Skip to content

feat(cost): node_cost_terms splits a node's formula CPU into named per-unit constants - #1371

Open
zzylol wants to merge 3 commits into
mainfrom
test/node-cost-terms
Open

zzylol wants to merge 3 commits into
mainfrom
test/node-cost-terms

Conversation

@zzylol

@zzylol zzylol commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Problem: a node's formula CPU is one number (NodeCost), so refitting one per-unit constant from measured node times needs a separate copy of the formulas that parses NodeCost::detail strings.
  • Change: asap_cost::node_cost_terms splits a node's formula CPU per execution into named per-unit constants (CostConstant) times units of work, plus the operations no constant charges (NodeCostTerms). The formula CPU of node_resource_usage_and_cost is now computed from those same terms, so the charge and its terms cannot drift; the terms also carry the charge added in each formula's own order, so every node's CPU is the same f64 as on main. No constant value changes, and no plan changes: asap_planner --run-until stage3 --format text is byte-identical to main on 47 workloads (timings masked).
  • Example: a per-series max_over_time(latency[5m]) over 1,000 series at 1 Hz is 300,000 × HashAggregateOperationsPerRow (16) + 300,000 × AggregateMeasureOperationsPerRow (4) + 30,000 × OperationsPerGroupPerRawBatch (170) + 1,000 × OutputRowOperationsPerGroup (2,500) = 13.6 M, the formula's charge. With 140 per group visit it is 12.7 M.

Review guide

  • Base: main at 1760a69f5. Not stacked. Three commits: the approved tests, the implementation, then the final review fixes.
  • Read first: crates/cost/src/node/cost_terms.rs (the types), then node_usage_and_cost_terms in crates/cost/src/node/usage/mod.rs (each operator arm builds terms; charged turns them into the estimate's CPU).
  • Careful review:
    • operations_per_unit.rs: each per-unit helper now returns NodeCostTerms instead of f64. The formulas are the same; check each arm's constant and units.
    • NodeCostTerms::operations_at_built_in_values (private): plus, plus_terms, times and divided_by update it in the order the formula is written, so operations() is the formula's own f64 (e.g. rows × (update + carried label) + visits × 170), while operations_with(..) re-adds the units per constant (equal up to summation order, ≤ 1e-12 relative).
    • The hash aggregate in usage/mod.rs: estimate_operator_with_terms charges rows × ⌈per-row operations⌉ without a constant; attributing_to_constants moves the per-row terms times rows onto their constants and leaves the rounding without one, keeping the charge unchanged.
    • hash_aggregate_terms_per_row: "at least one operation per row for the measures" became an explicit term without a constant (max(1 − measures, 0)).
  • Mechanical: every per-unit constant is now pub(crate) (the four exact-distinct shape parameters stay private); helpers returning terms are named *_terms*; estimate_operator, merge_operations_per_state and merge_output_operations are deleted (callers use estimate_operator_with_terms(..)?.0 and merge_terms_per_state(..).operations()).

Behavior: before → after

Before: node_resource_usage_and_cost returns 13,600,000 CPU operations per execution for the aggregate above, and its detail string "20 ops per row, 30000 group visits".

After: the same charge and detail. In addition, node_cost_terms on the same node returns

units_per_constant: {HashAggregateOperationsPerRow: 300000, AggregateMeasureOperationsPerRow: 300000,
                     OperationsPerGroupPerRawBatch: 30000, OutputRowOperationsPerGroup: 1000}
operations_without_constant: 0

and operations_with(CostConstant::operations_per_unit) is 13,600,000. This serves the measurement harness's validate step, which fits constants from node profiles × terms.

Plans: asap_planner --run-until stage3 --format text (default deployment) on the 47 workloads of the final review (the planner-layering examples, random-mixed-seed-862(-long), the memo-examples PromQL and SQL sets, and the rangeheavy / rollupheavy evaluation workloads including rangeheavy, rangeheavy-8users, rangeheavy-8users-counter and rollupheavy) prints byte-identical text to main once the build and solve times are masked. The previous head summed each node's CPU term by term and flipped between tied plans (objectives equal to 7 digits) on those four workloads; the charge now keeps the formula's summation order.

Interfaces

crates/cost/src/node/cost_terms.rs (new), crates/cost/src/lib.rs

+/// A named per-unit constant of the cost formulas: CPU operations per unit
+/// of work, e.g. `OperationsPerGroupPerRawBatch` (170 per group visit).
+/// JSON: snake_case, e.g. `"operations_per_group_per_raw_batch"`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CostConstant {
+    TimeRangeOperationsPerRow,
+    OperationsPerGroupPerRawBatch,
+    // ... one variant per `const NAME: f64` of operations_per_unit.rs (37),
+    // except the four exact-distinct shape parameters
+    KllMergeOperationsPerOutputGroup,
+}
+impl CostConstant {
+    /// Its built-in value: the constant of the same name in
+    /// `operations_per_unit`, e.g. 170.0 for `OperationsPerGroupPerRawBatch`.
+    pub fn operations_per_unit(self) -> f64;
+}
+/// One node's formula CPU operations per execution, as units of work per
+/// named constant plus the operations no named constant charges.
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct NodeCostTerms {
+    /// Per constant, the units it multiplies in one execution, e.g. 30,000
+    /// group visits for `OperationsPerGroupPerRawBatch`.
+    pub units_per_constant: BTreeMap<CostConstant, f64>,
+    /// Operations charged without a named constant: one per row a `Scan`
+    /// reads, a predicate's operations per row, the rounding a hash
+    /// aggregate applies to its per-row operations.
+    pub operations_without_constant: f64,
+    /// The formula's charge: these terms at the built-in values, added in
+    /// the order the formula adds them (private).
+    operations_at_built_in_values: f64,
+}
+impl NodeCostTerms {
+    /// `operations_without_constant + Σ units × value(constant)`; with
+    /// `CostConstant::operations_per_unit` it is the formula's charge up
+    /// to floating-point summation order.
+    pub fn operations_with(&self, value: impl Fn(CostConstant) -> f64) -> f64;
+}
+/// The terms of `node`'s formula CPU per execution, from the inputs
+/// `node_resource_usage_and_cost` takes except the rate (which scales
+/// executions, not units). Independent of
+/// `settings.measured_operation_costs` and `frozen_calibration_factor`.
+pub fn node_cost_terms<'a>(
+    node: &'a PhysicalASAPDAGNode,
+    producers: &[ProducerOutput<'a>],
+    window_ms: Option<u64>,
+    data: &DataWorkload,
+    settings: &'a CostInputs,
+) -> Result<NodeCostTerms, AnalyticalCostError>;

 // crates/cost/src/lib.rs
+pub use node::cost_terms::{node_cost_terms, CostConstant, NodeCostTerms};

Kept although unread in this repository: node_cost_terms, NodeCostTerms and CostConstant's serde names have no reader in the planner itself; their consumer is the measurement harness's validate step, which reads a node's terms through the engine adapter and keys refitted constants by these JSON names.

Crate-internal changes (not public API):

 // crates/cost/src/node/operations_per_unit.rs: the helpers return terms
-pub(crate) fn update_operations_per_row(..) -> f64;
+pub(crate) fn update_terms_per_row(..) -> NodeCostTerms;
-pub(crate) fn hash_aggregate_operations_per_row(..) -> f64;
+pub(crate) fn hash_aggregate_terms_per_row(..) -> NodeCostTerms;
-pub(crate) fn exact_distinct_value_operations_per_row(..) -> f64;
+pub(crate) fn exact_distinct_value_terms_per_row(..) -> NodeCostTerms;
-pub(crate) fn estimate_operations_per_group(..) -> f64;
+pub(crate) fn estimate_terms_per_group(..) -> NodeCostTerms;
-pub(crate) fn chain_emit_operations_per_state(..) -> f64;
+pub(crate) fn chain_emit_terms_per_state(..) -> NodeCostTerms;
-pub(crate) fn pass_through_merge_operations(..) -> f64;
+pub(crate) fn pass_through_merge_terms(..) -> NodeCostTerms;
-pub(crate) fn merge_operations_per_state(..) -> f64;
+pub(crate) fn merge_terms_per_state(..) -> NodeCostTerms;
-pub(crate) fn merge_output_operations(..) -> f64;
+pub(crate) fn merge_output_terms(..) -> NodeCostTerms;
 // crates/cost/src/node/cost_terms.rs
+impl NodeCostTerms {
+    pub(crate) fn operations(&self) -> f64;          // the formula's charge
+    pub(crate) fn of(constant, units) -> Self;
+    pub(crate) fn without_constant(operations) -> Self;
+    pub(crate) fn plus(self, constant, units) -> Self;
+    pub(crate) fn plus_terms(self, other: &NodeCostTerms) -> Self;
+    pub(crate) fn times(self, times: f64) -> Self;
+    pub(crate) fn divided_by(self, parts: f64) -> Self;   // exact-distinct inserts over the rows
+    pub(crate) fn attributing_to_constants(self, part: &NodeCostTerms) -> Self;
+}
 // crates/cost/src/node/analytical.rs
-pub(crate) fn estimate_operator(operator, statistics) -> Result<ResourceEstimate, AnalyticalCostError>;
+pub(crate) fn estimate_operator_with_terms(operator, statistics)
+    -> Result<(ResourceEstimate, NodeCostTerms), AnalyticalCostError>;
 // crates/cost/src/node/usage/mod.rs
+pub(crate) fn node_usage_and_cost_terms<'a>(..)   // node_resource_usage_and_cost = its first part
+    -> Result<(NodeResourceUsageAndCost<'a>, NodeCostTerms), AnalyticalCostError>;

Usage (test 9 checks these numbers):

// The workload's data facts: 1,000 series of `latency` sampled every second.
let data = thousand_series_sampled_every(1_000);
// Stage 3 costs this node of a query-time plan for max_over_time(latency[5m]):
// a per-series Aggregate[Max] over the 300,000 rows of a 5 min TimeRange.
let aggregate = per_series_aggregate(AggIntent::Max { col: None });
// The node's terms under default cost inputs (10 s raw batches).
let terms = node_cost_terms(&aggregate, &[raw_rows(&range, "latency", 300_000, 300_000)],
    None, &data, &CostInputs::default())?;
// At the built-in values: 13,600,000 operations, the formula's charge.
let charged = terms.operations_with(CostConstant::operations_per_unit);
// A refit that sets 140 operations per group visit: 13.6 M − 30 × 30,000 = 12.7 M.
let refit = terms.operations_with(|c| if c == CostConstant::OperationsPerGroupPerRawBatch { 140.0 } else { c.operations_per_unit() });

Design scope

New item Scope Why it is general
crates/cost/src/node/cost_terms.rs node cost (asap-cost, node), beside usage and operations_per_unit it describes one node's formula CPU, whatever the operator
CostConstant node cost one variant per per-unit constant of operations_per_unit.rs; the key a checked-in reference calibration will use. The four exact-distinct cache and size parameters are not variants: they shape units, they do not charge them
NodeCostTerms node cost units per constant plus the remainder; any operator's charge has this form
node_cost_terms node cost a free function with node_resource_usage_and_cost's inputs minus the rate; NodeCost does not carry the terms

Algorithm changes

None. Each formula is the same expression, now written as units per named constant; the charge is those units at the built-in values, added in the formula's order (the same f64 as main). A hash aggregate's ceil of its per-row operations stays, its rounding charged without a constant (test 6).

Decisions and open questions

Verification

cargo nextest is not installed on the build machine, so the tests ran with cargo test. cargo fmt --all --check is clean, and so is cargo clippy -p asap-cost -p asap-accuracy -p asap-stage1-pass2-reuse-candidates -p asap-devtools --all-targets.

Commands, run on this branch and on main (1760a69f5), compared by test name:

Command main This PR
cargo test -p asap-cost (lib) 83 passed 98 passed: the same 83, plus the 13 new tests and 2 from the final review (the_charge_adds_terms_in_the_formula_s_order, attributing_to_constants_keeps_the_charge)
cargo test -p asap-accuracy (lib) 46 passed 46 passed
cargo test -p asap-stage1-pass2-reuse-candidates --lib 28 passed 28 passed
cargo test -p asap-devtools --lib rqe_atomic_costs 2 passed 2 passed
cargo test --release -p asap-devtools --test corpus_snapshots -- --include-ignored (includes sketch_plans_match_snapshots) 8 passed the same 8 passed
cargo test --release -p asap-integration-tests --test integration -- stage3_objective default_cost_plan_ranking 30 passed the same 30 passed

No plan and no snapshot changes. At the final-review head, asap_planner --run-until stage3 --format text prints byte-identical text to main on all 47 final-review workloads (build and solve times masked); main itself is deterministic on them under the same masking. The cargo test --release rows above (corpus snapshots, integration) were run at the earlier head; the final-review commit reran cargo test -p asap-cost --lib, cargo clippy -p asap-cost --all-targets and cargo fmt --all --check. Planning time is unchanged within noise (median of 3 runs, one core: rangeheavy 67.9 ms on main, 63.3 ms here; w01-q3-q8 84.8 ms and 85.8 ms).

Final review fixes

Item Status
1. Functions returning NodeCostTerms named *_terms* (update_terms_per_row, hash_aggregate_terms_per_row, exact_distinct_value_terms_per_row, aggregate_measure_terms_per_row, estimate_terms_per_group, chain_emit_terms_per_state, pass_through_merge_terms, carried_label_terms_per_row) done
2. Test-only wrappers deleted (estimate_operator, merge_output_operations); merge_operations_per_state deleted too, plan/cost.rs uses merge_terms_per_state(..).operations() done
3. CostConstant::ALL deleted; the tests enumerate the constants from their JSON-name list, still checked against the constants of operations_per_unit.rs done
4. Hash-aggregate rounding: no back-solve; attributing_to_constants moves the per-row terms onto their constants, leaving the rounding done
5. Body: "kept although unread" line naming the harness consumer; Interfaces relinked to 5f080872b done
6. extend-asap-aware-mapping.md step 5: a new constant needs a CostConstant variant and its match arm done
7. Tie flips on rangeheavy, rangeheavy-8users, rangeheavy-8users-counter, rollupheavy: main's summation order restored (the terms carry the charge in formula order); byte-identical text to main on all 47 workloads done
8. (optional) fixed array instead of BTreeMap declined: no measured effect, and the sparse map keeps a node's terms to the constants it charges

Follow-ups

  • Moving the constants into a checked-in reference calibration keyed by CostConstant.
  • Terms for a whole plan (summing per node with multipliers), if the harness needs them.

@zzylol zzylol added cost-model Cost formulas, statistics, ranking, and selection testing Corpus, regression, differential, or benchmark tests labels Nov 16, 2026
@zzylol
zzylol force-pushed the test/node-cost-terms branch from d6f4a92 to 0868ecb Compare November 16, 2026 22:35
@zzylol zzylol changed the title test(cost): node_cost_terms splits a node's formula CPU into named per-unit constants (tests only) feat(cost): node_cost_terms splits a node's formula CPU into named per-unit constants Nov 16, 2026
@zzylol
zzylol marked this pull request as ready for review November 16, 2026 22:35
…unit constants times units (tests only)

Adds the twelve tests of node_cost_terms and CostConstant, and the
declarations they compile against. The bodies are todo!() until the tests
are approved, so eleven tests fail; the JSON-name test passes on the
derived serde of the declared enum.
…onstants times units, the charge computed from those terms

CostConstant names each per-unit constant of operations_per_unit.rs (values
unchanged). The per-unit helpers and estimate_operator now return
NodeCostTerms, and node_resource_usage_and_cost computes its formula CPU as
those terms at the built-in values, so the charge and its terms cannot
drift. A hash aggregate's rounding of its per-row operations stays, charged
without a constant. node_cost_terms returns the terms taken before a
measured entry or the calibration factor applies.
@zzylol
zzylol force-pushed the test/node-cost-terms branch from 0868ecb to 32aac84 Compare November 17, 2026 00:47
@zzylol zzylol added the enhancement New feature or request label Nov 17, 2026
…'s summation order; terms-named helpers; no test-only wrappers

NodeCostTerms carries the charge at the built-in values, added in the
order each formula adds its terms, so every node's CPU is the same f64 as
before the terms existed and tied plans no longer flip on summation order.
The exact-distinct insert terms are divided by the rows as a whole
(divided_by), and the hash aggregate attributes its per-row terms to their
constants (attributing_to_constants) instead of back-solving the rounding.

Helpers returning terms are named *_terms*; estimate_operator,
merge_operations_per_state, merge_output_operations and CostConstant::ALL
are deleted (tests enumerate the constants from their JSON names). The
extension guide says a new per-unit constant needs a CostConstant variant.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cost-model Cost formulas, statistics, ranking, and selection enhancement New feature or request testing Corpus, regression, differential, or benchmark tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant