When you run a query in the bq
command-line tool, you can use the --dry_run
flag to estimate
the number of bytes read by the query. You can also use the dryRun
parameter
when submitting a query job using the API or client libraries.
You can use the estimate returned by the dry run to calculate query costs in the pricing calculator. You are not charged for performing the dry run.
Permissions required
At a minimum, to run a query job, you must be
granted bigquery.jobs.create
permissions. In order for the query job to
complete successfully, you must also be granted access to the tables or views
referenced by the query. Access to the tables or views can be granted at the
following levels, listed in order of range of resources allowed (largest to
smallest):
- at a high level in the Google Cloud resource hierarchy such as the project, folder, or organization level
- at the dataset level
- at the table level
The following predefined IAM roles include bigquery.jobs.create
permissions:
bigquery.user
bigquery.jobUser
bigquery.admin
In addition, if a user has bigquery.datasets.create
permissions, when that
user creates a dataset, they are granted bigquery.dataOwner
access to it.
bigquery.dataOwner
access gives the user the ability to query tables and views
in the dataset.
For more information on IAM roles in BigQuery, see Predefined roles and permissions.
Performing dry runs
You can perform a dry run for a query job by using:
- The
--dry_run
flag with thequery
command in thebq
command-line tool - The
dryRun
parameter in the job configuration when you use the API or client libraries
Performing a dry run
To perform a dry run:
Console
Currently, you cannot perform a dry run by using the Cloud Console.
bq
Enter a query like the following using the --dry_run
flag.
bq query \ --use_legacy_sql=false \ --dry_run \ 'SELECT COUNTRY, AIRPORT, IATA FROM `project_id`.dataset.airports LIMIT 1000'
The command produces the following response:
Query successfully validated. Assuming the tables are not modified, running this query will process 10918 bytes of data.
API
To perform a dry run by using the API, submit a query job with
dryRun
set to true
in the
JobConfiguration
type.
Go
Before trying this sample, follow the Go setup instructions in the BigQuery Quickstart Using Client Libraries. For more information, see the BigQuery Go API reference documentation.
Java
Before trying this sample, follow the Java setup instructions in the BigQuery Quickstart Using Client Libraries. For more information, see the BigQuery Java API reference documentation.
Python
To perform a dry run using the Python client library, set the
QueryJobConfig.dry_run
property to True
.
Client.query()
always returns a completed
QueryJob
when provided a dry run query configuration.
Before trying this sample, follow the Python setup instructions in the BigQuery Quickstart Using Client Libraries. For more information, see the BigQuery Python API reference documentation.