[ShawnChen-Sirius]

Summary

Add the optional com.clickhouse.chdb:chdb-arrow module using Arrow Java 19.0.0 and the native Arrow C Data/C Stream ABI. The development binding is 1.0.0-rc.3-SNAPSHOT, pinned to the published chDB core v26.11.0-rc.3 and JNI ABI 3 on four platform packages. This PR does not publish a Java artifact; existing JDBC ResultSet/RowBinary behavior and the ordinary JDBC dependency tree remain unchanged.

Arrow Java API

• Register a caller-owned VectorSchemaRoot current batch or a one-shot, registration-owned ArrowReader as an in-memory SQL source with a closable arrowstream('name') fragment.
• Read core-materialized results as a typed Arrow Java reader, including schema for zero rows, or pull typed batches incrementally with ArrowQuery, partial-consumption close, cooperative cancellation, and connection/native-handle leases.
• Insert a batch or owned reader synchronously into an existing table via chdb_insert_arrow_stream. Source columns must have distinct names; the destination is validated and quoted. There is no implicit table creation or transaction guarantee.
• Expose explicit Arrow output type choices and ownership rules. This path does not use Arrow IPC and makes no unconditional zero-copy claim.
• Add a getting-started guide with matching Maven coordinates, JVM arguments, and input/output/insert examples.

Verification and CI follow-up

• Published core v26.11.0-rc.3 macOS arm64 asset, checksum, header, and staged JNI pair were verified without an engine-version override. LicenseInventoryIT matches 1081 components from that binary.
• On the staged macOS arm64 pair, the native Arrow suite passes on JDK 11, 21, and 26: 21 passing cases, one explicitly disabled core String-to-Int64 conversion regression, no other failures. The existing JDBC unit and integration suites were previously verified on JDK 11.
• The former fork PR Add optional Arrow Java integration pinned to chdb-core v26.11.0-rc.3 #37 showed Arrow tests passing on JDK 11/17/21 on macOS arm64, but failing at RootAllocator initialization on JDK 25 across the completed platform jobs: Arrow 19's Netty allocator reached EmptyByteBuf.memoryAddress() and threw UnsupportedOperationException. This change selects Arrow 19's official arrow-memory-unsafe backend instead of Netty. JDK 26 reproduced the former failure locally and passes after the change; JDK 25 itself still needs CI verification. JDK 26 warns about future removal of some sun.misc.Unsafe methods, so forward compatibility beyond the supported matrix is not implied.
• PR build.yml exercises the native Arrow suite on Linux x86_64/aarch64 and macOS arm64/x86_64 across JDK 11/17/21/25, archives reports and crash logs, and fails a platform job on any Maven failure. This same-repository PR also allows Macroscope to run; Add optional Arrow Java integration pinned to chdb-core v26.11.0-rc.3 #37's Macroscope check explicitly skipped cross-repository PRs.

Limits and follow-up

The disabled insert-conversion regression is not counted as passed. On published rc.3, an Arrow UTF-8 id="not-an-integer" inserted into an Int64 column reports one row written and stores 0, whereas ordinary SQL rejects it with CANNOT_PARSE_TEXT. Re-enable the regression after a core fix; do not silently coerce in Java. A2 sources are one-shot, A4 cancellation waits for an in-flight fetch, and A5 targets existing tables. Production use and a subsequent Java RC require review of this PR's four-platform results and normal publishing gates.

Note

Add experimental chdb-arrow module with materialized, streaming, and insert Arrow APIs

• Adds a new chdb-arrow Maven module providing ArrowSession for Arrow-based queries without IPC serialization: materialized queries (queryArrowMaterialized), lazy streaming queries (queryArrow via ArrowQuery), batch registration (registerBatch), and inserts (insertBatch)
• Adds JNI entry points in chdb_jni.cpp for Arrow query, stream open/fetch/cancel/close, registration, and insertion, with a new ArrowStreamHandle kind; bumps JNI ABI from 2 to 3
• Extends ChdbConnection to track Arrow queries and register cleanup hooks; close() now closes tracked Arrow queries and runs Arrow hooks before closing statements
• Adds ArrowOptions for type mapping (binary, dictionary, UTF-8 string) and CI runs Arrow tests in the Java-version matrix
• Updates engine baseline to v26.11.0-rc.3 across engine.properties, version comments, license inventory, and docs
• Risk: JNI ABI bump to 3 in ChdbNative.java requires a matching native shim; the Arrow module is documented as experimental and its session blocks other operations while an Arrow query is active

^{Macroscope summarized bacd685.}

[ShawnChen-Sirius]

@wudidapaopao, please review this PR

[wudidapaopao]

LGTM