Skip to content

fix(cost): charge an exact distinct count per value and pair lookup that misses the cache; declare the production workloads' column-wide distinct users - #1368

Merged
zzylol merged 3 commits into
mainfrom
fix/exact-distinct-cost-refit
Nov 16, 2026
Merged

zzylol merged 3 commits into
mainfrom
fix/exact-distinct-cost-refit

Conversation

@zzylol

@zzylol zzylol commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Problem. The planner charges an exact COUNT(DISTINCT user_id) too much when a source has many rows per distinct value. On the production SQL shape it predicts 273.7 s per evaluation for the exact counts against 200.2 s for KMV (k = 4,323), but the exact counts measure 1.8x faster (12.3 s against 21.8 s over 12,000,000 rows). The shape is 120,000,000 rows, 1,000 (region, service) groups and 1,000,000 users. Once draft PR fix(accuracy): split δ over the readout values the covered output values depend on #1360 corrects the δ split, the planner picks KMV here.
  • Change. The exact distinct-count cost is refit on a measured grid. It now has a constant, a term per doubling of the values, a cache-miss term for the value table and one for the pair set, and one term each per inserted value and per inserted pair. The two production distinct-count workloads now declare the column-wide fact distinct_values_per_label: {"user_id": 1_000_000}. max_distinct_per_evaluation keeps its documented per-group meaning.
  • Effect. The production SQL exact counts are predicted at 117.2 s and measure 122.9 s (scaled ×10). KMV is predicted at 200.6 s and measures 218.3 s. With fix(accuracy): split δ over the readout values the covered output values depend on #1360 applied, production_sql_distinct_region_service_counts_exactly passes. At the rollup_controlled shape, KMV measures 1.26x faster than exact at 60,000,000 rows, so the planner's KMV choice there is correct (see Decisions).

Review guide

  • Base: main at 8e65fca. The PR is not stacked. It was also checked on top of draft PR fix(accuracy): split δ over the readout values the covered output values depend on #1360 (fix/delta-split-over-dependent-readouts at 4f069ac).
  • Read first: exact_distinct_value_operations_per_row and its constants in crates/cost/src/node/operations_per_unit.rs. Then read the two workload declarations, in production_rollup_workloads::data() and tools/dag-viewer/memo-examples/sql/rollupheavy-t11-service-endpoint-5m.json.
  • Commit 1 (1419e68) changes only tests. The refit test fails on main. Commit 2 (2021937) is the fix and the workload declarations.
  • Careful review: Decision 1. This PR keeps the per-group meaning of max_distinct_per_evaluation and declares the column-wide fact in the workloads.

Behavior: before → after

The workload is production_rollup_workloads::data(): http at 2,000,000 rows/s, 10,000 series and 120,000,000 rows held. Each group has at most 1,000,000 distinct users per evaluation (max_distinct_per_evaluation), and this PR also declares 1,000,000 for the whole user_id column (distinct_values_per_label). It runs two queries every 60 s at a 5% relative per-value target:

SELECT region, service, COUNT(DISTINCT user_id) AS value FROM http WHERE ts >= now() - INTERVAL '5 minutes' GROUP BY region, service
SELECT service,         COUNT(DISTINCT user_id) AS value FROM http WHERE ts >= now() - INTERVAL '5 minutes' GROUP BY service
per evaluation before (#1360 alone) after (#1360 + this PR), at 120 M rows after, charged at the measured 12 M rows measured (12 M rows)
exact Aggregate by (region, service) 138.2 s (1,151 ops/row) 59.7 s (497 ops/row) 6.25 s (521 ops/row) 6.35 s (529 ns/row)
exact Aggregate by service 134.8 s (1,123 ops/row) 56.3 s (469 ops/row) 5.91 s (493 ops/row) 5.87 s (489 ns/row)
exact plan total 273.7 s 117.2 s 12.3 s (with the scan) 12.3 s
KMV plan (k = 4,323), unchanged 200.2 s 200.6 s 21.8 s
selected with #1360 KMV exact exact is 1.78x faster

The measurements used the executor at release, one pinned core, median of 3, over 12,000,000 rows. At the measured shape the exact charge is 0.98x (by (region, service)) and 1.01x (by service) of the measured time. The per-row charge at 120,000,000 rows is about 5% lower, because the inserted values and pairs are shared over 10x the rows. Before this PR the exact charge was 2.2x the measured time.

Before this PR the charge grew because the planner passed 120,000,000 distinct values. Without a column-wide declaration it bounds the value table by the per-group bound times the groups (1,000,000 × 10,000) and by the rows read, so every row was taken as differing. The value lookup was then charged as at 3,000,000 values (918 per row). With the declared 1,000,000 users the table holds 1,000,000 values.

This serves the user need that the measured-best plan is selected (MVP correctness of plan choice).

Interfaces

None public. All changed items are crate-private, in crates/cost/src/node/operations_per_unit.rs:

 /// Per input row of an exact distinct count, beyond its table terms: reading the value
 /// and looking it and its pair up while both tables fit in the cache.
-const EXACT_DISTINCT_OPERATIONS_PER_ROW: f64 = 41.0;
+const EXACT_DISTINCT_OPERATIONS_PER_ROW: f64 = 59.0;
-/// Per input row, per square root of the distinct values its value table holds.
-const EXACT_DISTINCT_LOOKUP_OPERATIONS_PER_SQRT_VALUE: f64 = 0.53;
-/// The most distinct values measured: past it the lookup is charged as at it.
-const EXACT_DISTINCT_LOOKUP_MOST_VALUES: f64 = 3_000_000.0;
-/// Per entry (value or pair) an exact distinct count inserts, shared over its rows.
-const EXACT_DISTINCT_OPERATIONS_PER_INSERTED_ENTRY: f64 = 72.0;
+/// Per doubling of the values past `EXACT_DISTINCT_FEWEST_VALUES` (at most the most).
+const EXACT_DISTINCT_OPERATIONS_PER_VALUE_DOUBLING: f64 = 13.0;
+/// The fewest distinct values on the grid: fewer are charged as 1,000.
+const EXACT_DISTINCT_FEWEST_VALUES: f64 = 1_000.0;
+/// The most distinct values on the grid: more are charged as 10,000,000.
+const EXACT_DISTINCT_MOST_VALUES: f64 = 10_000_000.0;
+/// Per input row when every value lookup misses the cache, so charged times the
+/// fraction that miss.
+const EXACT_DISTINCT_OPERATIONS_PER_ROW_AT_FULL_VALUE_MISS: f64 = 207.0;
+/// The distinct values whose table still fits in the cache. Machine-specific: a default
+/// until calibration measures it per machine.
+const EXACT_DISTINCT_VALUES_IN_CACHE: f64 = 200_000.0;
+/// Per input row when every (group, value) pair lookup misses the cache, so charged
+/// times the fraction that miss.
+const EXACT_DISTINCT_OPERATIONS_PER_ROW_AT_FULL_PAIR_MISS: f64 = 79.0;
+/// The (group, value) pairs whose set still fits in the cache. Machine-specific: a
+/// default until calibration measures it per machine.
+const EXACT_DISTINCT_PAIRS_IN_CACHE: f64 = 500_000.0;
+/// Per distinct value interned into the value table, shared over the rows.
+const EXACT_DISTINCT_OPERATIONS_PER_INSERTED_VALUE: f64 = 356.0;
+/// Per (group, value) pair inserted into the pair set, shared over the rows.
+const EXACT_DISTINCT_OPERATIONS_PER_INSERTED_PAIR: f64 = 13.0;
+/// The fraction of random lookups into a table of `entries` that miss a cache holding
+/// `entries_in_cache` of them: 0 while it fits, then 1 - entries_in_cache / entries.
+fn cache_miss_fraction(entries: f64, entries_in_cache: f64) -> f64;
 /// The operations one input row costs an exact distinct count (or frequency statistic)
 /// beyond the measure's own, its keys, its group visits and its output rows.
 pub(crate) fn exact_distinct_value_operations_per_row(
     distinct_values: u64,
     group_count: u64,
     rows: u64,
 ) -> f64;

EXACT_DISTINCT_LOOKUP_* and EXACT_DISTINCT_OPERATIONS_PER_INSERTED_ENTRY are removed because the new form replaces them. node_resource_usage_and_cost (crates/cost/src/node/usage/mod.rs) is unchanged.

The two workloads declare one more data fact:

 "http": {
     "series_count": 10_000,
     "sample_interval": 5,
     "column_signs": {"value": "non_negative"},
     "max_distinct_per_evaluation": 1_000_000,
+    "distinct_values_per_label": {"user_id": 1_000_000},
     "rows_held": 120_000_000,
 }

Usage. The flow is the workload above → run_planning → Stage 3 plan_cost → node_resource_usage_and_cost. For each exact Aggregate { measures: [Cardinality { cols: [user_id] }] } that call:

// distinct_values: min(declared user_id values (1,000,000), max_distinct_per_evaluation
// x groups (1,000,000 x 10,000), rows read (120,000,000)) = 1,000,000.
// Without the declaration it is 120,000,000: every row is taken as differing.
// group_count: 10,000 (the planner's estimate for `service` and for (region, service)).
let per_row = hash_aggregate_operations_per_row(1, &measures, 120_000_000, 10_000, 1_000_000);
// = key 16 + measure 4 + exact_distinct_value_operations_per_row(1_000_000, 10_000, 120_000_000)
//   (59 + 13 x log2(1,000) + 207 x 0.8 + 79 x 0.996 + 356 x 1 M / 120 M + 13 x 119.3 M / 120 M = 449)
//   = 469 operations per row: 56.3 s per evaluation, so the exact plan totals 117.2 s.

run_planning then selects the two exact Aggregates (117.2 s) over KMV k = 4,323 (200.6 s).

Algorithm changes

Exact distinct-count cost

  • Problem. 12,000,000 rows of 1,000,000 users, ungrouped, measure 381 ns per row and were charged 587 (1.54x). 1,000 users by instance (10,000 groups, 7.0 M pairs) measure 179 and were charged 139 (0.78x). The square-root term over-charges large value tables. The same constant was charged for a value insert and a pair insert, so a pair set that has outgrown the cache was not charged at all.

  • Before. 41 + 0.53 √min(values, 3 M) + 72 (min(values, rows) + pairs) / rows.

  • After.

    1. values = min(declared, max_distinct_per_evaluation × groups, rows), in node_resource_usage_and_cost, unchanged.
    2. pairs = G · values · (1 − e^{−rows/(G·values)}), unchanged.
    3. With v = clamp(values, 1e3, 1e7), the charge per row is 59 + 13 log2(v/1e3) + 207 miss(v, 2e5) + 79 miss(pairs, 5e5) + (356 min(values, rows) + 13 pairs) / rows, with miss(x, K) = max(0, 1 − K/x) (cache_miss_fraction).
  • Fit.

    • Data: 119 exact COUNT(DISTINCT) aggregates. The new grid is 10,000 series, 10 rows per series per batch: 1.2 M, 12 M and 36 M rows × 1e3, 1e4, 1e5, 1e6 and 1e7 distinct values × ungrouped, 10, 100, 1,000 and 10,000 groups (1 or 2 keys), 75 aggregates. The earlier grid is 1,000 series, 300 k and 3 M rows, 100 to 1e8 values, 1 to 1,000 groups, 44 aggregates.

    • The key, measure, visit and output-row terms are fixed at their constants. The fit minimizes squared log error and uses the features the planner passes (values capped at the rows).

    • Form chosen by leave-one-setting-out error. A setting is a (distinct values, rows, series) triple, so all of its groupings are held out together. Among about 45 forms (square root, log2, saturating and cache-miss terms, one or two insert terms, grids of cache sizes), the chosen form has LOSO RMS log error 0.122 (largest single error 0.32×). Leaving out each group count gives 0.116, each distinct count 0.148 and each row count 0.128. The old form, refit, scores 0.202.

    • Fitted constants: 59.2, 12.9, 207, 79.2, 356 and 13.3 (cache sizes 200,000 values and 500,000 pairs).

    • Rounded constants: measured ÷ charged is 0.76–1.32 (RMS log 0.109) over all 119 aggregates. The old constants give 0.61–1.58 (0.224).

    • Held-out shapes. Five shapes outside both grids were measured afterwards (12 M rows, one idle pinned core, median of 3; controls reproduced the grid within 3–4.5%). The new charge stays within 0.89–1.11 of the measured time, against 0.63–1.18 for the old one:

      shape measured ns/row charged measured ÷ charged old: measured ÷ charged
      5 M distinct, 3 groups 724.3 669 1.08 0.68
      30,000 distinct, 300 groups 227.2 224.6 1.01 1.18
      300,000 distinct, ungrouped 222.8 249 0.89 0.66
      300,000 distinct, 1,000 groups 412.3 382.9 1.08 0.91
      3 M distinct, 100 groups 668.8 600.2 1.11 0.63
  • Correctness. The charge rises with the values, with the pairs and with the inserted entries, and never falls below 59 per row. an_exact_distinct_count_costs_per_value_and_pair_it_looks_up checks five measured shapes at 0.8–1.25x. The two older measured-point tests still hold.

  • Complexity. O(1) per node, unchanged.

  • Assumptions and limits.

    • Below 1,000 values the charge is as at 1,000, and above 1e7 as at 1e7.
    • The cache sizes are machine-specific. They were fitted on one machine type (35 MB of L3 per socket), and both grids ran on that type. They are documented defaults until calibration measures them per machine: Exact distinct-count cache sizes are fixed constants: calibrate them per machine #1369.
    • The grid has no exact merge of distinct sets because the executor has none: an exact distinct count is always one Aggregate over raw rows. So no merge term was fitted (see Follow-ups).

Decisions and open questions

Decided

  1. max_distinct_per_evaluation keeps its per-group meaning. Its doc says "Each group's own items count separately: the bound is per output row". An earlier revision of this PR read it as a bound over all groups together, and capped the value table at it. Example of why that is wrong: 10,000 instances with disjoint users, at most 1,000 per instance per evaluation, so 10,000,000 users in total. A deployment may validly declare max_distinct_per_evaluation: 1000. For GROUP BY instance over 12,000,000 rows:

    • the total reading charges 179 ops per row, as if the table held 1,000 values;
    • the table really holds about 7,000,000 values. The per-group reading charges 859, and the measured 1e7 shape on the grid takes 811 ns per row;
    • so the total reading under-charges 4.5–4.8x and can wrongly pick exact.

    Instead, a workload whose users are shared across groups declares the column-wide fact distinct_values_per_label, which the cost already reads. The two production distinct-count workloads now declare {"user_id": 1_000_000}. With fix(accuracy): split δ over the readout values the covered output values depend on #1360, this gives the same plans as the total reading: the SQL test picks exact, and the rollup test picks KMV on both queries. an_exact_distinct_count_reads_at_most_its_column_s_declared_distinct_values checks that the declared fact caps the value table, and that the per-group bound alone does not.

  2. rollup_controlled::production_distinct_rollup_counts_exactly with fix(accuracy): split δ over the readout values the covered output values depend on #1360. The best plan there depends on the rows per state, so this PR does not force exact. The test plans COUNT(DISTINCT user_id) by service and by (service, endpoint) over 600,000,000 rows per evaluation. Measured on the executor (×10 to one evaluation):

    per evaluation predicted measured at 60 M rows (60,000 rows per state, as planned)
    exact: Aggregate by (service, endpoint) 297.1 s 321.9 s
    exact: Aggregate by service 280.3 s 284.7 s
    exact plan total 589.8 s 609.6 s
    KMV k = 4,323: build + rollup merge 331.9 + 49.5 s 453.1 + 24.4 s
    KMV plan total 394.0 s 483.6 s
  3. The form was chosen by leave-one-setting-out error over both grids, not by any test. One existing test bound was widened as a result (see Verification).

Verification

scope branch vs main 8e65fca combined (#1360 + this) notes
cargo test --release -p asap-cost 83/0/0 vs 81/0/0 +2 new tests
cargo test --release -p asap-integration-tests --test integration -- production_sql_distinct_region_service_counts_exactly production_distinct_rollup_counts_exactly 1/1/0 the SQL test picks exact and passes; the rollup test picks KMV on both queries (Decision 2)
the same two integration tests, run on this PR alone 2/0/0 both pass
cargo fmt --all --check, cargo clippy --release -p asap-cost --all-targets clean (one existing asap-types unused-import warning)

Columns are passed / failed / ignored.

New and changed tests:

  • an_exact_distinct_count_costs_per_value_and_pair_it_looks_up (new, fails on main) checks five measured 12 M-row shapes (1e3 to 1e7 users, ungrouped to 10,000 groups), each charged within 0.8–1.25x of its measured time. main charges 0.78–1.54x.
  • an_exact_distinct_count_reads_at_most_its_column_s_declared_distinct_values (new) checks that a count by instance over 120 M rows, with user_id declared at 1 M values and a per-group bound of 1 M, is charged as over the 1 M declared values. With the per-group bound alone it is charged more (as over the rows read).
  • a_grouped_exact_distinct_count_pays_its_key_and_visits_once (changed bound, 0.8–1.25 → 0.75–1.35). The bound is the fit's measured ÷ charged range over 119 aggregates. It is wider because the 100-user point is noisy: over the same 300,000 rows of 100 users, the count by job measures 60.2 ns per row and the count by region 86.1, 1.43x apart. Every count under 1,000 values is charged as at 1,000, so the 60.2 point is charged 1.33x, near the edge.

Earlier plan sweep. All 203 workloads were planned on main and on an earlier revision of this branch through run_default_search_over: #1363's grid (120), the showcase gate (24), the held-out set (48), the 2,000-series set (10) and the viewer's rollupheavy-t11. 203/203 select the same plan, node by node. But none of the 202 others contains a distinct count. The 10 cdist workloads are count(count by (instance) …), which are exact Count windows. So only rollupheavy-t11 reaches the changed code. Its exact plan was already selected, and its cost fell from 37,323 to 16,331 per second. That workload now declares the same 1,000,000 users, so the values it passes are unchanged from that revision. The evidence that the new charge ranks plans correctly is therefore the fit, the held-out shapes table above, and the two production shapes measured with free, exact-only and KMV-only arms.

The measurements and fit scripts are kept locally.

Design scope

  • cache_miss_fraction (private fn, crates/cost/src/node/operations_per_unit.rs) belongs to the Stage 3 cost scope, per-operation cost kernels. It is the general cost of a random lookup into a hash table that has outgrown the cache, and is not specific to distinct counts. It sits beside the other per-unit operation costs and reads only its arguments.
  • No new types, fields or files.

Follow-ups

  • Exact distinct-count cache sizes are fixed constants: calibrate them per machine #1369: measure the two cache sizes per machine in calibration, instead of fixed constants.
  • The KMV build at large rows per state (k = 4,323, 60,000 rows per state) measures 755 ns per row and is charged 553. This PR leaves the KMV cost as it is.
  • No exact distinct-set state exists for an exact rollup (merging (group, value) sets). The executor answers each grouping from raw rows, so the planner offers no such candidate and there is no merge cost to fit.
  • Two-key groupings over few values are still under-charged by about 1.3x (HASH_AGGREGATE_OPERATIONS_PER_FURTHER_KEY). This is the largest residual on the grid and is not changed here.

@zzylol zzylol added bug Something isn't working cost-model Cost formulas, statistics, ranking, and selection labels Nov 16, 2026
… up, and its column's declared distinct values cap its value table
…hat misses the cache and per inserted value; declare the production workloads' column-wide distinct users
@zzylol
zzylol force-pushed the fix/exact-distinct-cost-refit branch from 266d2d6 to 2021937 Compare November 16, 2026 17:03
@zzylol zzylol changed the title fix(cost): charge an exact distinct count per value and pair lookup that misses the cache, and bound its values by the source's distinct-item bound fix(cost): charge an exact distinct count per value and pair lookup that misses the cache; declare the production workloads' column-wide distinct users Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working cost-model Cost formulas, statistics, ranking, and selection

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant