Endpoint property projections leave node-record reads unbatched

perfloop-oss/helix-db · Under-Batching

https://perfloop.ai/t/oss/case_vqzxhf17zy

Verdict

VERIFIED · settled 2026-11-14 · pull request opened as HelixDB/helix-db#1300

What happened: The paired measurements met the required improvement.

Hypothesis

Native Values projections of endpoint properties batch the edge metadata but still await endpoint-node records one by one. When a batch contains many distinct endpoints, independent reads remain serialized. The local read pattern is confirmed, while elapsed-time savings, storage-cache conditions and production exposure are unknown.

project_values calls prefetch_rows, whose PropertySource::EdgeEndpoint branch collects only edge IDs. It does not collect the nodes referenced by those endpoints. RowValueResolver::element_property subsequently resolves each endpoint and calls element_row for the node; an uncached node reaches load_blob and property_bytes as an individual get. Ordinary current-element records are already batched. For a successfully completed batch of R edge rows selecting stored fields from both endpoints, this can leave as many as 2R individual node-record reads when every endpoint is distinct and not otherwise cached. Shared nodes reduce that count. Missing endpoints and identifier-only paths do not read node properties, and early errors can stop evaluation sooner.

The successful provisional probe in measurement receipt call_Oqq4P3MyJrFXyJzwibat59oY, output:1, ran `cargo test -p db --lib perfloop_projection_probe -- --nocapture --test-threads=1`. Values over 16 fixture-created edges with 32 distinct endpoint nodes and two endpoint-name selections produced 32 logical raw gets plus 16 multi-get keys. A comparator prefetched the known fixture node IDs through the existing resolver, returned the same values and produced zero raw gets plus 48 multi-get keys. Total requested keys were unchanged; the opportunity is grouping and overlap, not eliminating necessary data. These counters do not measure physical block reads or network round trips, and the comparator is not a complete repair.

Endpoint-property projection is documented in docs/database/helix-db/query-guides/projections.mdx:116-127. The landed batching implementation, https://github.com/HelixDB/helix-db/commit/ae6cdc2475c75fa824911db94c55fbd44e7ff68a, batches current-element records and edge endpoints but leaves the dependent node-record phase on demand. This is a distinct extension of that implementation. The bounded open-PR and landed-history checks did not identify active ownership of this phase. The README's Discord community was not accessible through the attempted public invite read, so off-host discussion remains a named evidence gap.

The first useful Case check is a provisional two-stage batch lookup driven by actual endpoint metadata, followed by native Values queries with distinct, shared, absent and corrupt endpoints. Compare logical read grouping and elapsed time, including warm-cache overhead. Error ordering, deadlines and memory-budget behavior need explicit comparison because eager node loading can change when failures surface. A failure to remove individual reads, unacceptable semantic changes or no useful end-to-end saving can reject the proposed move.

Change to test: Once edge endpoints are known, fetch the endpoint-node records required by selected property fields in bounded, deduplicated batches rather than individual reads. Preserve identifier-only and missing-endpoint skips and establish compatibility with the existing error, deadline and resource-accounting contracts.

Where it lives

perfloop-oss/helix-db · crates/db/src/execution/interpreter/stream/projection/dispatch.rs

Evidence

Endpoint Values on property-path data · 17 sample pairs

metric baseline candidate paired median change confidence range required result
ns/query 16100 11940 −24.9% (−4010) −5220 to −2060 gain > 0; gain > 0.05 × |baseline median|; arm medians separated PASSED
allocated_bytes/query 47610 41860 −12.1% (−5750) −5750 to −5750 loss ≤ 0.05 × |baseline median| PASSED
process_cpu_ns 380000000 300000000 −21.1% (−80000000) −130000000 to −40000000 loss ≤ 0.05 × |baseline median| PASSED
peak_rss_bytes 57917440 58044416 −184320 −1716224 to +847872 loss ≤ 0.05 × |baseline median| PASSED

Endpoint Values with distinct nodes · 18 sample pairs

metric baseline candidate paired median change confidence range required result
ns/query 3090500 1657000 −46.1% (−1424000) −1656000 to −1240000 gain > 0; gain > 0.05 × |baseline median|; arm medians separated PASSED
allocated_bytes/query 4788000 2057000 −57% (−2730000) −2731000 to −2730000 loss ≤ 0.05 × |baseline median| PASSED
process_cpu_ns 2600000000 1485000000 −43.1% (−1120000000) −1380000000 to −1000000000 loss ≤ 0.05 × |baseline median| PASSED
peak_rss_bytes 68997120 68859904 −145408 −2027520 to +1363968 loss ≤ 0.05 × |baseline median| PASSED

Endpoint Values on ring data · 18 sample pairs

metric baseline candidate paired median change confidence range required result
ns/query 38665 28995 −24.8% (−9605) −11630 to −6910 loss ≤ 0.05 × |baseline median| PASSED
allocated_bytes/query 96870 79790 −17.6% (−17080) −17080 to −17080 loss ≤ 0.05 × |baseline median| PASSED

Endpoint Values with shared nodes · 54 sample pairs

metric baseline candidate paired median change confidence range required result
ns/query 966650 967500 +5500 −20700 to +31200 loss ≤ 0.05 × |baseline median| PASSED
allocated_bytes/query 1610000 1609000 −0.1% (−1000) −1000 to −1000 loss ≤ 0.05 × |baseline median| PASSED
process_cpu_ns 900000000 910000000 +10000000 −30000000 to +40000000 loss ≤ 0.05 × |baseline median| PASSED
peak_rss_bytes 62969856 62887936 −202752 −1458176 to +765952 loss ≤ 0.05 × |baseline median| PASSED

Single stored endpoint field · 18 sample pairs

metric baseline candidate paired median change confidence range required result
ns/query 17575 15440 −12.3% (−2160) −3800 to −1470 loss ≤ 0.05 × |baseline median| PASSED
allocated_bytes/query 63900 63910 +10 +10 to +10 loss ≤ 0.05 × |baseline median| PASSED

Single endpoint ID · 48 sample pairs

metric baseline candidate paired median change confidence range required result
ns/query 13755 13710 −60 −790 to +590 loss ≤ 0.05 × |baseline median| PASSED
allocated_bytes/query 56830 56860 +0.1% (+30) +30 to +30 loss ≤ 0.05 × |baseline median| PASSED

Single node field · 33 sample pairs

metric baseline candidate paired median change confidence range required result
ns/query 13920 13940 +20 −1330 to +600 loss ≤ 0.05 × |baseline median| PASSED
allocated_bytes/query 57580 57610 +0.1% (+30) +30 to +30 loss ≤ 0.05 × |baseline median| PASSED

Checks: 5 of 5 passed. Verification: no defect found.

Timeline