Skip to content

fix(liquid): charge entries for the memory they hold - #101

Merged
anoop-narang merged 4 commits into
mainfrom
fix/liquid-memory-charge
Nov 19, 2026
Merged

anoop-narang merged 4 commits into
mainfrom
fix/liquid-memory-charge

Conversation

@zfarrell

@zfarrell zfarrell commented Nov 17, 2026 •

Copy link
Copy Markdown

Liquid entries are now charged within about 10% of the heap they hold.

  • Buffers stay in the block (liquid: decode copies misaligned buffers and keeps the block #77). The serialized layout pads every buffer to its alignment relative to an aligned block start, so decode slices buffers in place instead of Vortex copying misaligned ones while the block stays alive. The serialized format moves to version 2; a version 1 block is not readable.
  • Per-node heap is charged (liquid: entries are charged without their per-node overhead #76). The charge is computed once at decode: the block, buffers outside it, and a fixed allowance per node (NODE_HEAP) and per FSST symbol table (FSST_SYMBOL_TABLE_HEAP), measured with a counting allocator. tests/liquid_array_memory.rs checks charges against real heap and fails if the allowances drift, e.g. after a Vortex upgrade; the constants' doc says how to re-derive them.
  • FSST = / != no longer grow the entry (liquid: FSST = and != grow an entry by 160 KiB uncharged #78). They evaluate on a copy with its own symbol table, so the ~160 KiB compressor Vortex builds for the literal is dropped with the copy. Trade-off: the compressor is rebuilt on each evaluation, a few µs per batch, instead of being kept per entry uncharged.

Small batches of high-entropy strings are over-charged by about 2 KB (a full symbol table holds less than the allowance). The error is deliberately on the safe side: over-charging costs cache space, under-charging overruns memory.

Closes #77
Closes #76
Closes #78

https://claude.ai/code/session_01LbJrgYNLF7FxwMy5VSHXar

@zfarrell
zfarrell marked this pull request as ready for review November 17, 2026 20:35
@zfarrell
zfarrell requested a review from a team as a code owner November 17, 2026 20:35
@zfarrell
zfarrell requested review from shefeek-jinnah and removed request for a team November 17, 2026 20:35
zfarrell and others added 4 commits November 18, 2026 21:19
Liquid arrays were serialized as Vortex IPC messages, which place
buffers with no padding. Decoding copied every buffer that landed at an
offset its alignment rejects, while the rest kept the whole block
alive, so the copied bytes were held twice and charged once: up to
1.51x the charge for random binary.

Write the array segment with Vortex's zero-copy padding instead, in an
allocation aligned for its largest buffer, and realign a block handed
to from_bytes once if its allocation is not aligned enough. The format
version moves to 2; the disk tier only reads blocks this process wrote.

Fixes #77
A Liquid entry was charged nbytes(), the sum of its buffer lengths. That
leaves out the serialized block's framing and padding, each Vortex
node's allocation and statistics, and the FSST symbol table the decoder
re-pads to its full 256 entries. For well-compressed columns that was
most of the entry: low-cardinality strings held 2.2-2.4x their charge,
constant and sequential columns 15x.

Compute the charge once at decode: the block if any buffer still points
into it, every buffer that does not, and a measured per-node and
per-FSST-node overhead. A counting-allocator test, scoped to its own
test binary, holds the charge within 10% + 256 bytes of the real heap
in both directions across 28 column shapes.

Two tests sized their budget from the old under-charge: the 128-row
string OR test now uses 1024 rows so its Liquid form is still the
smaller, and the URL snapshot keeps one fewer entry in memory.

Fixes #76
FSST evaluates = and != by compressing the literal, and memoizes the
160 KiB compressor it builds in the symbol table that every slice and
filter of the node shares. The first such predicate on a cached entry
grew it for the rest of its life, uncharged: 1.8x the whole charge of a
16-character hex column.

Give the comparison a private copy of each FSST node's symbol table, so
the compressor is freed with the predicate's array. Pre-charging every
FSST entry for a compressor most never build would over-charge them,
and re-charging after growth needs a hook from the array into the
budget. Rebuilding the compressor costs 15-30 us per 8192-row batch.

Fixes #78
- The predicate test asserts its columns are FSST-compressed, so an
  encoding change cannot make it pass without exercising FSST.
- Small string batches must be charged at least the heap they hold. A full
  FSST symbol table is over-charged by about 2 KB, which costs cache space
  rather than memory.
- Note how to re-derive NODE_HEAP and FSST_SYMBOL_TABLE_HEAP after a
  Vortex upgrade.
- Regenerate the url_selection_and_ordering snapshot after the rebase.

Claude-Session: https://claude.ai/code/session_01LbJrgYNLF7FxwMy5VSHXar
@anoop-narang
anoop-narang force-pushed the fix/liquid-memory-charge branch from c7555e6 to 1b7a6f1 Compare November 18, 2026 16:24
@anoop-narang
anoop-narang changed the base branch from fix/eviction-accounting to main November 18, 2026 16:24
@anoop-narang anoop-narang reopened this Nov 18, 2026
@codecov

codecov Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 98.23789% with 4 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/core/src/liquid_array/array.rs 98.13% 2 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

@github-actions

Copy link
Copy Markdown

📊 Benchmark Comparison

Current: 178598c4 (Liquid) vs Baseline: 178598c4 (DataFusionDefault)

Query Cold Time Δ Warm Time Δ CPU Time Δ
Q1 3.0ms (2.0ms) +50.0% 0.000ms (0.000ms) +0.0% 0.000ms (0.000ms) +0.0%
Q2 8.0ms (5.0ms) +60.0% 3.0ms (4.5ms) -33.3% 7.0ms (6.5ms) +7.7%
Q3 14.0ms (11.0ms) +27.3% 5.5ms (13.0ms) -57.7% 3.0ms (24.0ms) -87.5%
Q4 12.0ms (10.0ms) +20.0% 4.0ms (9.0ms) -55.6% 3.0ms (19.5ms) -84.6%
Q5 57.0ms (50.0ms) +14.0% 38.5ms (45.0ms) -14.4% 4.0ms (20.5ms) -80.5%
Q6 220.0ms (95.0ms) +131.6% 65.0ms (96.0ms) -32.3% 22.0ms (77.5ms) -71.6%
Q7 1.0ms (1.0ms) +0.0% 0.000ms (0.000ms) +0.0% 0.000ms (0.000ms) +0.0%
Q8 7.0ms (6.0ms) +16.7% 4.0ms (5.5ms) -27.3% 8.0ms (6.0ms) +33.3%
Q9 81.0ms (76.0ms) +6.6% 67.5ms (79.5ms) -15.1% 6.0ms (39.5ms) -84.8%
Q10 93.0ms (84.0ms) +10.7% 66.0ms (81.5ms) -19.0% 5.0ms (57.5ms) -91.3%
Q11 37.0ms (23.0ms) +60.9% 18.0ms (23.0ms) -21.7% 33.5ms (29.5ms) +13.6%
Q12 42.0ms (25.0ms) +68.0% 19.0ms (25.0ms) -24.0% 34.0ms (35.5ms) -4.2%
Q13 238.0ms (101.0ms) +135.6% 80.5ms (99.0ms) -18.7% 48.5ms (79.5ms) -39.0%
Q14 455.0ms (126.0ms) +261.1% 101.5ms (133.5ms) -24.0% 65.5ms (97.0ms) -32.5%
Q15 363.0ms (102.0ms) +255.9% 81.0ms (97.5ms) -16.9% 57.0ms (91.0ms) -37.4%
Q16 111.0ms (104.0ms) +6.7% 97.5ms (118.5ms) -17.7% 4.0ms (19.5ms) -79.5%
Q17 581.0ms (220.0ms) +164.1% 231.5ms (219.0ms) +5.7% 63.0ms (96.0ms) -34.4%
Q18 699.0ms (211.0ms) +231.3% 261.5ms (219.0ms) +19.4% 83.5ms (96.0ms) -13.0%
Q19 1.02s (403.0ms) +152.6% 407.5ms (404.5ms) +0.7% 89.5ms (138.0ms) -35.1%
Q20 13.0ms (11.0ms) +18.2% 3.0ms (10.0ms) -70.0% 8.0ms (18.5ms) -56.8%
Q21 645.0ms (173.0ms) +272.8% 474.0ms (176.5ms) +168.6% 283.5ms (265.0ms) +7.0%
Q22 1.18s (169.0ms) +600.6% 619.0ms (162.5ms) +280.9% 158.0ms (336.0ms) -53.0%
Q23 1.93s (447.0ms) +331.5% 1.72s (460.0ms) +273.7% 510.0ms (712.5ms) -28.4%
Q24 23.24s (868.0ms) +2577.5% 981.5ms (879.5ms) +11.6% 590.0ms (2.43s) -75.7%
Q25 334.0ms (69.0ms) +384.1% 16.0ms (58.5ms) -72.6% 44.5ms (115.0ms) -61.3%
Q26 160.0ms (43.0ms) +272.1% 17.5ms (43.0ms) -59.3% 48.5ms (80.0ms) -39.4%
Q27 320.0ms (56.0ms) +471.4% 25.5ms (58.0ms) -56.0% 71.5ms (113.5ms) -37.0%
Q28 823.0ms (214.0ms) +284.6% 951.0ms (212.0ms) +348.6% 200.5ms (268.5ms) -25.3%
Q29 1.44s (971.0ms) +48.6% 1.08s (973.0ms) +10.9% 419.0ms (325.5ms) +28.7%
Q30 28.0ms (29.0ms) -3.4% 21.0ms (27.0ms) -22.2% 6.0ms (20.5ms) -70.7%
Q31 801.0ms (130.0ms) +516.2% 83.0ms (124.5ms) -33.3% 80.0ms (166.5ms) -52.0%
Q32 970.0ms (114.0ms) +750.9% 139.0ms (115.0ms) +20.9% 114.0ms (170.0ms) -32.9%
Q33 362.0ms (435.0ms) -16.8% 340.0ms (356.5ms) -4.6% 7.0ms (66.0ms) -89.4%
Q34 958.0ms (402.0ms) +138.3% 452.5ms (411.0ms) +10.1% 130.5ms (260.5ms) -49.9%
Q35 861.0ms (418.0ms) +106.0% 511.5ms (406.5ms) +25.8% 145.5ms (263.5ms) -44.8%
Q36 103.0ms (113.0ms) -8.8% 85.0ms (99.0ms) -14.1% 4.0ms (20.0ms) -80.0%
Q37 308.0ms (98.0ms) +214.3% 74.5ms (95.0ms) -21.6% 26.5ms (71.0ms) -62.7%
Q38 70.0ms (48.0ms) +45.8% 27.0ms (42.0ms) -35.7% 16.0ms (23.0ms) -30.4%
Q39 275.0ms (48.0ms) +472.9% 26.5ms (48.5ms) -45.4% 17.5ms (73.0ms) -76.0%
Q40 684.0ms (185.0ms) +269.7% 212.5ms (173.5ms) +22.5% 59.5ms (125.0ms) -52.4%
Q41 25.0ms (18.0ms) +38.9% 10.0ms (20.5ms) -51.2% 6.0ms (19.5ms) -69.2%
Q42 19.0ms (18.0ms) +5.6% 9.0ms (18.0ms) -50.0% 6.5ms (15.5ms) -58.1%
Q43 17.0ms (17.0ms) +0.0% 10.5ms (15.5ms) -32.3% 7.5ms (11.0ms) -31.8%

⚠️ LiquidCache is slower on 8 queries (warm)

  • Q28: warm +348.6% (951.0ms vs 212.0ms)
  • Q22: warm +280.9% (619.0ms vs 162.5ms)
  • Q23: warm +273.7% (1.72s vs 460.0ms)
  • Q21: warm +168.6% (474.0ms vs 176.5ms)
  • Q35: warm +25.8% (511.5ms vs 406.5ms)
  • Q40: warm +22.5% (212.5ms vs 173.5ms)
  • Q32: warm +20.9% (139.0ms vs 115.0ms)
  • Q18: warm +19.4% (261.5ms vs 219.0ms)

Compared Liquid vs DataFusionDefault on the same runner
Regressions: warm-time increases of at least 15%. Cold Time: first iteration; Warm Time: median of remaining iterations.

@anoop-narang
anoop-narang merged commit 3fe46aa into main Nov 19, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants