Add support for query parameters

docs/bigquery-usage.rst

@@ -209,6 +209,12 @@ Run a query which can be expected to complete within bounded time:
    :start-after: [START client_run_sync_query]
    :end-before: [END client_run_sync_query]
 
+Run a query using a named query parameter:
+
+.. literalinclude:: bigquery_snippets.py
+   :start-after: [START client_run_sync_query_w_param]
+   :end-before: [END client_run_sync_query_w_param]
+
 If the rows returned by the query do not fit into the initial response,
 then we need to fetch the remaining rows via
 :meth:`~google.cloud.bigquery.query.QueryResults.fetch_data`:

docs/bigquery_snippets.py

@@ -461,13 +461,9 @@ def do_something_with(_):
         pass
 
     # [START client_list_jobs]
-    jobs, token = client.list_jobs()   # API request
-    while True:
-        for job in jobs:
-            do_something_with(job)
-        if token is None:
-            break
-        jobs, token = client.list_jobs(page_token=token)  # API request
+    job_iterator = client.list_jobs()   # API request
+    for job in job_iterator:
+        do_something_with(job)
     # [END client_list_jobs]
 
 
@@ -489,6 +485,30 @@ def client_run_sync_query(client, _):
     # [END client_run_sync_query]
 
 
+@snippet
+def client_run_sync_query_w_param(client, _):
+    """Run a synchronous query using a query parameter"""
+    QUERY_W_PARM = (
+        'SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` '
+        'WHERE state = @state')
+    LIMIT = 100
+    LIMITED = '%s LIMIT %d' % (QUERY_W_PARM, LIMIT)
+    TIMEOUT_MS = 1000
+
+    # [START client_run_sync_query_w_param]
+    from google.cloud.bigquery import ScalarQueryParameter
+    param = ScalarQueryParameter('state', 'STRING', 'TX')
+    query = client.run_sync_query(LIMITED, query_parameters=[param])
+    query.use_legacy_sql = False
+    query.timeout_ms = TIMEOUT_MS
+    query.run()             # API request
+
+    assert query.complete
+    assert len(query.rows) == LIMIT
+    assert [field.name for field in query.schema] == ['name']
+    # [END client_run_sync_query_w_param]
+
+
 @snippet
 def client_run_sync_query_paged(client, _):
     """Run a synchronous query with paged results."""