Dry Run

A dry run executes the preparation and validation for an operation while deliberately stopping short of the effect. The intended change is not applied, and what you get back is a prediction: what would happen, and at what cost. Side outputs vary by tool; Terraform, for one, can save its plan to a file. The pattern appears across tooling — infrastructure planners, package managers, file synchronization utilities — and the shared purpose is to make a consequential action reviewable before it becomes irreversible.

In BigQuery the consequence being previewed is money. Because on-demand queries are billed by bytes processed, the useful question before running an unfamiliar query is how much data it will read. A dry run answers exactly that without executing the query or incurring a charge, which makes it the cheapest cost control available: it costs nothing and requires no configuration.

Google’s Estimate and control costs page places it alongside a related habit. “Don’t run queries to explore or preview table data,” it advises; instead, “in the Google Cloud console, on the table details page, click the Preview tab to sample the data.” Previewing a table is free, while SELECT * against a large table is not — and a dry run is how you check which situation you are in before committing.

An estimate is not enforcement, and the distinction is the most useful thing to take from the term. A dry run tells you a number; it does nothing to stop anyone from running the query anyway. Enforcement is a separate setting: “Use the maximum bytes billed setting to limit query costs when using the on-demand pricing model,” where “if the number of estimated bytes is beyond the limit, then the query fails without incurring a charge.” Estimation informs a person, enforcement constrains a job — and automated pipelines need the second, because no one is reading the estimate at three in the morning.

The estimate also has a documented limit worth knowing. Against a clustered table, “you don’t receive an accurate query cost estimate before query execution because the number of storage blocks to be scanned is not known before query execution.” The figure becomes an upper bound rather than a prediction, so a dry run on a clustered table tells you the worst case, not the likely case.

Distinguish a dry run from an execution plan. A plan such as EXPLAIN describes how the engine intends to do the work — which joins, in what order, with what redistribution. BigQuery’s own query execution plan is a different thing: it reports the stages and timing of a query that has already run, so it is available after execution, not before. A dry run reports the scale of the work and validates that the query is well-formed and the referenced objects exist. Use the plan to understand why a query is slow, and the dry run to decide whether to run it at all.

Further reading

• Google, Estimate and control costs
• Introduction to clustered tables

See the worked examples in BigQuery Architecture and Cost.