[tae898]

Closes #228

On the native wheel, append_samples turned every column into a list with .tolist(), walked the timestamps again with int(), and sent the chunk as one JSON text. In the untimed probe of the l4 lane shape (100,000-point chunks, numpy columns, primitive=True), glue plus encode was 46.7% of the load wall (numbers in the issue). This PR sends the numeric columns by address.

What changes: a new library entry arcadedb_n_async_bin(handle, op, json, table, n_table) next to arcadedb_n_async. For append_samples, a one-dimensional numpy int, float or bool column, and an int or datetime64[ns] timestamp array, cross in an address table of (address, count) longs (the convention of arcadedb_n_insert_colp), and the JSON holds only a kind marker per column ("q" int64, "d" float64) and the sample count. The host tag column and every shape the text path converts differently keep the text: lists, float timestamps, other datetime64 units, 2-D and empty arrays, uint64 past the int64 range, a column whose length differs from the timestamps. Python side: codec.sample_array decides per column, NativeAsyncExecutor.append_samples builds the table. Java side: NativeExtras.asyncImpl (the old body of async, now shared by both entries) builds the same long[] and boxed Object[] columns the text gave and calls the same appendSamples.

What does not change: the stored samples are bit-identical to the text path (a float32 or float16 array widens to float64 exactly, a bool array is 0 and 1, a NaN is the canonical NaN the text gives, an int array into a DOUBLE column and a float array into a LONG column go through the same Number conversions). primitive=True keeps its meaning on the native build: the same length check, before the crossing, with the same message. A library without the entry (the loader sets lib.TS_BIN false) or ARCADEDB_NATIVE_TS_BIN=0 keeps the text path. The JVM wheel is not touched.

Tests (tests/test_native_timeseries_binary.py, native only, collected through conftest.py like the other native observers, no skips): the lane's shape takes arcadedb_n_async_bin once per chunk and its text holds no number of a numeric column, and the stored samples are read back by count, sums and a window; a matrix of dtypes (float64 with -0.0, NaN, infinities, 1e300 and 5e-324, float32, float16, int32 into DOUBLE, int64 extremes, uint8, bool, float into LONG) is stored bit-equal to the text path of the same call; timestamp arrays of int32, uint16, uint64, datetime64[ns] and a strided view are stored equal; non-contiguous and big-endian columns are stored as values; the entry choice for lists, float timestamps, datetime64[ms] (still a TypeError), a column of another length, primitive=True and a library without the entry; sample_array for 24 dtype cases; and the Java checks of a wrong address table (nothing is written). The CI run ids are in the first comment.

Speed: a timed A/B of the CI native wheel of this change (head 8c5f106, before the rebase below) against main's CI wheel, on the lane's shape (2,000,000 points of 100 hosts in chunks of 100,000, numpy columns, one wait_completion() at the end), measured the whole ingest at 0.370 of main's time (95% interval 0.362 to 0.390, 11 clean paired runs, clean A/A control). The Java side still boxes each value once, the engine's TimeSeriesBatch route is a possible follow-up.

Docs: this head adds a section to the bulk-loads how-to (which numpy dtypes cross by address, what keeps the text path, the opt-out, and the figure above with the shape it was measured on) and a docstring on the native append_samples. Docs and docstring only.

Rebase: #224 merged and touched lib.py, extras.py and codec.py (the textual conflicts mentioned before); this branch is rebased onto the main that has it, and the conflicts are resolved by keeping both sides.

🤖 Generated with Claude Code

[tae898]

CI on head 4cb904dbdb, read at 06:16 KST on 2026-11-04. The native build has compiled the new entry: the dispatch run of test-native.yml (41716062800) built and gated the wheels for linux-x86_64, linux-aarch64 and windows-x64; macos-arm64 was still building, and the parity tests (which include tests/test_native_timeseries_binary.py) start after the wheel jobs, so they have not run yet. The pull_request JVM run (41716066631) is green: the new test file is collected on the native backend only. The pull_request native run (41716066558) was skipped because the PR is a draft.

The test results will be added here when the dispatch run finishes. The timed A/B (DECISIONS #240, wheel versus wheel) is prepared and not started.

[tae898]

Timed A/B on head 8c5f106 (native build; arm A = main's CI wheel 7e64c5e (run 41659112491), arm B = this PR's CI wheel (run 41741554269), A/A control; laptop timed lane, tools/ab.py --noise, ABBA, round 0 dropped). B/A median with its 95% interval (below 1 = this PR is faster or smaller):

figure	role	B/A median [95% CI]	A/A median [95% CI]
time-series ingest wall (100 hosts, 2,000,000 points, numpy columns)	gating	0.370 [0.362, 0.390]	1.006 [0.991, 1.026]
document insert (1,000,000 documents through insert_many, which crosses neither async entry)	control	1.020 [1.016, 1.022]	1.001 [0.999, 1.002]
the append_samples calls alone	info	0.212 [0.207, 0.224]	1.008 [0.997, 1.022]
the final wait	info	1.168 [1.149, 1.201]	1.009 [0.994, 1.055]
the harness's own column building (not bindings code)	info	1.048 [1.013, 1.122]	0.999 [0.975, 1.068]
peak RSS	info	0.990 [0.986, 0.998]	1.001 [1.000, 1.002]

Clean pairs per figure: 11. By the rule written before the run (gating upper end below 0.90, the control inside [0.97, 1.03], clean A/A) this is a SHIP: the ingest takes 0.370 [0.362, 0.390] of main's wall time, with the append_samples calls themselves at 0.212 [0.207, 0.224]. The final wait is longer (1.168 [1.149, 1.201]); it is part of the ingest wall above.

Scored at round 12, where the pre-written stopping rule ends this study. A file-name bug in the study's scorer (not in this PR) let the run continue to round 30; those extra rounds are not used.

The merge waits for the end of the current batch of timed studies that pin main (merging now would move their pins); the PR leaves draft at that point, with its docs.