BigQuery: Add snippet to run a dry run query. (googleapis#5119)

tswast · web-flow · commit 80641f41d1ac · 2018-03-26T15:33:01.000-07:00
* BigQuery: Add snippet to run a dry run query.

* Fix region tags. Make sample more readable.
* Add commented imports and client creation.
* Move query text to query call.
* Add print statement for query bytes processing.
diff --git a/docs/bigquery/snippets.py b/docs/bigquery/snippets.py
@@ -1760,6 +1760,35 @@ def test_client_query_w_param(client):
     # [END client_query_w_param]
 
 
+def test_client_query_dry_run(client):
+    """Run a dry run query"""
+
+    # [START bigquery_query_dry_run]
+    # from google.cloud import bigquery
+    # client = bigquery.Client()
+    job_config = bigquery.QueryJobConfig()
+    job_config.dry_run = True
+    job_config.use_query_cache = False
+    query_job = client.query(
+        ('SELECT name, COUNT(*) as name_count '
+         'FROM `bigquery-public-data.usa_names.usa_1910_2013` '
+         "WHERE state = 'WA' "
+         'GROUP BY name'),
+        # Location must match that of the dataset(s) referenced in the query.
+        location='US',
+        job_config=job_config)  # API request
+
+    # A dry run query completes immediately.
+    assert query_job.state == 'DONE'
+    assert query_job.dry_run
+
+    print("This query will process {} bytes.".format(
+        query_job.total_bytes_processed))
+    # [END bigquery_query_dry_run]
+
+    assert query_job.total_bytes_processed > 0
+
+
 def test_client_list_jobs(client):
     """List jobs for a project."""
 
diff --git a/docs/bigquery/usage.rst b/docs/bigquery/usage.rst
@@ -346,6 +346,12 @@ Querying data
   - Use of the ``timeout`` parameter is optional. The query will continue to
     run in the background even if it takes longer the timeout allowed.
 
+Run a dry run query
+~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: snippets.py
+   :start-after: [START bigquery_query_dry_run]
+   :end-before: [END bigquery_query_dry_run]
 
 Writing query results to a destination table
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
