docs: migrate code from googleapis/python-bigquery

packages/google-cloud-bigquery/samples/AUTHORING_GUIDE.md

@@ -0,0 +1 @@
+See https://github.com/GoogleCloudPlatform/python-docs-samples/blob/main/AUTHORING_GUIDE.md

packages/google-cloud-bigquery/samples/CONTRIBUTING.md

@@ -0,0 +1 @@
+See https://github.com/GoogleCloudPlatform/python-docs-samples/blob/main/CONTRIBUTING.md

packages/google-cloud-bigquery/samples/add_empty_column.py

@@ -0,0 +1,40 @@
+# 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 add_empty_column(table_id: str) -> None:
+    # [START bigquery_add_empty_column]
+    from google.cloud import bigquery
+
+    # Construct a BigQuery client object.
+    client = bigquery.Client()
+
+    # TODO(developer): Set table_id to the ID of the table
+    #                  to add an empty column.
+    # table_id = "your-project.your_dataset.your_table_name"
+
+    table = client.get_table(table_id)  # Make an API request.
+
+    original_schema = table.schema
+    new_schema = original_schema[:]  # Creates a copy of the schema.
+    new_schema.append(bigquery.SchemaField("phone", "STRING"))
+
+    table.schema = new_schema
+    table = client.update_table(table, ["schema"])  # Make an API request.
+
+    if len(table.schema) == len(original_schema) + 1 == len(new_schema):
+        print("A new column has been added.")
+    else:
+        print("The column has not been added.")
+    # [END bigquery_add_empty_column]

packages/google-cloud-bigquery/samples/browse_table_data.py

@@ -0,0 +1,56 @@
+# 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 browse_table_data(table_id: str) -> None:
+    # [START bigquery_browse_table]
+
+    from google.cloud import bigquery
+
+    # Construct a BigQuery client object.
+    client = bigquery.Client()
+
+    # TODO(developer): Set table_id to the ID of the table to browse data rows.
+    # table_id = "your-project.your_dataset.your_table_name"
+
+    # Download all rows from a table.
+    rows_iter = client.list_rows(table_id)  # Make an API request.
+
+    # Iterate over rows to make the API requests to fetch row data.
+    rows = list(rows_iter)
+    print("Downloaded {} rows from table {}".format(len(rows), table_id))
+
+    # Download at most 10 rows.
+    rows_iter = client.list_rows(table_id, max_results=10)
+    rows = list(rows_iter)
+    print("Downloaded {} rows from table {}".format(len(rows), table_id))
+
+    # Specify selected fields to limit the results to certain columns.
+    table = client.get_table(table_id)  # Make an API request.
+    fields = table.schema[:2]  # First two columns.
+    rows_iter = client.list_rows(table_id, selected_fields=fields, max_results=10)
+    print("Selected {} columns from table {}.".format(len(rows_iter.schema), table_id))
+
+    rows = list(rows_iter)
+    print("Downloaded {} rows from table {}".format(len(rows), table_id))
+
+    # Print row data in tabular format.
+    rows_iter = client.list_rows(table_id, max_results=10)
+    format_string = "{!s:<16} " * len(rows_iter.schema)
+    field_names = [field.name for field in rows_iter.schema]
+    print(format_string.format(*field_names))  # Prints column headers.
+
+    for row in rows_iter:
+        print(format_string.format(*row))  # Prints row data.
+    # [END bigquery_browse_table]

packages/google-cloud-bigquery/samples/client_list_jobs.py

@@ -0,0 +1,49 @@
+# 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_list_jobs() -> None:
+    # [START bigquery_list_jobs]
+
+    from google.cloud import bigquery
+
+    import datetime
+
+    # Construct a BigQuery client object.
+    client = bigquery.Client()
+
+    # List the 10 most recent jobs in reverse chronological order.
+    # Omit the max_results parameter to list jobs from the past 6 months.
+    print("Last 10 jobs:")
+    for job in client.list_jobs(max_results=10):  # API request(s)
+        print("{}".format(job.job_id))
+
+    # The following are examples of additional optional parameters:
+
+    # Use min_creation_time and/or max_creation_time to specify a time window.
+    print("Jobs from the last ten minutes:")
+    ten_mins_ago = datetime.datetime.utcnow() - datetime.timedelta(minutes=10)
+    for job in client.list_jobs(min_creation_time=ten_mins_ago):
+        print("{}".format(job.job_id))
+
+    # Use all_users to include jobs run by all users in the project.
+    print("Last 10 jobs run by all users:")
+    for job in client.list_jobs(max_results=10, all_users=True):
+        print("{} run by user: {}".format(job.job_id, job.user_email))
+
+    # Use state_filter to filter by job state.
+    print("Last 10 jobs done:")
+    for job in client.list_jobs(max_results=10, state_filter="DONE"):
+        print("{}".format(job.job_id))
+    # [END bigquery_list_jobs]

packages/google-cloud-bigquery/samples/client_load_partitioned_table.py

@@ -0,0 +1,49 @@
+# 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_load_partitioned_table(table_id: str) -> None:
+    # [START bigquery_load_table_partitioned]
+    from google.cloud import bigquery
+
+    # Construct a BigQuery client object.
+    client = bigquery.Client()
+
+    # TODO(developer): Set table_id to the ID of the table to create.
+    # table_id = "your-project.your_dataset.your_table_name"
+
+    job_config = bigquery.LoadJobConfig(
+        schema=[
+            bigquery.SchemaField("name", "STRING"),
+            bigquery.SchemaField("post_abbr", "STRING"),
+            bigquery.SchemaField("date", "DATE"),
+        ],
+        skip_leading_rows=1,
+        time_partitioning=bigquery.TimePartitioning(
+            type_=bigquery.TimePartitioningType.DAY,
+            field="date",  # Name of the column to use for partitioning.
+            expiration_ms=7776000000,  # 90 days.
+        ),
+    )
+    uri = "gs://cloud-samples-data/bigquery/us-states/us-states-by-date.csv"
+
+    load_job = client.load_table_from_uri(
+        uri, table_id, job_config=job_config
+    )  # Make an API request.
+
+    load_job.result()  # Wait for the job to complete.
+
+    table = client.get_table(table_id)
+    print("Loaded {} rows to table {}".format(table.num_rows, table_id))
+    # [END bigquery_load_table_partitioned]

packages/google-cloud-bigquery/samples/client_query_add_column.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_add_column(table_id: str) -> None:
+    # [START bigquery_add_column_query_append]
+    from google.cloud import bigquery
+
+    # 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(
+        destination=table_id,
+        schema_update_options=[bigquery.SchemaUpdateOption.ALLOW_FIELD_ADDITION],
+        write_disposition=bigquery.WriteDisposition.WRITE_APPEND,
+    )
+
+    # Start the query, passing in the extra configuration.
+    client.query_and_wait(
+        # 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;',
+        job_config=job_config,
+    )  # Make an API request and wait for 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]

packages/google-cloud-bigquery/samples/client_query_batch.py

@@ -0,0 +1,53 @@
+# 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.
+
+import typing
+
+if typing.TYPE_CHECKING:
+    from google.cloud import bigquery
+
+
+def client_query_batch() -> "bigquery.QueryJob":
+    # [START bigquery_query_batch]
+    from google.cloud import bigquery
+
+    # Construct a BigQuery client object.
+    client = bigquery.Client()
+
+    job_config = bigquery.QueryJobConfig(
+        # Run at batch priority, which won't count toward concurrent rate limit.
+        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, 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 = typing.cast(
+        "bigquery.QueryJob",
+        client.get_job(
+            query_job.job_id, location=query_job.location
+        ),  # 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

packages/google-cloud-bigquery/samples/client_query_destination_table.py

@@ -0,0 +1,40 @@
+# 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(table_id: str) -> None:
+    # [START bigquery_query_destination_table]
+    from google.cloud import bigquery
+
+    # 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(destination=table_id)
+
+    sql = """
+        SELECT corpus
+        FROM `bigquery-public-data.samples.shakespeare`
+        GROUP BY corpus;
+    """
+
+    # Start the query, passing in the extra configuration.
+    client.query_and_wait(
+        sql, job_config=job_config
+    )  # Make an API request and wait for the query to finish.
+
+    print("Query results loaded to the table {}".format(table_id))
+    # [END bigquery_query_destination_table]

packages/google-cloud-bigquery/samples/client_query_destination_table_clustered.py

@@ -0,0 +1,43 @@
+# Copyright 2020 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_clustered(table_id: str) -> None:
+    # [START bigquery_query_clustered_table]
+    from google.cloud import bigquery
+
+    # 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"
+
+    sql = "SELECT * FROM `bigquery-public-data.samples.shakespeare`"
+    cluster_fields = ["corpus"]
+
+    job_config = bigquery.QueryJobConfig(
+        clustering_fields=cluster_fields, destination=table_id
+    )
+
+    # Start the query, passing in the extra configuration.
+    client.query_and_wait(
+        sql, job_config=job_config
+    )  # Make an API request and wait for job to complete.
+
+    table = client.get_table(table_id)  # Make an API request.
+    if table.clustering_fields == cluster_fields:
+        print(
+            "The destination table is written using the cluster_fields configuration."
+        )
+    # [END bigquery_query_clustered_table]