[tae898]

What does this PR do?

On the JVM wheel, insert_arrow, insert_dataframe and insert_columns (called by the first two) made one LocalDateTime.ofEpochSecond or LocalDate.ofEpochDay JPype call per cell of every timestamp or date column, and then _column_to_java converted every element of that list again. A million-row timestamp column was two million JPype calls. The native wheel moved the same columns to one crossing in #333 (#316).

Now a timestamp or date column of a batch is the integer epoch values in one long[] (plus one boolean[] when a row is null), wrapped in a new bridge class TemporalColumn, built with one call per column and batch. DocumentBatcher builds each LocalDateTime or LocalDate as it fills the document of that row, the way StringColumn does for text. The old per-cell path is gone. The wheel carries its own bridge jar, so there is no fallback for an older one.

The Java side, in src/java/com/arcadedb/python/TemporalColumn.java:

public static TemporalColumn dateTimes(long[] ticks, long ticksPerSecond, boolean[] nulls)
public static TemporalColumn dates(long[] ticks, long ticksPerDay, boolean[] nulls)
public int rows()
public Object get(int i)   // LocalDateTime or LocalDate, or null for a null row

DocumentBatcher.checkColumns and fillRow take it beside long[], double[], boolean[], Object[], FloatVectors.Matrix and StringColumn. In Python, dataframe._temporal_column replaces _temporal_to_java, and core._column_to_java hands the column over as it is.

How the stored value is kept

• A date-time is a UTC wall clock. A timestamp with a zone is already UTC epoch time and a timestamp without one is the clock it shows, so both read the integer, in the unit of the column (ticksPerSecond 1, 1,000, 1,000,000 or 1,000,000,000).
• Precision: whole seconds are floorDiv(tick, ticksPerSecond) and the rest is floorMod(...) * (1e9 / ticksPerSecond) nanoseconds, so a nanosecond tick keeps its nanoseconds and a tick before the epoch is the last tick of 1969. This is the np.divmod arithmetic of the old code, now in Java.
• Dates: date32 is days (ticksPerDay 1) and date64 is milliseconds (ticksPerDay 86,400,000), floored as the old numpy // was.
• Nulls: a null row holds 0 in the array and a flag in the boolean[], which is only sent when there is a null. get(i) returns null for it.
• A value past the years of java.time still raises before a row is written, as it did in Python: the factory builds the value of the smallest and of the largest tick of the non-null rows, and the rest lies between them.
• A list of Python datetime objects passed to insert_columns is not touched: it still crosses value by value. A numpy datetime64 column is still refused there.

Related issues

Part of #315.

Performance changes

Not measured yet. The change removes the per-cell crossings, which the tests count, but I have not timed it. The speed claim waits for a timed A/B of a candidate wheel against 26.11.1.post2, as CONTRIBUTING asks.

How I checked it

The tests come first in the first commit and the change in the second, so a run of the first commit shows them failing on the old code.

• tests/test_arrow_temporal_column_jvm.py (JVM wheel only, listed in NATIVE_NOT_APPLICABLE): two tests count what one load does and fail on the old code. One asserts no java.time call and no convert_python_to_java per cell for a 600-row batch of seven temporal columns (the old code makes one of each per cell). The other asserts that each of the seven columns reaches the bridge as one TemporalColumn per batch (500, 500 and 300 rows). The rest compare the bridge column with the per-cell reading it replaced (every unit, random ticks, negative ticks, nulls), pin the refusal of a bad unit, and pin that a timestamp[s] of 2**62 is refused with nothing written. No test asserts on time.
• tests/test_dataframe_ingest.py::TestTemporalColumns (both wheels): every timestamp unit with no zone, with UTC and with a zone, to the nanosecond through a DATETIME_NANOS property read back with format('yyyy-MM-dd HH:mm:ss.SSSSSSSSS'); date32 and date64 before 1970, declared and undeclared; a load in batches of six timestamp and two date columns with nulls into a document type, a document type with parallel=True and a vertex type; a pandas frame (with a NaT and a zone) and a Polars frame. The expected values come from the integers, never from a read of the database.
• Run on this branch, light checks only: uvx pre-commit run --files on the changed files (black, isort, ruff, prettier on the Java and the adoc, whitespace), bandit, pyflakes, and a cross-check of the expected wall clocks against numpy datetime64.
• Not run locally, so CI has to prove them: the Java compiles (no JDK 25 on this machine for it), and every test above, on both wheels. A draft pull request skips the platform legs, so they start when it is marked ready.

CI: to be filled in once the legs have run.

Docs

docs/modules/ROOT/pages/how-to/bulk-loads.adoc: one paragraph on how a timestamp or date column crosses on arcadedb-jvm. No other page or the README describes it, and no documented behavior changes.

Checklist

• A regression test fails on the old code and passes on the new (the first needs the CI run of the first commit to be seen)
• The test suite that the change can affect passes (CI)
• uvx pre-commit run --files <changed files> passes

🤖 Generated with Claude Code

[tae898]

This change shipped in 26.11.1.post3 (on PyPI since 2026-11-14) through the release line, which #387 merged into main with a merge commit. The release line carries the same change as its own commits, so I close this draft. The measurements are on #315.