Skip to content

Commit 7e75199

Browse files
committed
perf: benchmark and document TopK reader pruning
1 parent 852a56c commit 7e75199

4 files changed

Lines changed: 145 additions & 35 deletions

File tree

‎docs/source/contributor-guide/adding_a_new_operator.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,14 @@ remove the inserted local node when restoring Spark execution. Restoring its `or
8585
apply the global TopK twice. A single input partition uses a final native limit and projection;
8686
multiple input partitions still require a final TopK after the shuffle.
8787

88+
With `spark.comet.exec.topK.dynamicFilter.enabled`, only the local sort sets the protobuf
89+
`Sort.dynamic_filter_enabled` flag. The native planner wraps an eligible sort in
90+
`TopKReaderFilterExec`. Its permanent plan contains an unexecuted sort template; each execution
91+
creates a fresh sort and live predicate, then attaches that predicate to the Parquet reader when
92+
eligible. The stream owns the heap and predicate until completion, error, or cancellation. The
93+
final TopK after an exchange does not share this state. Reader work stays on scan metrics while
94+
attachment counters belong to the local TopK.
95+
8896
### Choosing the Right Operator Type
8997

9098
When adding a new operator, choose based on these criteria:

‎docs/source/user-guide/latest/metrics.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,25 @@ by the reader. An attached filter does not guarantee that any row groups are pru
107107
probe scan's `bytes_scanned` and `row_groups_pruned_statistics` with filtering disabled to assess
108108
reader savings. Existing join, scan, and intervening filter metrics retain their own meanings.
109109

110+
### Local TopK
111+
112+
With `spark.comet.exec.topK.dynamicFilter.enabled=true`, eligible fused local TopK operators report
113+
these counters. See [TopK Reader Pruning](tuning/operators.md#topk-reader-pruning) for the required
114+
fusion option and reader restrictions.
115+
116+
| Metric | Description |
117+
| -------------------------------------- | ---------------------------------------------------------------------------- |
118+
| `dynamic_filter_topk_filters_attached` | Executions that attach their live TopK threshold to a native Parquet reader. |
119+
| `dynamic_filter_topk_filters_skipped` | Eligible TopK executions whose input cannot accept reader attachment. |
120+
121+
These counters belong to the local TopK. An attached predicate may prune nothing, and a file's
122+
schema adaptation can disable it to preserve conversion errors. Reader work remains on the scan:
123+
`output_rows` counts rows emitted by the scan, `bytes_scanned` measures requested data/Bloom-filter
124+
ranges (excluding footer and page-index reads), and `row_groups_pruned_dynamic_filter` counts groups
125+
skipped by a changing runtime predicate. Page and decoder filtering use the existing
126+
`page_index_rows_pruned` and `pushdown_rows_pruned` counters.
127+
This feature adds no separate decoded-batch filter or evaluated/pruned row counters to the TopK.
128+
110129
### Exchange
111130

112131
Comet adds some additional metrics:
@@ -185,6 +204,7 @@ execution metrics. Counters accumulate per scan operator; they do not instrument
185204
| `scan_io_object_store_response_bytes_read` | Response bytes actually consumed at that API, including bytes fetched between coalesced ranges. Not HTTP wire bytes. |
186205
| `scan_io_metadata_cache_hits` | Successful, cache-eligible metadata opens requiring no storage reads. |
187206
| `scan_io_metadata_cache_misses` | Successful, cache-eligible metadata opens requiring storage reads. Failed opens and encrypted opens, which bypass this shared cache, increment neither cache counter. |
207+
| `row_groups_pruned_dynamic_filter` | Row groups skipped by a runtime predicate whose value changes during execution, such as a local TopK threshold. |
188208

189209
Reader-level and object-store bytes are two views of the same reads; do not add them together.
190210
Likewise, footer bytes are a subset of metadata bytes, not a third reader-level category. A warm

‎docs/source/user-guide/latest/tuning/operators.md‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -111,12 +111,40 @@ Each scan partition keeps enough candidates for both `LIMIT` and `OFFSET`. With
111111
Comet shuffles those candidates and performs the final TopK. With one partition, it reuses the local
112112
ordering without building a second heap. The final stage applies the offset and output projection.
113113

114-
Fusion reduces the work of passing scan batches between native execution blocks. It still reads all
115-
input rows and does not enable TopK reader pruning. It can also reduce overlap between scan decoding
114+
Fusion reduces the work of passing scan batches between native execution blocks. Fusion alone still
115+
reads all input rows. [TopK reader pruning](#topk-reader-pruning) is enabled separately. Fusion can
116+
also reduce overlap between scan decoding
116117
and TopK processing, so some workloads may run slower. Compare enabled and disabled runs with your
117118
data layout, payload width, limit, and partition count before enabling it. The
118119
`CometTopKBenchmark` microbenchmark covers these cases with ascending, descending, and random layouts.
119120

121+
### TopK Reader Pruning
122+
123+
Set both `spark.comet.exec.topK.fusion.enabled=true` and
124+
`spark.comet.exec.topK.dynamicFilter.enabled=true` to pass the local TopK's improving threshold to
125+
its Parquet reader. Both options are experimental and disabled by default. Eligibility is the same
126+
single signed integer key described above. Each task creates a fresh threshold; it is not shared
127+
across Spark partitions or exchanges, or retained for later executions.
128+
129+
Once the heap contains enough candidates for `LIMIT + OFFSET`, the reader can skip later row groups
130+
whose statistics prove that no row can improve those candidates. Existing Parquet page-index and
131+
decoder-filter options can also use the predicate. This option adds no separate filter over decoded
132+
scan batches. TopK continues to select the final candidates.
133+
134+
Reader attachment is conservative. A scan with a fetch limit, supplied file statistics, or a static
135+
predicate other than direct column `IS NOT NULL` checks keeps the existing execution path. For each
136+
file, schema adaptation disables pruning if it could hide a conversion error in a projected or
137+
filtered column. Missing null counts remain unknown, which can prevent pruning even when min/max
138+
statistics are present. These cases can still execute a fused TopK.
139+
140+
Reader pruning is most useful when small K values and the file order establish a strong threshold
141+
early. Descending or random layouts for an ascending query can prune few or no groups, while still
142+
paying the cost of attaching and checking the predicate. Wider rows can increase the benefit when
143+
groups are skipped. Compare `pruning` with `fused` in `CometTopKBenchmark` to measure the reader effect,
144+
and compare both with `unfused` to include the cost of fusion. Check the scan's emitted rows,
145+
`bytes_scanned`, and `row_groups_pruned_dynamic_filter` alongside elapsed time; attachment alone does
146+
not demonstrate a saving. See [TopK metrics](../metrics.md#local-topk).
147+
120148
## Optimizing Sorting on Floating-Point Values
121149

122150
Comet normalizes NaN payloads and signed zeros in scalar `FLOAT` and `DOUBLE` ordering keys, so `ORDER BY`, window

‎spark/src/test/scala/org/apache/spark/sql/benchmark/CometTopKBenchmark.scala‎

Lines changed: 87 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,11 @@
2020
package org.apache.spark.sql.benchmark
2121

2222
import scala.concurrent.duration._
23+
import scala.jdk.CollectionConverters._
2324

2425
import org.apache.hadoop.fs.Path
26+
import org.apache.parquet.hadoop.ParquetFileReader
27+
import org.apache.parquet.hadoop.util.HadoopInputFile
2528
import org.apache.spark.benchmark.Benchmark
2629
import org.apache.spark.sql.Row
2730
import org.apache.spark.sql.comet.{CometLocalTopKExec, CometNativeScanExec, CometTakeOrderedAndProjectExec}
@@ -31,29 +34,47 @@ import org.apache.comet.CometConf
3134
import org.apache.comet.serde.OperatorOuterClass.Operator
3235

3336
/**
34-
* Compare local TopK fusion enabled and disabled, using a native release build. The make target
35-
* builds and packages the release library before running the benchmark:
37+
* Compare native TopK without fusion, with fusion, and with fusion plus reader pruning. Use a
38+
* native release build. The make target builds and packages it before running:
3639
*
3740
* {{{
3841
* make benchmark-org.apache.spark.sql.benchmark.CometTopKBenchmark -- \
39-
* 1048576 1,4 1,16 16,4096 ascending,descending,random 5 off,on
42+
* 1048576 1,4 1,16 16,100000 ascending,descending,random 5 unfused,fused,pruning
4043
* }}}
4144
*
4245
* Arguments are rows, scan partitions, BIGINT payload columns, K values, layouts, minimum
43-
* measured iterations, and mode order. Defaults match the example. Use on,off for a second run
44-
* with the opposite case order. Selectors between rows and iterations accept comma-separated
45-
* lists. For a quick smoke run, use 16384 rows and three iterations. Each case warms up for at
46-
* least 500 ms and measures for at least 500 ms. Results include query planning and collection;
47-
* fixtures, Spark result checks, and native plan checks run outside the timings. The wide payload
48-
* and descending layout expose the possible cost of losing scan/TopK overlap.
46+
* measured iterations, and mode order. Defaults match the example. Repeat with
47+
* pruning,fused,unfused to reverse the case order. Selectors between rows and iterations accept
48+
* comma-separated lists. For a smoke run, use 16384 rows, K=16, and three iterations. Each case
49+
* warms up and measures for at least 500 ms. Timings include planning and collection; fixture
50+
* creation, Spark result comparisons, and plan checks run outside timings. Reader metrics come
51+
* from the untimed validation execution; metadata cache warmth can depend on mode order.
52+
*
53+
* Compare pruning against fused to isolate reader savings. The unfused baseline separately
54+
* exposes changes in scan/TopK overlap. Page indexes and decoder row filters are disabled so scan
55+
* metrics measure row-group pruning. Every fixture has multiple row groups per file.
4956
*/
5057
object CometTopKBenchmark extends CometBenchmarkBase {
5158

59+
private case class Mode(name: String, fusion: Boolean, filtering: Boolean) {
60+
val configs: Seq[(String, String)] = Seq(
61+
CometConf.COMET_EXEC_TOPK_FUSION_ENABLED.key -> fusion.toString,
62+
CometConf.COMET_EXEC_TOPK_DYNAMIC_FILTER_ENABLED.key -> filtering.toString)
63+
}
64+
65+
private val modes = Seq(
66+
Mode("unfused", fusion = false, filtering = false),
67+
Mode("fused", fusion = true, filtering = false),
68+
Mode("pruning", fusion = true, filtering = true)).map(mode => mode.name -> mode).toMap
69+
5270
private val nativeConfigs = Seq(
5371
CometConf.COMET_ENABLED.key -> "true",
5472
CometConf.COMET_EXEC_ENABLED.key -> "true",
5573
CometConf.COMET_NATIVE_SCAN_ENABLED.key -> "true",
5674
CometConf.COMET_BATCH_SIZE.key -> "4096",
75+
CometConf.COMET_PARQUET_ROW_FILTER_PUSHDOWN_ENABLED.key -> "false",
76+
CometConf.COMET_RESPECT_DATAFUSION_CONFIGS.key -> "true",
77+
"spark.comet.datafusion.execution.parquet.enable_page_index" -> "false",
5778
SQLConf.ADAPTIVE_EXECUTION_ENABLED.key -> "false",
5879
SQLConf.LEAF_NODE_DEFAULT_PARALLELISM.key -> "1",
5980
SQLConf.FILES_OPEN_COST_IN_BYTES.key -> "4194304")
@@ -73,7 +94,9 @@ object CometTopKBenchmark extends CometBenchmarkBase {
7394
rows: Int,
7495
partitions: Int,
7596
payloadColumns: Int,
76-
layout: String): Long = {
97+
layout: String): (Long, Seq[Int]) = {
98+
// Target eight row groups per file, scaling with row width and fixture size.
99+
val blockBytes = rows.toLong / partitions * (4L + 8L * payloadColumns) / 8
77100
withSQLConf(CometConf.COMET_ENABLED.key -> "false") {
78101
val payload = (0 until payloadColumns).map(i => s"id * ${17 + i * 2} AS payload_$i")
79102
spark
@@ -82,6 +105,7 @@ object CometTopKBenchmark extends CometBenchmarkBase {
82105
.write
83106
.option("compression", "snappy")
84107
.option("parquet.enable.dictionary", "false")
108+
.option("parquet.block.size", blockBytes.toString)
85109
.parquet(directory)
86110
}
87111
val path = new Path(directory)
@@ -90,17 +114,25 @@ object CometTopKBenchmark extends CometBenchmarkBase {
90114
.listStatus(path)
91115
.filter(_.getPath.getName.endsWith(".parquet"))
92116
require(files.length == partitions, s"Expected $partitions files, found ${files.length}")
93-
files.map(_.getLen).max
117+
val rowGroups = files.toSeq.map { file =>
118+
val reader = ParquetFileReader.open(
119+
HadoopInputFile.fromPath(file.getPath, spark.sessionState.newHadoopConf()))
120+
try reader.getFooter.getBlocks.asScala.size
121+
finally reader.close()
122+
}
123+
require(rowGroups.forall(_ > 1), s"Expected multiple row groups per file: $rowGroups")
124+
(files.map(_.getLen).max, rowGroups)
94125
}
95126

96127
private def verifyPlanAndResult(
97128
benchmark: Benchmark,
98129
query: String,
99130
expected: Seq[Row],
100-
fusion: Boolean,
131+
mode: Mode,
101132
k: Int,
102133
partitions: Int,
103134
expectedInputRows: Int): Unit = {
135+
val fusion = mode.fusion
104136
val df = spark.sql(query)
105137
val plan = stripAQEPlan(df.queryExecution.executedPlan)
106138
val local = collect(plan) { case node: CometLocalTopKExec => node }
@@ -111,9 +143,11 @@ object CometTopKBenchmark extends CometBenchmarkBase {
111143
require(outer.head.child.executeColumnar().getNumPartitions == partitions)
112144
if (fusion) {
113145
require(local.head.limit == k)
146+
require(local.head.dynamicFilterEnabled == mode.filtering)
114147
val block = Operator.parseFrom(local.head.serializedPlanOpt.plan.get)
115148
require(block.hasSort && block.getSort.getFetch == k && block.getSort.getSkip == 0)
116149
require(block.getChildrenCount == 1 && block.getChildren(0).hasNativeScan)
150+
require(block.getSort.getDynamicFilterEnabled == mode.filtering)
117151
}
118152
val finalPlan = outer.head.finalNativePlan(partitions).get
119153
require(finalPlan.hasProjection && finalPlan.getChildrenCount == 1)
@@ -124,31 +158,52 @@ object CometTopKBenchmark extends CometBenchmarkBase {
124158
} else {
125159
require(selection.hasSort && selection.getSort.getFetch == k)
126160
}
127-
require(df.collect().toSeq == expected, s"Incorrect results with fusion=$fusion")
161+
require(df.collect().toSeq == expected, s"Incorrect results in mode ${mode.name}")
128162
val scanMetrics = scans.head.metrics
129-
require(
130-
scanMetrics.get("output_rows").exists(_.value == expectedInputRows.toLong),
131-
"TopK fusion must still decode all input rows")
132-
val readerWork = Seq("output_rows", "bytes_scanned", "row_groups_pruned_dynamic_filter")
133-
.flatMap(name => scanMetrics.get(name).map(metric => s"$name=${metric.value}"))
134-
.mkString(", ")
135-
benchmark.out.println(s"fusion=$fusion, $readerWork")
163+
if (!mode.filtering) {
164+
require(scanMetrics("output_rows").value == expectedInputRows.toLong)
165+
require(scanMetrics("row_groups_pruned_dynamic_filter").value == 0L)
166+
}
167+
require(scanMetrics("row_groups_pruned_statistics").value == 0L)
168+
require(scanMetrics("page_index_rows_pruned").value == 0L)
169+
require(scanMetrics("pushdown_rows_pruned").value == 0L)
170+
val readerWork = Seq(
171+
"output_rows",
172+
"bytes_scanned",
173+
"scan_io_data_bytes",
174+
"scan_io_metadata_bytes",
175+
"row_groups_pruned_dynamic_filter",
176+
"row_groups_pruned_statistics",
177+
"page_index_rows_pruned",
178+
"pushdown_rows_pruned")
179+
.map(name => s"$name=${scanMetrics(name).value}")
180+
val attachment = local.flatMap { topK =>
181+
val attached = topK.metrics("dynamic_filter_topk_filters_attached").value
182+
val skipped = topK.metrics("dynamic_filter_topk_filters_skipped").value
183+
require(attached == (if (mode.filtering) partitions.toLong else 0L))
184+
require(skipped == 0L)
185+
Seq(
186+
s"dynamic_filter_topk_filters_attached=$attached",
187+
s"dynamic_filter_topk_filters_skipped=$skipped")
188+
}
189+
benchmark.out.println(s"mode=${mode.name}, ${(readerWork ++ attachment).mkString(", ")}")
136190
}
137191

138192
override def runCometBenchmark(mainArgs: Array[String]): Unit = {
139193
require(
140194
mainArgs.length <= 7,
141195
"Usage: CometTopKBenchmark [rows] [partitions] [payload-columns] [ks] [layouts] " +
142-
"[iterations] [off,on|on,off]")
196+
"[iterations] [unfused,fused,pruning in any order]")
143197
val rows = mainArgs.headOption.map(_.toInt).getOrElse(1 << 20)
144198
val partitions = mainArgs.lift(1).getOrElse("1,4").split(",").map(_.toInt).toSeq
145199
val payloadColumns = mainArgs.lift(2).getOrElse("1,16").split(",").map(_.toInt).toSeq
146-
val ks = mainArgs.lift(3).getOrElse("16,4096").split(",").map(_.toInt).toSeq
200+
val ks = mainArgs.lift(3).getOrElse("16,100000").split(",").map(_.toInt).toSeq
147201
val layouts = mainArgs.lift(4).getOrElse("ascending,descending,random").split(",").toSeq
148202
val iterations = mainArgs.lift(5).map(_.toInt).getOrElse(5)
149-
val modeOrder = mainArgs.lift(6).getOrElse("off,on")
150-
require(Set("off,on", "on,off").contains(modeOrder), "mode order must be off,on or on,off")
151-
val fusionModes = modeOrder.split(",").map(_ == "on").toSeq
203+
val modeOrder = mainArgs.lift(6).getOrElse("unfused,fused,pruning").split(",").toSeq
204+
require(
205+
modeOrder.size == modes.size && modeOrder.toSet == modes.keySet,
206+
"mode order must contain unfused, fused, and pruning exactly once")
152207
require(rows >= 16384 && (rows & (rows - 1)) == 0, "rows must be a power of two >= 16384")
153208
require(partitions.forall(p => p > 0 && rows % p == 0), "partitions must divide rows")
154209
require(payloadColumns.forall(_ > 0), "payload-columns must be positive")
@@ -160,7 +215,7 @@ object CometTopKBenchmark extends CometBenchmarkBase {
160215
withTempTable("topk_input") {
161216
for (p <- partitions; columns <- payloadColumns; layout <- layouts) {
162217
val directory = s"${root.getCanonicalPath}/$layout-p$p-c$columns"
163-
val maxFileBytes = writeInput(directory, rows, p, columns, layout)
218+
val (maxFileBytes, rowGroups) = writeInput(directory, rows, p, columns, layout)
164219
// Keep each file in its own scan partition without inserting a repartition operator,
165220
// which would interrupt fusion. Verify the actual partition count for every case.
166221
val scanConfigs = nativeConfigs :+
@@ -183,14 +238,13 @@ object CometTopKBenchmark extends CometBenchmarkBase {
183238
minTime = 500.millis,
184239
output = output)
185240
withSQLConf(scanConfigs: _*) {
186-
fusionModes.foreach { fusion =>
187-
val fusionConfig =
188-
CometConf.COMET_EXEC_TOPK_FUSION_ENABLED.key -> fusion.toString
189-
withSQLConf(fusionConfig) {
190-
verifyPlanAndResult(benchmark, query, expected, fusion, k, p, rows)
241+
benchmark.out.println(s"row groups per file: ${rowGroups.mkString(",")}")
242+
modeOrder.map(modes).foreach { mode =>
243+
withSQLConf(mode.configs: _*) {
244+
verifyPlanAndResult(benchmark, query, expected, mode, k, p, rows)
191245
}
192-
benchmark.addCase(if (fusion) "fusion enabled" else "fusion disabled") { _ =>
193-
withSQLConf(fusionConfig) {
246+
benchmark.addCase(mode.name) { _ =>
247+
withSQLConf(mode.configs: _*) {
194248
spark.sql(query).collect()
195249
}
196250
}

0 commit comments

Comments
 (0)