refactor(bigquery): update code samples to use strings for table and dataset IDs

bigquery/docs/usage/encryption.rst

@@ -36,7 +36,7 @@ Cloud KMS for the destination table.
 Copy a table, using a customer-managed encryption key from Cloud KMS for the
 destination table.
 
-.. literalinclude:: ../snippets.py
+.. literalinclude:: ../samples/copy_table_cmek.py
    :language: python
    :dedent: 4
    :start-after: [START bigquery_copy_table_cmek]
@@ -45,7 +45,7 @@ destination table.
 Write query results to a table, using a customer-managed encryption key from
 Cloud KMS for the destination table.
 
-.. literalinclude:: ../snippets.py
+.. literalinclude:: ../samples/client_query_destination_table_cmek.py
    :language: python
    :dedent: 4
    :start-after: [START bigquery_query_destination_table_cmek]

bigquery/docs/usage/queries.rst

@@ -17,7 +17,7 @@ Run a query and wait for it to finish with the
 Run a dry run query
 ^^^^^^^^^^^^^^^^^^^
 
-.. literalinclude:: ../snippets.py
+.. literalinclude:: ../samples/client_query_dry_run.py
    :language: python
    :dedent: 4
    :start-after: [START bigquery_query_dry_run]
@@ -30,7 +30,7 @@ Writing query results to a destination table
 See BigQuery documentation for more information on
 `writing query results <https://cloud.google.com/bigquery/docs/writing-results>`_.
 
-.. literalinclude:: ../snippets.py
+.. literalinclude:: ../samples/client_query_destination_table.py
    :language: python
    :dedent: 4
    :start-after: [START bigquery_query_destination_table]

bigquery/samples/client_query.py

@@ -31,7 +31,8 @@ def client_query(client):
         LIMIT 20
     """
     query_job = client.query(
-        query, location="US"  # Must match the destination dataset(s) location.
+        query,
+        location="US",  # Must match the source and the destination dataset(s) location.
     )  # Make an API request.
 
     print("The query data:")

bigquery/samples/client_query_add_column.py

@@ -0,0 +1,54 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+def client_query_add_column(client, table_id):
+
+    # [START bigquery_add_column_query_append]
+    from google.cloud import bigquery
+
+    # TODO(developer): Construct a BigQuery client object.
+    # client = bigquery.Client()
+
+    # TODO(developer): Set table_id to the ID of the destination table.
+    # table_id = "your-project.your_dataset.your_table_name"
+
+    # Retrieves the destination table and checks the length of the schema.
+    table = client.get_table(table_id)  # Make an API request.
+    print("Table {} contains {} columns".format(table_id, len(table.schema)))
+
+    # Configures the query to append the results to a destination table,
+    # allowing field addition.
+    job_config = bigquery.QueryJobConfig()
+    job_config.schema_update_options = [
+        bigquery.SchemaUpdateOption.ALLOW_FIELD_ADDITION
+    ]
+    job_config.destination = table_id
+    job_config.write_disposition = bigquery.WriteDisposition.WRITE_APPEND
+
+    # Start the query, passing in the extra configuration.
+    query_job = client.query(
+        # In this example, the existing table contains only the 'full_name' and
+        # 'age' columns, while the results of this query will contain an
+        # additional 'favorite_color' column.
+        'SELECT "Timmy" as full_name, 85 as age, "Blue" as favorite_color;',
+        location="US",  # Must match the source and the destination dataset(s) location.
+        job_config=job_config,
+    )  # Make an API request.
+    query_job.result()  # Wait for the job to complete.
+
+    # Checks the updated length of the schema.
+    table = client.get_table(table_id)  # Make an API request.
+    print("Table {} now contains {} columns".format(table_id, len(table.schema)))
+    # [END bigquery_add_column_query_append]

bigquery/samples/client_query_batch.py

@@ -0,0 +1,45 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+def client_query_batch(client):
+
+    # [START bigquery_query_batch]
+    from google.cloud import bigquery
+
+    # TODO(developer): Construct a BigQuery client object.
+    # client = bigquery.Client()
+
+    job_config = bigquery.QueryJobConfig()
+
+    # Run at batch priority, which won't count toward concurrent rate limit.
+    job_config.priority = bigquery.QueryPriority.BATCH
+    sql = """
+        SELECT corpus
+        FROM `bigquery-public-data.samples.shakespeare`
+        GROUP BY corpus;
+    """
+
+    # Start the query, passing in the extra configuration.
+    query_job = client.query(
+        sql, location="US", job_config=job_config
+    )  # Make an API request.
+
+    # Check on the progress by getting the job's updated state. Once the state
+    # is `DONE`, the results are ready.
+    query_job = client.get_job(query_job.job_id, location="US")  # Make an API request.
+
+    print("Job {} is currently in state {}".format(query_job.job_id, query_job.state))
+    # [END bigquery_query_batch]
+    return query_job

bigquery/samples/client_query_destination_table.py

@@ -0,0 +1,46 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+def client_query_destination_table(client, table_id):
+
+    # [START bigquery_query_destination_table]
+    from google.cloud import bigquery
+
+    # TODO(developer): Construct a BigQuery client object.
+    # client = bigquery.Client()
+
+    # TODO(developer): Set table_id to the ID of the destination table.
+    # table_id = "your-project.your_dataset.your_table_name"
+
+    job_config = bigquery.QueryJobConfig()
+
+    table = client.get_table(table_id)  # Make an API request.
+    job_config.destination = table
+    sql = """
+        SELECT corpus
+        FROM `bigquery-public-data.samples.shakespeare`
+        GROUP BY corpus;
+    """
+
+    # Start the query, passing in the extra configuration.
+    query_job = client.query(
+        sql,
+        location="US",  # Must match the source and the destination dataset(s) location.
+        job_config=job_config,
+    )  # Make an API request.
+    query_job.result()  # Wait for the job to complete.
+
+    print("Query results loaded to the table {}".format(table_id))
+    # [END bigquery_query_destination_table]

bigquery/samples/client_query_destination_table_cmek.py

@@ -0,0 +1,50 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+def client_query_destination_table_cmek(client, table_id, kms_key_name):
+
+    # [START bigquery_query_destination_table_cmek]
+    from google.cloud import bigquery
+
+    # TODO(developer): Construct a BigQuery client object.
+    # client = bigquery.Client()
+
+    # TODO(developer): Set table_id to the ID of the destination table.
+    # table_id = "your-project.your_dataset.your_table_name"
+
+    # Set the encryption key to use for the destination.
+    # TODO(developer): Replace this key with a key you have created in KMS.
+    # kms_key_name = "projects/{}/locations/{}/keyRings/{}/cryptoKeys/{}".format(
+    #     your-project, location, your-ring, your-key
+    # )
+
+    job_config = bigquery.QueryJobConfig()
+    job_config.destination = table_id
+
+    encryption_config = bigquery.EncryptionConfiguration(kms_key_name=kms_key_name)
+    job_config.destination_encryption_configuration = encryption_config
+
+    # Start the query, passing in the extra configuration.
+    query_job = client.query(
+        "SELECT 17 AS my_col;",
+        location="US",  # Must match the source and the destination dataset(s) location.
+        job_config=job_config,
+    )  # Make an API request.
+    query_job.result()  # Wait for the job to complete.
+
+    table = client.get_table(table_id)  # Make an API request.
+    if table.encryption_configuration.kms_key_name == kms_key_name:
+        print("The destination table is written using the encryption configuration")
+    # [END bigquery_query_destination_table_cmek]

bigquery/samples/client_query_destination_table_legacy.py

@@ -0,0 +1,51 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+def client_query_destination_table_legacy(client, table_id):
+
+    # [START bigquery_query_legacy_large_results]
+    from google.cloud import bigquery
+
+    # TODO(developer): Construct a BigQuery client object.
+    # client = bigquery.Client()
+
+    # TODO(developer): Set table_id to the ID of the destination table.
+    # table_id = "your-project.your_dataset.your_table_name"
+
+    job_config = bigquery.QueryJobConfig()
+
+    # Set use_legacy_sql to True to use legacy SQL syntax.
+    job_config.use_legacy_sql = True
+
+    # Set the destination table.
+    table = client.get_table(table_id)  # Make an API request.
+    job_config.destination = table
+    job_config.allow_large_results = True
+    sql = """
+        SELECT corpus
+        FROM [bigquery-public-data:samples.shakespeare]
+        GROUP BY corpus;
+    """
+
+    # Start the query, passing in the extra configuration.
+    query_job = client.query(
+        sql,
+        location="US",  # Must match the source and the destination dataset(s) location.
+        job_config=job_config,
+    )  # Make an API request.
+    query_job.result()  # Wait for the job to complete.
+
+    print("Query results loaded to the table {}".format(table_id))
+    # [END bigquery_query_legacy_large_results]

bigquery/samples/client_query_dry_run.py

@@ -0,0 +1,43 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+def client_query_dry_run(client):
+
+    # [START bigquery_query_dry_run]
+    from google.cloud import bigquery
+
+    # TODO(developer): Construct a BigQuery client object.
+    # client = bigquery.Client()
+
+    job_config = bigquery.QueryJobConfig()
+    job_config.dry_run = True
+    job_config.use_query_cache = False
+
+    # Start the query, passing in the extra configuration.
+    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="US",  # Must match the source and the destination dataset(s) location.
+        job_config=job_config,
+    )  # Make an API request.
+
+    # A dry run query completes immediately.
+    print("This query will process {} bytes.".format(query_job.total_bytes_processed))
+    # [END bigquery_query_dry_run]
+    return query_job

bigquery/samples/client_query_legacy_sql.py

@@ -0,0 +1,44 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+def client_query_legacy_sql(client):
+
+    # [START bigquery_query_legacy]
+    from google.cloud import bigquery
+
+    # TODO(developer): Construct a BigQuery client object.
+    # client = bigquery.Client()
+
+    query = (
+        "SELECT name FROM [bigquery-public-data:usa_names.usa_1910_2013] "
+        'WHERE state = "TX" '
+        "LIMIT 100"
+    )
+
+    # Set use_legacy_sql to True to use legacy SQL syntax.
+    job_config = bigquery.QueryJobConfig()
+    job_config.use_legacy_sql = True
+
+    # Start the query, passing in the extra configuration.
+    query_job = client.query(
+        query,
+        location="US",  # Must match the source and the destination dataset(s) location.
+        job_config=job_config,
+    )  # Make an API request.
+
+    print("The query data:")
+    for row in query_job:
+        print(row)
+    # [END bigquery_query_legacy]