Skip to content

perf: combine small columnar batches before caching them - #6988

Open
andygrove wants to merge 7 commits into
apache:mainfrom
andygrove:perf/cache-coalesce-small-batches
Open

andygrove wants to merge 7 commits into
apache:mainfrom
andygrove:perf/cache-coalesce-small-batches

Conversation

@andygrove

@andygrove andygrove commented Oct 14, 2026 •

Copy link
Copy Markdown
Member

Which issue does this PR close?

Closes #6950.

Rationale for this change

The columnar cache write stores each input batch as one cached batch, and nothing bounds how small those batches are. A shuffle read returns at least one batch per map output block, so a relation cached straight from a shuffle over many map tasks holds thousands of small batches. Each carries its own message metadata, compression framing and statistics row, and every read of the cache pays for the batch count. #6950 has the details.

What changes are included in this PR?

  • A new CacheBatchCoalescer sits in front of the columnar write in ArrowCachedBatchSerializer.convertColumnarBatchToCachedBatch. It passes a batch through when two things hold: the batch is Arrow-backed and laid out the way the reader reads it, which is the test the write already used to store a batch as it stands, and it holds at least half of the smaller of spark.sql.inMemoryColumnarStorage.batchSize and spark.comet.batchSize. The second is the number of rows a Comet operator puts in a full batch, so a full native batch reaches the writer without a copy at any spark.comet.batchSize. With the defaults (10000 and 8192) the threshold is 4096 rows.
  • Every other batch is copied with ArrowWriter.writeColumns into batches of batchSize rows, the size the row path cuts at, and is split where it crosses that size. A small batch is worth the copy. A batch of Spark's own column vectors, or one laid out differently from the reader, was already being copied into Arrow one batch at a time, so combining it adds no copy. The copy reads each column through the ColumnVector interface, so it handles dictionary-encoded and nested columns, and offsets that don't start at zero, as a native producer's sliced arrays can have. Arrow's VectorAppender assumes offsets start at zero, which is why this doesn't use it.
  • Row order is kept, so a sorted cache stays sorted: the rows copied so far are emitted before a batch that passes through. A large input is copied one output batch at a time, as the consumer asks for them, so the allocation does not grow with the number of pieces it splits into, and the input does not advance until it has been copied in full, because a native producer such as CometExecIterator releases the batch it returned last when it is asked for the next. The coalescer owns the batches it builds and releases each one when the next is requested, and anything still open when the task completes.
  • The row path is unchanged, since it already cuts at batchSize.
  • The in-memory cache guide's "Storage format" section describes the batch sizes. It also says that Spark's own format ends a batch at about 4 MiB (ColumnBuilder.MAX_BATCH_SIZE_IN_BYTE), while Comet cuts by row count alone, so a relation of wide rows is stored in larger batches than Spark's format would use.

How are these changes tested?

Four new tests in CometInMemoryCacheSuite, and a new CacheBatchCoalescerSuite that runs the coalescer directly:

  • "combines small columnar batches in order" feeds the serializer a mix of Arrow and Spark-vector batches at a batch size of 1000. The input releases each batch when it is asked for the next, as a native producer does. The test checks the exact cached batch sizes (600, 9000, 700, 1000, 1000, 1000 and 100) and every row in order.
  • "stores a full native batch as it stands whatever its size" caches 300-row Arrow batches at a cache batch size of 1000. With spark.comet.batchSize at 8192 they are combined into one batch, and at 300 they are stored as they stand.
  • "combines the small batches of a shuffle read" caches a 20,000-row relation with nested columns straight from a shuffle over 20 map tasks into 2 partitions. Without this change it caches 40 batches of about 500 rows. With it there are at most 4, and the rows match Spark's.
  • "keeps a sorted cache sorted whatever the size of its batches" caches a sort whose native batches hold 100 rows, which is a full batch there, and checks that each partition reads back in order.

CacheBatchCoalescerSuite splits one 4096-row Spark-vector input of four string columns into batches of 10 rows under a 4 MiB allocator limit, checks every row in order, and checks that the allocator is empty once the coalescer is closed. Splitting the whole input up front runs out of memory in it. It also covers rows left over from one input filling the next output batch, and empty inputs. Five more cases cover the release paths of a coalescer that is not drained:

  • closing after taking one batch from a 25-row input at a target of 10, which leaves the input partly copied and the batch handed out still open;
  • closing after hasNext has built a batch that nothing took;
  • a closed coalescer with input left reports no more batches, and closing twice is harmless;
  • an allocator limit that fails while the output batch is being started, after two of its four columns are allocated;
  • an allocator limit that fails while rows are being copied, once they outgrow the data buffers.

Each case checks that the allocator is back to zero. A batch being filled is never open between calls, since hasNext finishes it before it returns, so it is only open at close when a copy throws, which the last case covers.

Each of five mutants fails at least one of these tests: removing the coalescer, passing through at the threshold instead of half of it, not splitting at the batch size, emitting a pass-through batch ahead of the rows combined before it, and passing Spark-vector batches through. So do two mutants of the threshold, one using only the cache's batch size and one using only spark.comet.batchSize, and mutants that leave out the release of the batch handed out, of the batch that was ready, of the batch being filled, or of the vectors of a failed start, or that let a closed coalescer keep reading.

CometInMemoryCacheSuite, CometInMemoryCachePruningSuite, the Kryo suite, CachedBatchRowIteratorSuite and CacheBatchCoalescerSuite pass locally on Spark 4.1 (119 tests) and 3.5 (115 tests, 4 canceled). Scalafix and the strict-warnings build pass on 3.5.

I measured #6950's shape with a probe that isn't part of this PR. It reads 5M rows of four columns (bigint, int, double and string) from 200 Parquet files as 200 splits, and caches them with repartition(50, $"a"). Both caches were built and read in the same JVM, interleaved. The first was built at a batch size of 2, so every one of these batches passes through, which is the layout main produces. The figures are medians of 3 builds and 9 reads, on an Apple M3 Max with JDK 17.0.10, Spark 4.1 and a debug native library:

main's layout This PR
Cached batches 10000, of 250 to 775 rows 510, of 5000 to 10000 rows
Payload 36.1 MiB 32.8 MiB
Storage memory 44.0 MiB 33.2 MiB
Build 3961 ms 3815 ms
Aggregate through CometInMemoryTableScan 369 ms 289 ms
noop write of every row 141 ms 113 ms
Aggregate by Spark operators 315 ms 299 ms

On a copy of the same rows in random order, which compresses less well, storage memory went from 77.3 to 66.0 MiB, the build from 4.4 to 3.9 seconds, and the aggregate from 394 to 322 ms. Separate runs of main and this PR gave the same layouts. From a single map task, the same relation caches the same 633 full batches with or without this PR.

A second probe measures batches that come straight from native operators. It caches 5M rows of six columns from a native range and projection, with zstd, under AQE, on a release native library, and times the build and then an aggregate over every column. The two layouts alternate for 7 rounds in one JVM, and the figures are medians. At a spark.comet.batchSize of 8192, the default, both layouts are the same 624 batches. At 4096, a threshold of half the cache's batch size would have copied every full native batch:

Batch size 4096 main's layout Half of the cache's batch size This PR
Cached batches 1232 512 1232
Payload 54.3 MB 57.5 MB 54.3 MB
Build 1191 ms 1249 ms 1207 ms
Aggregate through CometInMemoryTableScan 357 ms 322 ms 351 ms

Copying full batches made the aggregate 10% faster and the build 5% slower, with a payload 6% larger, so this PR leaves them alone and combines only the batches that are small for their producer.

The columnar cache write stored each input batch as one cached batch,
and nothing bounds how small those batches are. A shuffle read returns
at least one batch per map output block, so a relation cached straight
from a shuffle over 200 map tasks into 50 partitions held 10000 batches
of about 500 rows, each with its own message metadata, compression
framing and statistics row.

CacheBatchCoalescer now sits in front of the columnar write. An
Arrow-backed batch laid out the way the reader reads it is passed
through when it holds at least half of
spark.sql.inMemoryColumnarStorage.batchSize, so full native batches are
still written without a copy. Every other batch is copied through
ArrowWriter.writeColumns into batches of batchSize rows, the size the
row path cuts at: a small batch is worth the copy, and a batch of Spark
column vectors was already copied into Arrow. Row order is kept, and
each batch is copied before the input advances, because a native
producer releases the batch it returned last when asked for the next.

Closes apache#6950.
@andygrove andygrove added enhancement New feature or request performance run-spark-4.1-tests Run the Spark 4.1 SQL tests on this pull request instead of waiting for the merge queue labels Oct 14, 2026

@sunchao sunchao left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the complete five-file diff at f1f57aeef84a9242848fadef250b47bcbc1792f6 against 7d8d9b1544b734c85a93cca2cc9d5380ad70accd. The PR is open and not a draft. The snapshot and refreshed GitHub discussion contain no existing reviews or comments.

Routed skills: review-comet-pr, review-comet-ffi-pr, and review-comet-memory-pr. One introduced P2 issue was reproduced.

Summary

  • Prior state and problem: Columnar cache writes stored each input batch separately. Shuffle inputs containing many small batches therefore accumulated IPC framing, statistics, and per-batch read costs.
  • Design approach: CacheBatchCoalescer combines small inputs and normalizes incompatible layouts before encoding. Compatible Arrow batches containing at least half the configured target row count pass through.
  • Correctness: The iterator copies inputs before advancing their producer and flushes preceding rows before pass-through batches. Focused checks preserved ordering, nulls, nested values, sliced vectors, decimals, pre-epoch timestamps, signed zero, and NaN. No value or ordering defect meeting the reporting bar was identified.
  • Compatibility analysis: Checked Spark sources for 3.4.3, 3.5.9, 4.0.4, 4.1.3, and 4.2.0. Their cache contracts retain plan ordering and expose columnBatchSize, defaulting to 10000. Timestamp getters preserve raw microseconds. Compared with branch-1.1, coalescing intentionally changes columnar batch boundaries without changing the IPC format or supported-type fallback.
  • Key design decisions: Reusing the existing layout predicate preserves the direct-write path for ordinary 8192-row native batches. Using ArrowWriter.writeColumns avoids a separate copying implementation and retains the existing timestamp labeling.
  • Implementation sketch: A partition-local iterator manages pending output, completed roots, and a held pass-through batch. It releases owned output on advancement and task completion, while input ownership stays with the producer.
  • Performance: The reported reduction in cached batches fits the mechanism, but I did not independently rerun the benchmark. The bounded reproduction found a regression: splitting one Spark-vector input eagerly retains every fragment, multiplying Arrow allocation overhead before encoding can consume anything.
  • Design: Placing coalescing immediately before cache encoding is well scoped. Splitting should remain incremental, retaining the current input and its row offset until each output has been consumed.
  • Abstraction & complexity: A dedicated iterator makes ownership explicit. The queue of all split fragments adds avoidable retained state. The existing SparkColumnarArrowReader demonstrates how to retain an input and advance through its rows incrementally.
  • Behavioral changes worth calling out: Small inputs now share cache batches and statistics, making pruning coarser. Non-Arrow inputs are split at the configured row target. The guide documents the batching change. Smaller targets can currently increase peak memory sharply because of the finding below.
  • Suggested improvements: Address the eager-splitting memory regression and add a bounded-allocation regression test using a multi-fragment input with variable-width columns. No additional P1/P2 improvements were identified.

Exact-head CI: Java lint checks across all five Spark profiles, Scala lint, Spark 3.5 strict warnings, and CodeQL passed. Native compilation, Rust tests, and the labeled Spark 4.1 SQL build remained in progress. Two earlier label-run required-check aggregators failed because their upstream jobs were cancelled, not because a test failed. There is no completed integration-test verdict yet.

Validation: An isolated source harness using Spark 4.1.3, Arrow 18.3.0, and Arrow's unsafe allocator passed all 27 CometArrowWriterSuite tests. Additional probes passed the PR's 13,400-row ordering fixture, nested/sliced values, and early cleanup. The memory probe reproduced the P2 issue and verified cleanup after failure. The harness compiled the unchanged coalescer, writers, and vector classes with extracted utility methods. It did not exercise the complete serializer/JNI integration. I did not run the full Maven/native build, cache integration suites, other Spark-version binaries, or performance benchmark locally. The project checkout remains unchanged.

private def append(batch: ColumnarBatch): Unit = {
val numRows = batch.numRows()
var start = 0
while (start < numRows) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Emit split fragments incrementally instead of queuing the entire input. When a Spark-vector batch exceeds targetRows, this loop allocates and retains every output root before advance() returns the first one. Each variable-width vector receives Arrow's initial buffer allocation, so reducing spark.sql.inMemoryColumnarStorage.batchSize can greatly increase memory usage. For a normal-sized 4096-row input with four one-byte string columns, the previous conversion held 256 KiB, while a target of 100 retained 7.69 MiB and a target of 10 exhausted a bounded 64 MiB allocator before returning any output. Production uses the unbounded CometArrowAllocator, so this additional off-heap memory bypasses Spark's memory budget. Please retain the current input and row offset, emit one completed fragment, and continue copying only when the consumer requests another. The producer can remain unadvanced until that input is exhausted.

Evidence: Reproduced with the exact-head CacheBatchCoalescer and ArrowWriters, Spark 4.1.3, Arrow 18.3.0, and -Darrow.allocation.manager.type=Unsafe. Construct four OnHeapColumnVector(4096, StringType) columns containing the single byte 'x', wrap them in a ColumnarBatch, and call new CacheBatchCoalescer(Iterator(batch), attrs, targetRows, new RootAllocator(64L * 1024 * 1024)).next(). The unchanged base conversion sequence (ArrowWriter.create(root, 4096), writeColumns(batch, 0, 4096), finish()) retained 262144 bytes. Head retained 8060928 bytes at target 100. At target 10 it threw OutOfMemoryException before the first output, with 67092480 bytes allocated. Explicit cleanup returned allocation to zero. Reproduction and logs are under /tmp/pr6988-review/.

@andygrove andygrove Oct 28, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You were right about this. With four string columns and a 4 MiB limit on the allocator, one 4096-row input at a target of 10 ran out of memory before the first output batch came back. The coalescer now keeps the input it is copying and a row offset, and copies only as far as one output batch each time it is asked for one, so the producer is not advanced until that input is used up. The new CacheBatchCoalescerSuite has the bounded-allocator case, and it fails on the previous code with the same out-of-memory error. Fixed in 4220514.

The coalescer queued every fragment of a large Spark-vector batch before returning the first, so a small spark.sql.inMemoryColumnarStorage.batchSize multiplied the Arrow allocation of one input. It now keeps the batch it is copying and a row offset, and copies only as far as one output batch each time it is asked for one.
@andygrove
andygrove force-pushed the perf/cache-coalesce-small-batches branch from 59c9b6d to 4220514 Compare October 28, 2026 14:53

@comphead comphead left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The advance state machine keeps row order and never advances the input while a batch is partly copied, and copying through ArrowWriter avoids the 1 GiB doubling cap that VectorAppender hits in the broadcast path. Three comments, on untested release paths, the pass-through threshold and a doc sentence.


// Runs `f` on a coalescer over `inputs`, checks that closing it returns every byte it took, and
// returns the most the allocator held at once.
private def withCoalescer(limit: Long, inputs: Seq[ColumnarBatch], target: Int)(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Every test here, and the new CometInMemoryCacheSuite cases, drains the coalescer before close() runs, so the release paths for a partly consumed one have no test: pending, filled, a held readyRoot and emitted at close time, and the NonFatal cleanup in startPending. A change that made close() skip pending or filled would still pass. Could one case take a single batch from a multi-batch input (a 25-row sparkBatch at target 10 leaves a partial pending and a non-empty filled) and then close, and another use an allocator limit small enough that startPending or writeColumns throws, both checking the allocator returns to zero?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You were right that nothing closed a coalescer that was only partly consumed. CacheBatchCoalescerSuite now has cases for closing after one batch of a 25-row input at a target of 10 (the root behind the batch handed out, with the input half copied), closing after hasNext built a batch that nothing took, and a closed coalescer with input left reporting no more batches. It also has two allocator-limit cases: one fails while the output batch is being started, after two of its four columns are allocated, and one fails once the copied rows outgrow the data buffers. Each checks that the allocator is back to zero, and each fails when I take out the matching release (the handed-out root, the ready root, pending, the root.close() in startPending's catch) or the closed check.

Two of the states you listed can't be reached that way. advance finishes the batch being filled before it returns (when it is full, when a pass-through batch arrives, or when the input ends), and it dequeues the one batch it queued, so pending and filled are empty between calls. A 25-row input at a target of 10 leaves the input partly copied, not pending. pending is open at close only when a copy threw, which is the last case above, and filled is released defensively with nothing to test it against. Would you rather I drop filled to a single slot so that is plain?

private val readerFields = arrowSchema.getFields.asScala.toIndexedSeq

// A batch at least this large that the writer can store as it stands is not copied.
private val passThroughRows = math.max(1, targetRows / 2)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The threshold follows spark.sql.inMemoryColumnarStorage.batchSize, so it is 5000 rows by default, and default 8192-row native batches pass through. With spark.comet.batchSize at 4096 or lower, or the cache batch size above 16384, every native Arrow batch now takes the ArrowWriter.writeColumns copy, where before it was written without one. The table in the description measures inputs of 250 to 775 rows, where the copy clearly pays. Could you measure the build at 4096-row native batches against main, or tie the threshold to Comet's batch size? I have not measured the copy cost.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I measured it, and the copy is not free there. With 5M rows of six columns from a native range and projection, a release native library and spark.comet.batchSize at 4096, copying every full native batch into 10000-row batches cut the cached batches from 1232 to 512 and made the aggregate over the cache 10% faster (357 to 322 ms), but the build took 5% longer (1191 to 1249 ms) and the payload was 6% larger (54.3 to 57.5 MB). The two layouts alternated in one JVM for 7 rounds, and these are medians. At the default 8192 both layouts are identical.

So the threshold now follows Comet's batch size: a batch passes through when it holds at least half of the smaller of the cache's batch size and spark.comet.batchSize. At 4096 the layout is main's again (1232 batches, build 1207 against 1194 ms, aggregate 351 against 353 ms), and the small batches of a shuffle read are still combined. With the defaults the threshold is 4096 rows instead of 5000. The description has the table. Changing the sorted-cache test was a consequence: its native sort emits 100-row batches under spark.comet.batchSize 100, which are now full batches, so it checks the order of a sorted cache and leaves the combining to "combines small columnar batches in order".

Comment on lines +80 to +81
A cache built from rows cuts its batches at `spark.sql.inMemoryColumnarStorage.batchSize` rows,
10000 by default, as Spark's own format does. A cache built from the Arrow batches of Comet

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spark's row path also ends a batch once it reaches about 4 MiB (ColumnBuilder.MAX_BATCH_SIZE_IN_BYTE in InMemoryRelation, in 3.4, 3.5 and 4.1), while Comet's row path and this coalescer cut by rows only. Could the sentence say that, so readers know wide rows give larger cached batches than Spark's format?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added: "Spark's own format also ends a batch once it holds about 4 MiB, but Comet cuts by row count alone, so a relation of wide rows is stored in larger batches than Spark's format would use." I checked the cut in the Spark sources for 3.4.3, 3.5.9, 4.0.4, 4.1.3 and 4.2.0, where InMemoryRelation stops a batch when totalSize reaches ColumnBuilder.MAX_BATCH_SIZE_IN_BYTE, which is 4 MiB in each.

A batch is passed through when it holds at least half of the smaller of
spark.sql.inMemoryColumnarStorage.batchSize and spark.comet.batchSize, so a
batch that is full for the operator that produced it is not copied when
spark.comet.batchSize is under the cache's batch size.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request performance run-spark-4.1-tests Run the Spark 4.1 SQL tests on this pull request instead of waiting for the merge queue

Projects

None yet

Development

Successfully merging this pull request may close these issues.

The in-memory cache stores small input batches as they arrive, so a cached repartition over many map tasks holds thousands of small batches

3 participants