Strict Zero-Copy PyArrow Architecture & Shared-Nothing I/O
1. Context & Legacy Architectural Bottlenecks
Traditional data ingestion pipelines rely on dynamic Python list[dict] constructs to aggregate document chunks and entity relationships across multiprocessing boundaries. Heavy dictionary objects are constructed in worker processes, passed over IPC boundaries to an orchestrator, and accumulated in volatile memory before flushing.
At enterprise scale (1,000,000+ legal files), this architecture fundamentally fails due to three compounding bottlenecks:
- Dynamic Key Hashing: Python dictionaries compute hash values for every string key in every row. In a 1.25M-chunk corpus with 20 metadata keys, this burns hundreds of millions of CPU cycles solely in Python hash table lookups.
- IPC Multiprocessing Serialization: Passing massive lists of Python objects across process boundaries requires
pickleserialization and deserialization, creating severe memory bloat and starving the orchestrator. - Pandas Poison Pills: Consolidating relational data via Pandas
.df()shatters contiguous N-dimensional embedding arrays (e.g., 128-D or 256-D vectors) into fragmented Python objects, incurring catastrophic deserialization penalties when reconstructing PyArrow tables.
Eliminate dynamic Python dictionaries and Pandas entirely from the batch-processing engine. Workers construct flat, strongly-typed columnar arrays, zero-copy contiguous C-buffers directly into Apache Arrow, and flush partitioned Parquet files directly to disk without orchestrator data transport.
2. Five Pillars of the Zero-Copy Substrate
- State-Level Flat Columnar Storage: Dynamic dictionaries are banned. Workers construct strongly-typed State classes (e.g.,
P1DocsState,P3EdgesState) containing pre-allocated flat columnar Python lists (list[str],list[int],list[float]). - Native NumPy to Arrow Vectorization: Dense embeddings generated via static vector models are maintained strictly as C-contiguous buffers. They are directly raveled (
.ravel()) and zero-copied into apa.FixedSizeListArray(128)orpa.FixedSizeListArray(256), bypassing Python object iteration entirely. - Shared-Nothing Worker Parquet Flushes: Workers write their PyArrow tables directly to disk as partitioned Parquet files (e.g.,
docs_p1_w0_b1.parquet). The orchestrator never touches raw record payloads; it receives only lightweight telemetry markers. - Perfect Round Batching: Dispatchers distribute task batches via an O(1) mathematical partitioning algorithm calculated by dividing raw byte limits (Phase 1) or chunk counts (Phase 3). This guarantees that all 16 P-Cores remain 100% saturated without modulo stragglers.
- DuckDB Native CSR Consolidation: Python loop joins are forbidden. DuckDB mounts the partitioned Parquet files directly, utilizes native C++
CREATE SEQUENCEto assign globally contiguous entity integers, and computes topological graph edge joins in SQL. Arrow tables are fetched natively via.fetch_arrow_table().
# Contiguous C-Buffer Zero-Copy into Arrow FixedSizeListArray
# Eliminates .tolist() object unpacking: 21x faster ingestion
raw_embeddings = np.ascontiguousarray(embeddings_matrix, dtype=np.float32)
flat_buffer = pa.py_buffer(raw_embeddings.ravel())
arrow_vector_array = pa.FixedSizeListArray.from_arrays(
pa.Array.from_buffers(pa.float32(), raw_embeddings.size, [None, flat_buffer]),
dim=256
)