Adding BigQuery snippet for QueryParameters (#1455)

Author: garrettjonesgoogle

google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQuery.java

@@ -972,6 +972,30 @@ Page<List<FieldValue>> listTableData(String datasetId, String tableId,
    * }
    * }</pre>
    *
+   * <p>Example of running a query with query parameters.
+   * <pre> {@code
+   * String query = "SELECT distinct(corpus) FROM `bigquery-public-data.samples.shakespeare` where word_count > ?";
+   * QueryRequest request = QueryRequest.newBuilder(query)
+   *     .setUseLegacySql(false) // standard SQL is required to use query parameters
+   *     .addPositionalParameter(QueryParameterValue.int64(5))
+   *     .build();
+   * QueryResponse response = bigquery.query(request);
+   * // Wait for things to finish
+   * while (!response.jobCompleted()) {
+   *   Thread.sleep(1000);
+   *   response = bigquery.getQueryResults(response.getJobId());
+   * }
+   * if (response.hasErrors()) {
+   *   // handle errors
+   * }
+   * QueryResult result = response.getResult();
+   * Iterator<List<FieldValue>> rowIterator = result.iterateAll();
+   * while (rowIterator.hasNext()) {
+   *   List<FieldValue> row = rowIterator.next();
+   *   // do something with the data
+   * }
+   * }</pre>
+   *
    * @throws BigQueryException upon failure
    */
   QueryResponse query(QueryRequest request);

google-cloud-examples/src/main/java/com/google/cloud/examples/bigquery/snippets/BigQuerySnippets.java

@@ -46,6 +46,7 @@
 import com.google.cloud.bigquery.JobInfo;
 import com.google.cloud.bigquery.JobStatistics.LoadStatistics;
 import com.google.cloud.bigquery.QueryJobConfiguration;
+import com.google.cloud.bigquery.QueryParameterValue;
 import com.google.cloud.bigquery.QueryRequest;
 import com.google.cloud.bigquery.QueryResponse;
 import com.google.cloud.bigquery.QueryResult;
@@ -609,6 +610,36 @@ public QueryResponse runQuery(String query) throws InterruptedException {
     return response;
   }
 
+  /**
+   * Example of running a query with query parameters.
+   */
+  // [TARGET query(QueryRequest)]
+  // [VARIABLE "SELECT distinct(corpus) FROM `bigquery-public-data.samples.shakespeare` where word_count > @wordCount"]
+  public QueryResponse runQueryWithParameters(String query) throws InterruptedException {
+    // [START runQueryWithParameters]
+    QueryRequest request = QueryRequest.newBuilder(query)
+        .setUseLegacySql(false) // standard SQL is required to use query parameters
+        .addNamedParameter("wordCount", QueryParameterValue.int64(5))
+        .build();
+    QueryResponse response = bigquery.query(request);
+    // Wait for things to finish
+    while (!response.jobCompleted()) {
+      Thread.sleep(1000);
+      response = bigquery.getQueryResults(response.getJobId());
+    }
+    if (response.hasErrors()) {
+      // handle errors
+    }
+    QueryResult result = response.getResult();
+    Iterator<List<FieldValue>> rowIterator = result.iterateAll();
+    while (rowIterator.hasNext()) {
+      List<FieldValue> row = rowIterator.next();
+      // do something with the data
+    }
+    // [END runQueryWithParameters]
+    return response;
+  }
+
   /**
    * Example of getting the results of query.
    */

google-cloud-examples/src/test/java/com/google/cloud/examples/bigquery/snippets/ITBigQuerySnippets.java

@@ -73,6 +73,8 @@ public class ITBigQuerySnippets {
   private static final String OTHER_DATASET = RemoteBigQueryHelper.generateDatasetName();
   private static final String QUERY =
       "SELECT unique(corpus) FROM [bigquery-public-data:samples.shakespeare]";
+  private static final String QUERY_WITH_PARAMETERS =
+      "SELECT distinct(corpus) FROM `bigquery-public-data.samples.shakespeare` where word_count > @wordCount";
   private static final Function<Job, JobId> TO_JOB_ID_FUNCTION = new Function<Job, JobId>() {
     @Override
     public JobId apply(Job job) {
@@ -271,4 +273,15 @@ public void testRunQuery() throws InterruptedException {
     assertNotNull(result);
     assertTrue(bigquerySnippets.cancelJobFromId(queryResponse.getJobId().getJob()));
   }
+
+  @Test
+  public void testRunQueryWithParameters() throws InterruptedException {
+    QueryResponse queryResponse = bigquerySnippets.runQueryWithParameters(QUERY_WITH_PARAMETERS);
+    assertNotNull(queryResponse);
+    assertTrue(queryResponse.jobCompleted());
+    assertFalse(queryResponse.hasErrors());
+    QueryResult result = queryResponse.getResult();
+    assertNotNull(result);
+    assertTrue(bigquerySnippets.cancelJob(queryResponse.getJobId().getJob()));
+  }
 }