Query cost

A cost card prices one chart or query and shows how much work it does. You meet it in the Model AI chat: ask Model AI to check the cost of a chart, and its reply carries the card. A Model Builder uses the same modes when it checks how fast a model's charts are.

Read a cost card

• The card names its mode: Estimate, Measured, Analyzed or What if.
• A band chip rates the result: Fast, Watch or Slow.
• The Chart {chartId} badge names the chart it priced; its hover title names the report behind it.
• An RLS applied badge marks a run that used row-level security. See Row-level security and View as.
• When the card also carries an analysis or a what-if, the estimate folds into an Estimate disclosure. Show SQL opens the statement behind the chart.
• Small hints mark figures that need care: approx. for a counted estimate, and Timings from the server's query log when the figures come from the database's own log.

Price a chart before you run it

Estimate prices the execution plan without running the query behind the chart.

• The tiles read Rows read, Marks and Parts. Below them, a per-table breakdown lists each table the chart reads with its Parts kept and Granules kept, or nothing skipped when no index helps. Expand a row to see the table's indexes and the keys they cover.
• When the database cannot estimate on a table, the rows are counted from the granules the indexes keep, and the figure carries the approx. hint.
• When no estimate can be produced, the card reads No estimate: with the reason in place of the figures.

Measure the real speed of a chart

Measured runs the query behind the chart one to three times, three by default, and reports the median. The result cache is off for these runs, so each run measures the query and not an answer the database kept from an earlier run.

• The median carries the hint median of {n} runs, cache off, and a chip lists each finished run.
• A run that fails is marked run {i} failed. A run that cannot start, because no query slot was free or the call ran low on its budget, is skipped with a note, and the median covers the runs that finished.
• A run that hits the hard limit stops the measuring: the card reads Timed out at 30 s or Ran out of memory, and the band turns Slow.
• When the card carries an estimate too, it compares the two: Estimated {n} rows · measured {m} rows in {t}.
• When every finished run came from the database's own log, the card says Timings from the server's query log.

See the plan of one run

Analyzed runs the query behind the chart once, with execution analysis, and reads the plan it produced.

• The tiles read Ran in, with a one run badge, plus Rows read, Bytes read and Peak memory. The card hints that "ClickHouse rounds these numbers in its EXPLAIN ANALYZE text."
• Up to eight findings name what to look at: the slowest step, the biggest read, a join that built a large hash table, a join whose output was misestimated, and a runtime filter that ran.
• The step table reads Plan step, Rows in → out and Slowest stage, and counts the steps it left out, for example 3 faster steps not shown. Expand a step for its stages, its join facts and its runtime filters.
• When the runtime-filter comparison ran, the card adds With and without runtime-filter index analysis and a line like With it: 32.3% fewer rows read, 30% less time.
• Show EXPLAIN ANALYZE opens the plan text; only its first part is shown.
• When the estimate for the chart is red, an analysis is refused instead of run.

Price an index you have not built

What if prices hypothetical indexes on the tables the chart reads. It builds nothing: the candidates live only in one session. One run prices up to six candidates on up to three stored tables.

• A candidate row carries a label such as I1, its type, for example minmax, set(100) or bloom_filter(0.01), its granularity {n}, and what it would save: skips {n}%, with {baseline} → {marks} marks · {bytes}.
• The source badge says how the figure was obtained: measured on a sample, measured, estimated or applicability only.
• A candidate worth taking is marked Suggested. When the best candidates do better together than the best single one, a Together row prices them as a group.
• A per-table card shows the baseline, {n} marks kept in {m} parts, and counts the chart's filters: {n} of the chart's filters modelled, then {n} filter(s) is/are not part of the estimate. Show probe SQL opens the query the estimate used.
• A table with nothing to estimate reads Not applicable with the reason, or Timed out, Failed or Skipped when it ended differently. A view cannot be estimated: hypothetical indexes exist only on stored tables, and the card explains where the index belongs.
• The notes under the card add the caveats: an empirical skip ratio is an upper bound, and a row-level security rule that uses a SQL condition is not part of the estimate.

Cost bands and refusals

• The band shown is the worse of the estimate's band and the measured run's band. A run that times out or runs out of memory makes the band Slow.
• A red estimate stops the run before it starts: the card heads the refusal Not run: the estimate is red. The message explains that the estimate reads more rows than the budget allows, and asks you to make the chart cheaper first, or to report the estimate as it is.
• When row-level security denies you every row, there is nothing to price: the card reads "row-level security denies every row to you, so the statement does not run and there is nothing to price."
• When too much cost work runs at once, the card asks you to retry: "too many cost analyses and what-if estimates are running right now; try again in a minute."
• A note on a very large chart warns that during working hours its timing competes with every dashboard for the query slots, and suggests measuring it again outside working hours.
• Other messages from this area are collected in Troubleshooting.

When a mode is not available

Analyzed and What if need a newer database version than some servers run. On such a server the card shows Needs ClickHouse {version}, names the version the server runs, and says the mode becomes available after the upgrade; Estimate and Measured keep working. If the server's version cannot be read at the moment, the card says so and asks you to try again in a minute.

Questions, answered

Why was my chart not run?

The estimate came out over its budget (red), so the run was refused before it started. The card heads it Not run: the estimate is red: make the chart cheaper first through the performance ladder, or report the estimate as it is.

What do Fast, Watch and Slow mean?

They are the card's cost bands: Fast is the best and Slow the worst. The chip always reports the worse of the estimate's band and the measured run's band, and a run that times out or runs out of memory reads Slow.

What does "cache off" mean on a measured cost?

The measured runs repeat the query with the result cache off, so each run measures the query itself, not an answer the database kept from an earlier run.

Where do the measured timings come from?

From the runs as they complete. When every finished run could be matched in the database's own log, the card says Timings from the server's query log; when the log does not return the runs in time, the card uses the progress numbers and says so.

Why did only some of my runs count?

A run that cannot start, because no query slot was free or the call ran low on its budget, is skipped with a note; the median is computed over the runs that finished.

Why is the estimate marked approximate?

The database could not estimate on those tables, so the rows were counted from the granules the indexes keep. The figure is an approximation, not a measurement.

Why are some modes not available here?

Analyzed and What if need a newer database version. The card shows Needs ClickHouse {version} and names the version this server runs; Estimate and Measured still work. If the version cannot be read yet, try again in a minute.

Does a what-if build anything?

No. The hypothetical indexes live only in one session and nothing is built: "Nothing was built: the hypothetical indexes lived only in one ClickHouse session."

Which tables can a what-if price?

Up to three stored tables the chart reads, one estimate per table with that table's own filters. A view cannot be estimated, because hypothetical indexes exist only on stored tables.

What does "Together" mean?

It prices the best candidates as one group and shows what they would skip together, next to the best single candidate's share.

Why does the card say there is nothing to price?

Row-level security denies you every row of the chart, so the statement does not run and there is nothing to price. See Row-level security and View as.