From 2e76dccff197343a8b52657aa6261885862f7664 Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Tue, 17 Nov 2026 04:50:20 +0000 Subject: [PATCH 1/2] feat(bigquery): add bigquery_query_biglake_gcs_temp_table sample to query a temporary BigLake table on Cloud Storage Problem: The BigQuery documentation (https://cloud.google.com/bigquery/docs/query-cloud-storage-using-biglake) needs a standalone, tested Python code sample demonstrating how to query a temporary BigLake table on Cloud Storage (region tag `bigquery_query_biglake_gcs_temp_table`). Solution: - Add `query_biglake_gcs_temp_table(project_id: str, connection_id: str) -> None` in `bigquery/biglake/bigquery_query_biglake_gcs_temp_table.py` (Configure an ephemeral BigLake table definition over Cloud Storage files using ExternalConfig and query it within a single job.) - Add unit tests (`bigquery/biglake/bigquery_query_biglake_gcs_temp_table_test.py`) covering both the success path and API error handling (`GoogleAPICallError`) --- .../bigquery_query_biglake_gcs_temp_table.py | 71 +++++++++++++++++++ ...query_query_biglake_gcs_temp_table_test.py | 69 ++++++++++++++++++ 2 files changed, 140 insertions(+) create mode 100644 bigquery/biglake/bigquery_query_biglake_gcs_temp_table.py create mode 100644 bigquery/biglake/tests/bigquery_query_biglake_gcs_temp_table_test.py diff --git a/bigquery/biglake/bigquery_query_biglake_gcs_temp_table.py b/bigquery/biglake/bigquery_query_biglake_gcs_temp_table.py new file mode 100644 index 0000000000..140123bc43 --- /dev/null +++ b/bigquery/biglake/bigquery_query_biglake_gcs_temp_table.py @@ -0,0 +1,71 @@ +# Copyright 2026 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. + +# [START bigquery_query_biglake_gcs_temp_table] +from google.cloud import bigquery + + +def query_biglake_gcs_temp_table( + project_id: str, + connection_id: str, +) -> None: + """Configures and queries a temporary BigLake table backed by Cloud Storage. + + Args: + project_id: Google Cloud project ID (for example, 'example-project'). + connection_id: Fully qualified BigQuery Cloud Resource connection ID + (for example, 'projects/example-project/locations/us/connections/example-conn'). + """ + client = bigquery.Client(project=project_id) + temp_table_name = "example_us_states_temp" + source_uri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv" + prefix_filter = "W%" + + # Bind the Cloud Resource connection and explicit schema to a temporary CSV ExternalConfig. + external_config = bigquery.ExternalConfig("CSV") + external_config.source_uris = [source_uri] + external_config.connection_id = connection_id + external_config.schema = [ + bigquery.SchemaField("name", "STRING"), + bigquery.SchemaField("post_abbr", "STRING"), + ] + external_config.csv_options.skip_leading_rows = 1 + + job_config = bigquery.QueryJobConfig( + table_definitions={temp_table_name: external_config}, + query_parameters=[ + bigquery.ScalarQueryParameter("prefix_filter", "STRING", prefix_filter), + ], + ) + sql = f""" + SELECT + name, + post_abbr + FROM `{temp_table_name}` + WHERE post_abbr LIKE @prefix_filter + ORDER BY post_abbr ASC + LIMIT 10; + """ + + print(f"Querying temporary BigLake table {temp_table_name} via {connection_id}") + query_job = client.query(sql, job_config=job_config) + rows = list(query_job.result()) + + print(f"Resource ID: {connection_id}") + print(f"Job ID: {query_job.job_id}") + print(f"Rows Returned: {len(rows)}") + print(f"Source URI: {source_uri}") + + +# [END bigquery_query_biglake_gcs_temp_table] diff --git a/bigquery/biglake/tests/bigquery_query_biglake_gcs_temp_table_test.py b/bigquery/biglake/tests/bigquery_query_biglake_gcs_temp_table_test.py new file mode 100644 index 0000000000..36ef99210c --- /dev/null +++ b/bigquery/biglake/tests/bigquery_query_biglake_gcs_temp_table_test.py @@ -0,0 +1,69 @@ +# Copyright 2026 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. + +from unittest import mock + +from google.api_core import exceptions +import pytest + +from .. import bigquery_query_biglake_gcs_temp_table + + +def test_query_biglake_gcs_temp_table_success( + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], +) -> None: + mock_client = mock.MagicMock() + mock_job = mock.MagicMock() + mock_job.job_id = "example-job-123" + mock_job.result.return_value = [mock.MagicMock(), mock.MagicMock()] + mock_client.query.return_value = mock_job + monkeypatch.setattr( + bigquery_query_biglake_gcs_temp_table.bigquery, + "Client", + lambda project=None: mock_client, + ) + + bigquery_query_biglake_gcs_temp_table.query_biglake_gcs_temp_table( + project_id="example-project", + connection_id="projects/example-project/locations/us/connections/example-conn", + ) + + captured = capsys.readouterr() + assert ( + "Resource ID: projects/example-project/locations/us/connections/example-conn" + in captured.out + ) + assert "Rows Returned: 2" in captured.out + assert mock_client.query.called + + +def test_query_biglake_gcs_temp_table_error( + monkeypatch: pytest.MonkeyPatch, +) -> None: + mock_client = mock.MagicMock() + mock_job = mock.MagicMock() + mock_job.result.side_effect = exceptions.NotFound("connection not found") + mock_client.query.return_value = mock_job + monkeypatch.setattr( + bigquery_query_biglake_gcs_temp_table.bigquery, + "Client", + lambda project=None: mock_client, + ) + + with pytest.raises(exceptions.GoogleAPICallError): + bigquery_query_biglake_gcs_temp_table.query_biglake_gcs_temp_table( + project_id="example-project", + connection_id="projects/example-project/locations/us/connections/example-conn", + ) From 4e94861b30b348d71a907aafd2e635c4c75138ec Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Tue, 17 Nov 2026 05:05:48 +0000 Subject: [PATCH 2/2] test(bigquery): stub Client with MagicMock in bigquery_query_biglake_gcs_temp_table tests Problem: The tests replaced the client class with `lambda project=None: mock_client`. A lambda only accepts that one keyword, so the test would break for reasons unrelated to the sample if the constructor call changed, and it records nothing, so the tests could not verify how the client was created. Solution: Patch the client class with `mock.MagicMock(return_value=mock_client)` and assert in the success test that the sample constructed it exactly once with the expected arguments. --- .../bigquery_query_biglake_gcs_temp_table_test.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/bigquery/biglake/tests/bigquery_query_biglake_gcs_temp_table_test.py b/bigquery/biglake/tests/bigquery_query_biglake_gcs_temp_table_test.py index 36ef99210c..ab382e61a6 100644 --- a/bigquery/biglake/tests/bigquery_query_biglake_gcs_temp_table_test.py +++ b/bigquery/biglake/tests/bigquery_query_biglake_gcs_temp_table_test.py @@ -29,10 +29,9 @@ def test_query_biglake_gcs_temp_table_success( mock_job.job_id = "example-job-123" mock_job.result.return_value = [mock.MagicMock(), mock.MagicMock()] mock_client.query.return_value = mock_job + mock_client_cls = mock.MagicMock(return_value=mock_client) monkeypatch.setattr( - bigquery_query_biglake_gcs_temp_table.bigquery, - "Client", - lambda project=None: mock_client, + bigquery_query_biglake_gcs_temp_table.bigquery, "Client", mock_client_cls ) bigquery_query_biglake_gcs_temp_table.query_biglake_gcs_temp_table( @@ -47,6 +46,7 @@ def test_query_biglake_gcs_temp_table_success( ) assert "Rows Returned: 2" in captured.out assert mock_client.query.called + mock_client_cls.assert_called_once_with(project="example-project") def test_query_biglake_gcs_temp_table_error( @@ -56,10 +56,9 @@ def test_query_biglake_gcs_temp_table_error( mock_job = mock.MagicMock() mock_job.result.side_effect = exceptions.NotFound("connection not found") mock_client.query.return_value = mock_job + mock_client_cls = mock.MagicMock(return_value=mock_client) monkeypatch.setattr( - bigquery_query_biglake_gcs_temp_table.bigquery, - "Client", - lambda project=None: mock_client, + bigquery_query_biglake_gcs_temp_table.bigquery, "Client", mock_client_cls ) with pytest.raises(exceptions.GoogleAPICallError):