Skip to content

JVM insert_many: homogeneous chunks cross as typed columns, not as JSON text - #392

Draft
tae898 wants to merge 3 commits into
mainfrom
perf/388-jvm-insert-many-typed
Draft

tae898 wants to merge 3 commits into
mainfrom
perf/388-jvm-insert-many-typed

Conversation

@tae898

@tae898 tae898 commented Nov 14, 2026

Copy link
Copy Markdown
Collaborator

What does this PR do?

On the JVM wheel, insert_many turned every chunk of 10,000 rows into one JSON text (json_bulk_dumps_tagged), which DocumentBatcher.insertManyJson parsed again into a JSON tree and copied key by key. Now a chunk whose rows are dicts with the same str keys in the same order, and whose columns each hold None and values of one exact type (int within 64 bits, float, bool, str, date, or a datetime without a time zone), crosses as typed columns and no text: one numpy buffer per int, float or bool column, one StringColumn per str column (what insert_columns already sends), one TemporalColumn per date or datetime column (what #383 added), and a boxed Object[] only for a numeric column that holds a null. The new bridge entry points are DocumentBatcher.insertManyColumns and insertManyColumnsParallel, which share fillRow with insertColumns. The synchronous and the parallel mode both take them.

Every other chunk keeps the JSON text and the per-row fallback exactly as it was. The chunk is judged as a whole, from the types alone, before any bridge array is built: a row that lacks a key, has another one or lists the keys in another order, a column that mixes types (an int beside a float), an int beyond 64 bits, a Decimal, bytes, numpy or pandas value, a datetime with a time zone, a lone surrogate, a list, tuple or dict (a date inside a list included), and a float vector for an ARRAY_OF_FLOATS property. A fallback chunk pays for the census and nothing else. The bridge jar and Python change; no native image is involved.

One decision in the Java side is not obvious. The JSON text stores a whole number as an Integer when it fits an int and as a Long beyond (JSONObject.parseNumber), while a numpy long[] column would store a Long for every number. A schemaless property would then be an Integer or a Long depending on which route carried its chunk, and a load with one fallback chunk would mix the two. So insertManyColumns narrows a whole number the way the text did. insertColumns is unchanged and keeps Long (a test pins it).

None stays a null property, never a missing one. A float NaN, an infinity and a subnormal cross in a double[] and are stored as the per-row path stores them (the old route sent those rows down the per-row path; the parity tests compare the stored values).

What the change allocates per chunk of at most 10,000 rows and per column: one Python list of the column's values (references, not copies); an int, float or bool column also one numpy array and one long[], double[] or boolean[] copy; a str column one UTF-8 byte buffer, one int[] of offsets and a boolean[] when there is a null (the insert_columns layout); a date or datetime column one numpy int64 array, one long[] and a boolean[] when there is a null; a numeric column with a null one Object[] of boxed values. The chunk is no longer held as one JSON text in Python, as a Java String copy of it, and as a parsed JSON tree of all its rows. The memory of a load stays bounded by the chunk, as before (#294). I have not measured memory.

Related issues

Refs #388 and #315.

Performance changes

Not measured yet. The change removes the text and the parse, and I have not timed it. The speed claim waits for a pre-registered timed A/B of a candidate wheel against 26.11.1.post3.

The figure to measure, so the A/B can be registered before it runs:

  • Operation: Database.insert_many(type_name, rows) on the JVM wheel (arcadedb-jvm), a list of dicts, default commit_every, synchronous mode. The parallel mode as a second figure.
  • Sizes: 1, 100, 10,000 (one chunk) and 100,000 rows (ten chunks). The unit of one operation is one insert_many call; report rows per second and the latency per call.
  • Shapes: a narrow row (an int, a float, a str), a wide row of nine typed properties with date and datetime columns (the shape of the insert_columns figure), and the same wide row with a null in some columns of every chunk.
  • Memory: peak RSS and anon growth of the load, as information figures.
  • No-change control: a shape the typed route refuses with the same row count, for example one row per chunk with an extra key, or a Decimal column. Both arms run the old route there, so the ratio should be one. An A/A run of the released wheel as the noise control.
  • Parity digest: the stored data of the old route and the new route, read back through SQL SELECT and compared property by property (names in the order the record lists them, the Java class of each value, the value), for each shape. tests/test_insert_many_typed_columns.py does this for ints around 2^31, 2^53 and 2^63, floats (NaN, infinities, subnormal, -0.0), strings, dates, datetimes, nulls, None against a missing key, key order, mixed columns, a date or Decimal inside a list, bytes, numpy scalars, a datetime with a time zone, vertices, an edge type, a duplicate key and a value no route can store.

Docs

docs/modules/ROOT/pages/how-to/bulk-loads.adoc (the section on the values the bulk path carries) says which chunks cross as columns on the JVM package and which keep the JSON text. The insert_many docstring says the same. README.md does not describe the transport.

Checklist

  • A regression test fails on the old code and passes on the new (the first commit holds the tests, the second the change; the dispatched run of the first commit is the evidence, see the comment below)
  • The test suite that the change can affect passes
  • uvx pre-commit run --files <changed files> passes (Bandit as CI runs it is clean too)

🤖 Generated with Claude Code

@tae898 tae898 added jvm The arcadedb-jvm package (JPype build) performance Speed or memory of the bindings, with a measurement python Pull requests that update python code labels Nov 14, 2026
@tae898 tae898 self-assigned this Nov 14, 2026
tae898 and others added 3 commits November 20, 2026 13:25
…nd the JSON route (refs #388)

Parity (differential) tests for a typed-column route of the JVM insert_many that does not exist yet, so they fail on the parent: each stores the same rows with the typed route switched off and as shipped, and compares every record property by property through SQL (names, Java class of each value, value), for ints around 2^31 and 2^53 and 2^63, floats (NaN, infinity, subnormal, -0.0), strings, dates, date-times, nulls, None against a missing key, key order, mixed columns, date and Decimal inside lists, bytes, numpy scalars and aware date-times. Also the crossing counts, the order of mixed chunks, the commit boundary, the parallel mode, vertices, edge types, a duplicate key and a value no route can store.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… one JSON text (refs #388)

A chunk whose rows are dicts with the same str keys in the same order, and whose columns each hold None and values of one exact type (int within 64 bits, float, bool, str, date, naive datetime), is read as columns: one numpy buffer per int, float or bool column, one StringColumn per string column, one TemporalColumn per date or datetime column, an Object[] only for a numeric column with a null. DocumentBatcher.insertManyColumns (and the parallel twin) builds the documents from them, and stores a whole number as the JSON text route did, an Integer when it fits an int and a Long beyond, so the stored type of a schemaless property does not depend on the route (insert_columns is unchanged and keeps Long).

Every other chunk keeps the JSON text and the per-row fallback exactly as before: the whole chunk is judged first, from the types alone, before any bridge array is built. Bridge jar and Python only, no native image.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… its whole numbers Long, as the per-row path stores them (refs #388)

The first CI run of the typed route (tagged 26.11.1, workflow_dispatch 43588034127, all 9 finished legs) failed 5 tests of
tests/test_insert_many_typed_columns.py, the same 5 on every leg. Cause and evidence:

- The parity failures (all_kinds-free, all_kinds_with_nulls-free, parallel all_kinds_with_nulls) differ in one value: row 11 (i = 0, f = -inf).
  The old route sends a row with a NaN, an infinity or a subnormal double down the per-row path (bulk_row_ok is False for rows 6, 9, 10 and 11 of
  that data, checked by script), and the per-row path stores a Python int as a Long. The text route stores the same number as an Integer.
  insertManyColumns narrowed every whole number to an Integer, so that one row differed. This is not engine-version specific: the per-row path
  is Python-side.
- Fix in the code, not the test: fillRow keeps the whole numbers of such a row a Long (carriedByText: a double[] or Object[] column that holds
  a non-finite or subnormal double in the row). The stored data of the typed route is now the old route's for every row. The A/B candidate wheel
  changes (one pass over the columns per row in fillRow).
- Two tests asserted the wrong thing. insert_columns still stores a Long: the type declared id INTEGER, which converts a Long to an Integer on
  any entry point, so it now declares nothing. The homogeneous-load test hard-coded how JPype prints a Java Boolean ('false') and a String
  ('str'); it now asserts the classes and the lower-cased texts.
- New parity cases pin the rule: whole numbers that fit an int beside NaN, infinity, both signs of the smallest subnormal, the largest
  subnormal, the smallest normal value, -0.0 and a plain float, with and without nulls, on both the sync and the parallel route.
- Docs: bulk-loads.adoc and the insert_many docstring state the exception.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@tae898
tae898 force-pushed the perf/388-jvm-insert-many-typed branch from 85332a9 to 38f015b Compare November 20, 2026 04:26

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

jvm The arcadedb-jvm package (JPype build) performance Speed or memory of the bindings, with a measurement python Pull requests that update python code

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant