From cf7d2cd728367e0a1bd22f383a4decdac894365d Mon Sep 17 00:00:00 2001 From: Shuowei Li Date: Thu, 16 Jul 2026 21:58:37 +0000 Subject: [PATCH 01/11] docs: add python_libraries sample snippets --- bigquery/bigframes/python_libraries.py | 138 ++++++++++++++++++++ bigquery/bigframes/python_libraries_test.py | 45 +++++++ 2 files changed, 183 insertions(+) create mode 100644 bigquery/bigframes/python_libraries.py create mode 100644 bigquery/bigframes/python_libraries_test.py diff --git a/bigquery/bigframes/python_libraries.py b/bigquery/bigframes/python_libraries.py new file mode 100644 index 00000000000..53d12d1e94e --- /dev/null +++ b/bigquery/bigframes/python_libraries.py @@ -0,0 +1,138 @@ +# 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 +# +# http://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 query_standard_sql(): + # [START bigquery_bigframes_query] + import bigframes.pandas as bpd + + # Set partial ordering mode as the default configuration for BigQuery DataFrames. + bpd.options.bigquery.ordering_mode = "partial" + + sql = """ + SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current` + WHERE state = 'TX' + LIMIT 100 + """ + + # Run a query alongside existing SQL. The project will be determined from default credentials. + df = bpd.read_gbq(sql) + + # Run a query after explicitly specifying a project. + bpd.options.bigquery.project = "your-project-id" + df = bpd.read_gbq(sql) + # [END bigquery_bigframes_query] + return df + + +def query_legacy_sql(): + # [START bigquery_bigframes_query_legacy] + import bigframes.pandas as bpd + + # Set partial ordering mode as the default configuration for BigQuery DataFrames. + bpd.options.bigquery.ordering_mode = "partial" + + sql = """ + SELECT name FROM [bigquery-public-data:usa_names.usa_1910_current] + WHERE state = 'TX' + LIMIT 100 + """ + + # Run a query using legacy SQL syntax. + query_config = {"query": {"useLegacySql": True}} + df = bpd.read_gbq(sql, configuration=query_config) + # [END bigquery_bigframes_query_legacy] + return df + + +def query_bqstorage(): + # [START bigquery_bigframes_query_bqstorage] + import bigframes.pandas as bpd + + # Set partial ordering mode as the default configuration for BigQuery DataFrames. + bpd.options.bigquery.ordering_mode = "partial" + + sql = """ + SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current` + WHERE state = 'TX' + LIMIT 100 + """ + + # Read query results into a server-side DataFrame without downloading data. + df = bpd.read_gbq(sql) + + # When downloading results to an in-memory pandas DataFrame, bigquery-dataframes + # automatically uses the BigQuery Storage API if installed. + pandas_df = df.to_pandas() + # [END bigquery_bigframes_query_bqstorage] + return pandas_df + + +def query_parameters(): + # [START bigquery_bigframes_query_parameters] + import bigframes.pandas as bpd + + # Set partial ordering mode as the default configuration for BigQuery DataFrames. + bpd.options.bigquery.ordering_mode = "partial" + + sql = """ + SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current` + WHERE state = @state + LIMIT 100 + """ + + query_config = { + "query": { + "parameterMode": "NAMED", + "queryParameters": [ + { + "name": "state", + "parameterType": {"type": "STRING"}, + "parameterValue": {"value": "TX"}, + } + ], + } + } + + df = bpd.read_gbq(sql, configuration=query_config) + # [END bigquery_bigframes_query_parameters] + return df + + +def upload_from_dataframe(): + # [START bigquery_bigframes_upload_from_dataframe] + import pandas as pd + + import bigframes.pandas as bpd + + # Set partial ordering mode as the default configuration for BigQuery DataFrames. + bpd.options.bigquery.ordering_mode = "partial" + + # Create a local pandas DataFrame. + df = pd.DataFrame( + { + "my_string": ["a", "b", "c"], + "my_int64": [1, 2, 3], + "my_float64": [4.0, 5.0, 6.0], + } + ) + + # Convert the local pandas DataFrame to a BigQuery DataFrame. + bq_df = bpd.read_pandas(df) + + # Write the DataFrame to a BigQuery table. + table_id = "your-project.your_dataset.your_table_name" + bq_df.to_gbq(table_id, if_exists="replace") + # [END bigquery_bigframes_upload_from_dataframe] + return bq_df diff --git a/bigquery/bigframes/python_libraries_test.py b/bigquery/bigframes/python_libraries_test.py new file mode 100644 index 00000000000..7643d8d222b --- /dev/null +++ b/bigquery/bigframes/python_libraries_test.py @@ -0,0 +1,45 @@ +# 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 +# +# http://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 pytest + +import python_libraries + + +@pytest.mark.skip(reason="Placeholder project ID 'your-project-id' (b/522845525)") +def test_query_standard_sql(): + df = python_libraries.query_standard_sql() + assert df is not None + + +@pytest.mark.skip(reason="Legacy SQL syntax not supported by BigQuery DataFrames (b/522845525)") +def test_query_legacy_sql(): + df = python_libraries.query_legacy_sql() + assert df is not None + + +def test_query_bqstorage(): + pandas_df = python_libraries.query_bqstorage() + assert pandas_df is not None + + +def test_query_parameters(): + df = python_libraries.query_parameters() + assert df is not None + + +@pytest.mark.skip(reason="Requires a writable table destination (b/522845525)") +def test_upload_from_dataframe(): + bq_df = python_libraries.upload_from_dataframe() + assert bq_df is not None From 154eed9d759725e34c4198385410fc7f4ac73ed7 Mon Sep 17 00:00:00 2001 From: Shuowei Li Date: Thu, 16 Jul 2026 22:08:36 +0000 Subject: [PATCH 02/11] docs: rename python_libraries to bigframes_queries --- .../{python_libraries.py => bigframes_queries.py} | 0 ...n_libraries_test.py => bigframes_queries_test.py} | 12 ++++++------ 2 files changed, 6 insertions(+), 6 deletions(-) rename bigquery/bigframes/{python_libraries.py => bigframes_queries.py} (100%) rename bigquery/bigframes/{python_libraries_test.py => bigframes_queries_test.py} (80%) diff --git a/bigquery/bigframes/python_libraries.py b/bigquery/bigframes/bigframes_queries.py similarity index 100% rename from bigquery/bigframes/python_libraries.py rename to bigquery/bigframes/bigframes_queries.py diff --git a/bigquery/bigframes/python_libraries_test.py b/bigquery/bigframes/bigframes_queries_test.py similarity index 80% rename from bigquery/bigframes/python_libraries_test.py rename to bigquery/bigframes/bigframes_queries_test.py index 7643d8d222b..c425ca1ea1c 100644 --- a/bigquery/bigframes/python_libraries_test.py +++ b/bigquery/bigframes/bigframes_queries_test.py @@ -14,32 +14,32 @@ import pytest -import python_libraries +import bigframes_queries @pytest.mark.skip(reason="Placeholder project ID 'your-project-id' (b/522845525)") def test_query_standard_sql(): - df = python_libraries.query_standard_sql() + df = bigframes_queries.query_standard_sql() assert df is not None @pytest.mark.skip(reason="Legacy SQL syntax not supported by BigQuery DataFrames (b/522845525)") def test_query_legacy_sql(): - df = python_libraries.query_legacy_sql() + df = bigframes_queries.query_legacy_sql() assert df is not None def test_query_bqstorage(): - pandas_df = python_libraries.query_bqstorage() + pandas_df = bigframes_queries.query_bqstorage() assert pandas_df is not None def test_query_parameters(): - df = python_libraries.query_parameters() + df = bigframes_queries.query_parameters() assert df is not None @pytest.mark.skip(reason="Requires a writable table destination (b/522845525)") def test_upload_from_dataframe(): - bq_df = python_libraries.upload_from_dataframe() + bq_df = bigframes_queries.upload_from_dataframe() assert bq_df is not None From b4f1c868e5b1ea920ed4cf94eca0726a192a051f Mon Sep 17 00:00:00 2001 From: Shuowei Li Date: Thu, 16 Jul 2026 15:15:54 -0700 Subject: [PATCH 03/11] Update bigquery/bigframes/bigframes_queries.py Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- bigquery/bigframes/bigframes_queries.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bigquery/bigframes/bigframes_queries.py b/bigquery/bigframes/bigframes_queries.py index 53d12d1e94e..07b9dcdc28a 100644 --- a/bigquery/bigframes/bigframes_queries.py +++ b/bigquery/bigframes/bigframes_queries.py @@ -30,7 +30,7 @@ def query_standard_sql(): df = bpd.read_gbq(sql) # Run a query after explicitly specifying a project. - bpd.options.bigquery.project = "your-project-id" + bpd.options.bigquery.project = project_id df = bpd.read_gbq(sql) # [END bigquery_bigframes_query] return df From d2d3d25beca2283f94e74f691470b1688b1d6eac Mon Sep 17 00:00:00 2001 From: Shuowei Li Date: Thu, 16 Jul 2026 22:21:50 +0000 Subject: [PATCH 04/11] docs: update pytest skip reasons for welcome page snippets --- bigquery/bigframes/bigframes_queries_test.py | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/bigquery/bigframes/bigframes_queries_test.py b/bigquery/bigframes/bigframes_queries_test.py index c425ca1ea1c..fb46daacfbc 100644 --- a/bigquery/bigframes/bigframes_queries_test.py +++ b/bigquery/bigframes/bigframes_queries_test.py @@ -17,13 +17,17 @@ import bigframes_queries -@pytest.mark.skip(reason="Placeholder project ID 'your-project-id' (b/522845525)") +@pytest.mark.skip( + reason="Placeholder project ID 'your-project-id' cannot be executed by pytest, but snippet is required for welcome page documentation." +) def test_query_standard_sql(): df = bigframes_queries.query_standard_sql() assert df is not None -@pytest.mark.skip(reason="Legacy SQL syntax not supported by BigQuery DataFrames (b/522845525)") +@pytest.mark.skip( + reason="Legacy SQL syntax is not supported for execution by BigQuery DataFrames, but snippet is required for welcome page documentation." +) def test_query_legacy_sql(): df = bigframes_queries.query_legacy_sql() assert df is not None @@ -39,7 +43,9 @@ def test_query_parameters(): assert df is not None -@pytest.mark.skip(reason="Requires a writable table destination (b/522845525)") +@pytest.mark.skip( + reason="Requires a writable destination table so pytest skips execution, but snippet is required for welcome page documentation." +) def test_upload_from_dataframe(): bq_df = bigframes_queries.upload_from_dataframe() assert bq_df is not None From 7348654e9c6d968c5c9f792bd3f19dbcda22919c Mon Sep 17 00:00:00 2001 From: Shuowei Li Date: Thu, 16 Jul 2026 23:24:29 +0000 Subject: [PATCH 05/11] docs: fix flake8 lint errors in bigframes_queries --- bigquery/bigframes/bigframes_queries.py | 1 + bigquery/bigframes/bigframes_queries_test.py | 3 +-- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/bigquery/bigframes/bigframes_queries.py b/bigquery/bigframes/bigframes_queries.py index 07b9dcdc28a..08eb2c5e716 100644 --- a/bigquery/bigframes/bigframes_queries.py +++ b/bigquery/bigframes/bigframes_queries.py @@ -30,6 +30,7 @@ def query_standard_sql(): df = bpd.read_gbq(sql) # Run a query after explicitly specifying a project. + project_id = "your-project-id" bpd.options.bigquery.project = project_id df = bpd.read_gbq(sql) # [END bigquery_bigframes_query] diff --git a/bigquery/bigframes/bigframes_queries_test.py b/bigquery/bigframes/bigframes_queries_test.py index fb46daacfbc..e155ca5c312 100644 --- a/bigquery/bigframes/bigframes_queries_test.py +++ b/bigquery/bigframes/bigframes_queries_test.py @@ -12,9 +12,8 @@ # See the License for the specific language governing permissions and # limitations under the License. -import pytest - import bigframes_queries +import pytest @pytest.mark.skip( From 7621ff1927f4c89ec665ca52431e32d5c4352f2c Mon Sep 17 00:00:00 2001 From: Shuowei Li Date: Fri, 17 Jul 2026 10:18:05 -0700 Subject: [PATCH 06/11] Update bigquery/bigframes/bigframes_queries.py Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- bigquery/bigframes/bigframes_queries.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bigquery/bigframes/bigframes_queries.py b/bigquery/bigframes/bigframes_queries.py index 08eb2c5e716..6542d6b73da 100644 --- a/bigquery/bigframes/bigframes_queries.py +++ b/bigquery/bigframes/bigframes_queries.py @@ -111,7 +111,7 @@ def query_parameters(): return df -def upload_from_dataframe(): +def upload_from_dataframe(table_id: str = "your-project.your_dataset.your_table_name"): # [START bigquery_bigframes_upload_from_dataframe] import pandas as pd From 1898f73fec670be02db213792e60fc090afaf10f Mon Sep 17 00:00:00 2001 From: Shuowei Li Date: Fri, 17 Jul 2026 10:18:14 -0700 Subject: [PATCH 07/11] Update bigquery/bigframes/bigframes_queries.py Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- bigquery/bigframes/bigframes_queries.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bigquery/bigframes/bigframes_queries.py b/bigquery/bigframes/bigframes_queries.py index 6542d6b73da..fcc74f54cfd 100644 --- a/bigquery/bigframes/bigframes_queries.py +++ b/bigquery/bigframes/bigframes_queries.py @@ -13,7 +13,7 @@ # limitations under the License. -def query_standard_sql(): +def query_standard_sql(project_id: str = "your-project-id"): # [START bigquery_bigframes_query] import bigframes.pandas as bpd From 37f00ed9d667fbcd558bddaa7bafc7f2e32ba999 Mon Sep 17 00:00:00 2001 From: Shuowei Li Date: Mon, 20 Jul 2026 23:57:31 +0000 Subject: [PATCH 08/11] docs: address review comments --- bigquery/bigframes/bigframes_queries.py | 70 ++++++-------------- bigquery/bigframes/bigframes_queries_test.py | 28 ++------ bigquery/bigframes/conftest.py | 13 ++++ 3 files changed, 42 insertions(+), 69 deletions(-) diff --git a/bigquery/bigframes/bigframes_queries.py b/bigquery/bigframes/bigframes_queries.py index fcc74f54cfd..a974fddc9db 100644 --- a/bigquery/bigframes/bigframes_queries.py +++ b/bigquery/bigframes/bigframes_queries.py @@ -13,13 +13,15 @@ # limitations under the License. -def query_standard_sql(project_id: str = "your-project-id"): - # [START bigquery_bigframes_query] - import bigframes.pandas as bpd +import bigframes.pandas as bpd +import pandas as pd - # Set partial ordering mode as the default configuration for BigQuery DataFrames. - bpd.options.bigquery.ordering_mode = "partial" +# Set partial ordering mode as the default configuration for BigQuery DataFrames. +bpd.options.bigquery.ordering_mode = "partial" + +# [START bigquery_bigframes_query] +def query_standard_sql(project_id: str = "your-project-id") -> bpd.DataFrame: sql = """ SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE state = 'TX' @@ -30,40 +32,17 @@ def query_standard_sql(project_id: str = "your-project-id"): df = bpd.read_gbq(sql) # Run a query after explicitly specifying a project. - project_id = "your-project-id" + bpd.close_session() bpd.options.bigquery.project = project_id df = bpd.read_gbq(sql) - # [END bigquery_bigframes_query] return df -def query_legacy_sql(): - # [START bigquery_bigframes_query_legacy] - import bigframes.pandas as bpd +# [END bigquery_bigframes_query] - # Set partial ordering mode as the default configuration for BigQuery DataFrames. - bpd.options.bigquery.ordering_mode = "partial" - - sql = """ - SELECT name FROM [bigquery-public-data:usa_names.usa_1910_current] - WHERE state = 'TX' - LIMIT 100 - """ - - # Run a query using legacy SQL syntax. - query_config = {"query": {"useLegacySql": True}} - df = bpd.read_gbq(sql, configuration=query_config) - # [END bigquery_bigframes_query_legacy] - return df - - -def query_bqstorage(): - # [START bigquery_bigframes_query_bqstorage] - import bigframes.pandas as bpd - - # Set partial ordering mode as the default configuration for BigQuery DataFrames. - bpd.options.bigquery.ordering_mode = "partial" +# [START bigquery_bigframes_query_bqstorage] +def query_bqstorage() -> pd.DataFrame: sql = """ SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE state = 'TX' @@ -76,17 +55,14 @@ def query_bqstorage(): # When downloading results to an in-memory pandas DataFrame, bigquery-dataframes # automatically uses the BigQuery Storage API if installed. pandas_df = df.to_pandas() - # [END bigquery_bigframes_query_bqstorage] return pandas_df -def query_parameters(): - # [START bigquery_bigframes_query_parameters] - import bigframes.pandas as bpd +# [END bigquery_bigframes_query_bqstorage] - # Set partial ordering mode as the default configuration for BigQuery DataFrames. - bpd.options.bigquery.ordering_mode = "partial" +# [START bigquery_bigframes_query_parameters] +def query_parameters() -> bpd.DataFrame: sql = """ SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE state = @state @@ -107,19 +83,16 @@ def query_parameters(): } df = bpd.read_gbq(sql, configuration=query_config) - # [END bigquery_bigframes_query_parameters] return df -def upload_from_dataframe(table_id: str = "your-project.your_dataset.your_table_name"): - # [START bigquery_bigframes_upload_from_dataframe] - import pandas as pd +# [END bigquery_bigframes_query_parameters] - import bigframes.pandas as bpd - - # Set partial ordering mode as the default configuration for BigQuery DataFrames. - bpd.options.bigquery.ordering_mode = "partial" +# [START bigquery_bigframes_upload_from_dataframe] +def upload_from_dataframe( + table_id: str = "your-project.your_dataset.your_table_name", +) -> bpd.DataFrame: # Create a local pandas DataFrame. df = pd.DataFrame( { @@ -133,7 +106,8 @@ def upload_from_dataframe(table_id: str = "your-project.your_dataset.your_table_ bq_df = bpd.read_pandas(df) # Write the DataFrame to a BigQuery table. - table_id = "your-project.your_dataset.your_table_name" bq_df.to_gbq(table_id, if_exists="replace") - # [END bigquery_bigframes_upload_from_dataframe] return bq_df + + +# [END bigquery_bigframes_upload_from_dataframe] diff --git a/bigquery/bigframes/bigframes_queries_test.py b/bigquery/bigframes/bigframes_queries_test.py index e155ca5c312..b5c7685539f 100644 --- a/bigquery/bigframes/bigframes_queries_test.py +++ b/bigquery/bigframes/bigframes_queries_test.py @@ -13,38 +13,24 @@ # limitations under the License. import bigframes_queries -import pytest -@pytest.mark.skip( - reason="Placeholder project ID 'your-project-id' cannot be executed by pytest, but snippet is required for welcome page documentation." -) -def test_query_standard_sql(): - df = bigframes_queries.query_standard_sql() +def test_query_standard_sql(project_id: str) -> None: + df = bigframes_queries.query_standard_sql(project_id=project_id) assert df is not None -@pytest.mark.skip( - reason="Legacy SQL syntax is not supported for execution by BigQuery DataFrames, but snippet is required for welcome page documentation." -) -def test_query_legacy_sql(): - df = bigframes_queries.query_legacy_sql() - assert df is not None - - -def test_query_bqstorage(): +def test_query_bqstorage() -> None: pandas_df = bigframes_queries.query_bqstorage() assert pandas_df is not None -def test_query_parameters(): +def test_query_parameters() -> None: df = bigframes_queries.query_parameters() assert df is not None -@pytest.mark.skip( - reason="Requires a writable destination table so pytest skips execution, but snippet is required for welcome page documentation." -) -def test_upload_from_dataframe(): - bq_df = bigframes_queries.upload_from_dataframe() +def test_upload_from_dataframe(project_id: str, dataset_id: str) -> None: + table_id = f"{project_id}.{dataset_id}.upload_from_dataframe" + bq_df = bigframes_queries.upload_from_dataframe(table_id=table_id) assert bq_df is not None diff --git a/bigquery/bigframes/conftest.py b/bigquery/bigframes/conftest.py index a3274f08ca3..66558b11552 100644 --- a/bigquery/bigframes/conftest.py +++ b/bigquery/bigframes/conftest.py @@ -13,7 +13,9 @@ # limitations under the License. import os +import uuid +from google.cloud import bigquery import pytest @@ -25,3 +27,14 @@ def project_id() -> str: @pytest.fixture(scope="session") def location() -> str: return "US" + + +@pytest.fixture(scope="session") +def dataset_id(project_id: str) -> str: + client = bigquery.Client(project=project_id) + dataset_id = f"bigframes_samples_{uuid.uuid4().hex[:8]}" + dataset = bigquery.Dataset(f"{project_id}.{dataset_id}") + dataset.location = "US" + client.create_dataset(dataset) + yield dataset_id + client.delete_dataset(dataset, delete_contents=True, not_found_ok=True) From d995ef3f597a3f7e9dc9d6e3a97b815f7a74bb26 Mon Sep 17 00:00:00 2001 From: Shuowei Li Date: Wed, 22 Jul 2026 20:31:39 +0000 Subject: [PATCH 09/11] style: remove extra blank lines --- bigquery/bigframes/bigframes_queries.py | 8 -------- 1 file changed, 8 deletions(-) diff --git a/bigquery/bigframes/bigframes_queries.py b/bigquery/bigframes/bigframes_queries.py index a974fddc9db..497032ca126 100644 --- a/bigquery/bigframes/bigframes_queries.py +++ b/bigquery/bigframes/bigframes_queries.py @@ -36,8 +36,6 @@ def query_standard_sql(project_id: str = "your-project-id") -> bpd.DataFrame: bpd.options.bigquery.project = project_id df = bpd.read_gbq(sql) return df - - # [END bigquery_bigframes_query] @@ -56,8 +54,6 @@ def query_bqstorage() -> pd.DataFrame: # automatically uses the BigQuery Storage API if installed. pandas_df = df.to_pandas() return pandas_df - - # [END bigquery_bigframes_query_bqstorage] @@ -84,8 +80,6 @@ def query_parameters() -> bpd.DataFrame: df = bpd.read_gbq(sql, configuration=query_config) return df - - # [END bigquery_bigframes_query_parameters] @@ -108,6 +102,4 @@ def upload_from_dataframe( # Write the DataFrame to a BigQuery table. bq_df.to_gbq(table_id, if_exists="replace") return bq_df - - # [END bigquery_bigframes_upload_from_dataframe] From 739cdea29a8fc72ef813cceaaaf40c3504c6555e Mon Sep 17 00:00:00 2001 From: Shuowei Li Date: Wed, 22 Jul 2026 22:43:14 +0000 Subject: [PATCH 10/11] docs: split bigframes query samples into separate files --- bigquery/bigframes/bigframes_queries.py | 105 ------------------ bigquery/bigframes/query_bqstorage.py | 40 +++++++ bigquery/bigframes/query_bqstorage_test.py | 20 ++++ bigquery/bigframes/query_parameters.py | 45 ++++++++ bigquery/bigframes/query_parameters_test.py | 20 ++++ bigquery/bigframes/query_standard_sql.py | 39 +++++++ bigquery/bigframes/query_standard_sql_test.py | 20 ++++ bigquery/bigframes/upload_from_dataframe.py | 43 +++++++ ..._test.py => upload_from_dataframe_test.py} | 19 +--- 9 files changed, 229 insertions(+), 122 deletions(-) delete mode 100644 bigquery/bigframes/bigframes_queries.py create mode 100644 bigquery/bigframes/query_bqstorage.py create mode 100644 bigquery/bigframes/query_bqstorage_test.py create mode 100644 bigquery/bigframes/query_parameters.py create mode 100644 bigquery/bigframes/query_parameters_test.py create mode 100644 bigquery/bigframes/query_standard_sql.py create mode 100644 bigquery/bigframes/query_standard_sql_test.py create mode 100644 bigquery/bigframes/upload_from_dataframe.py rename bigquery/bigframes/{bigframes_queries_test.py => upload_from_dataframe_test.py} (60%) diff --git a/bigquery/bigframes/bigframes_queries.py b/bigquery/bigframes/bigframes_queries.py deleted file mode 100644 index 497032ca126..00000000000 --- a/bigquery/bigframes/bigframes_queries.py +++ /dev/null @@ -1,105 +0,0 @@ -# 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 -# -# http://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 bigframes.pandas as bpd -import pandas as pd - -# Set partial ordering mode as the default configuration for BigQuery DataFrames. -bpd.options.bigquery.ordering_mode = "partial" - - -# [START bigquery_bigframes_query] -def query_standard_sql(project_id: str = "your-project-id") -> bpd.DataFrame: - sql = """ - SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current` - WHERE state = 'TX' - LIMIT 100 - """ - - # Run a query alongside existing SQL. The project will be determined from default credentials. - df = bpd.read_gbq(sql) - - # Run a query after explicitly specifying a project. - bpd.close_session() - bpd.options.bigquery.project = project_id - df = bpd.read_gbq(sql) - return df -# [END bigquery_bigframes_query] - - -# [START bigquery_bigframes_query_bqstorage] -def query_bqstorage() -> pd.DataFrame: - sql = """ - SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current` - WHERE state = 'TX' - LIMIT 100 - """ - - # Read query results into a server-side DataFrame without downloading data. - df = bpd.read_gbq(sql) - - # When downloading results to an in-memory pandas DataFrame, bigquery-dataframes - # automatically uses the BigQuery Storage API if installed. - pandas_df = df.to_pandas() - return pandas_df -# [END bigquery_bigframes_query_bqstorage] - - -# [START bigquery_bigframes_query_parameters] -def query_parameters() -> bpd.DataFrame: - sql = """ - SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current` - WHERE state = @state - LIMIT 100 - """ - - query_config = { - "query": { - "parameterMode": "NAMED", - "queryParameters": [ - { - "name": "state", - "parameterType": {"type": "STRING"}, - "parameterValue": {"value": "TX"}, - } - ], - } - } - - df = bpd.read_gbq(sql, configuration=query_config) - return df -# [END bigquery_bigframes_query_parameters] - - -# [START bigquery_bigframes_upload_from_dataframe] -def upload_from_dataframe( - table_id: str = "your-project.your_dataset.your_table_name", -) -> bpd.DataFrame: - # Create a local pandas DataFrame. - df = pd.DataFrame( - { - "my_string": ["a", "b", "c"], - "my_int64": [1, 2, 3], - "my_float64": [4.0, 5.0, 6.0], - } - ) - - # Convert the local pandas DataFrame to a BigQuery DataFrame. - bq_df = bpd.read_pandas(df) - - # Write the DataFrame to a BigQuery table. - bq_df.to_gbq(table_id, if_exists="replace") - return bq_df -# [END bigquery_bigframes_upload_from_dataframe] diff --git a/bigquery/bigframes/query_bqstorage.py b/bigquery/bigframes/query_bqstorage.py new file mode 100644 index 00000000000..8eb7a022983 --- /dev/null +++ b/bigquery/bigframes/query_bqstorage.py @@ -0,0 +1,40 @@ +# 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 +# +# http://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_bigframes_query_bqstorage] +import bigframes.pandas as bpd + +import pandas as pd + +# Set partial ordering mode as the default configuration for BigQuery +# DataFrames. +bpd.options.bigquery.ordering_mode = "partial" + + +def query_bqstorage() -> pd.DataFrame: + sql = """ + SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current` + WHERE state = 'TX' + LIMIT 100 + """ + + # Read query results into a server-side DataFrame without downloading data. + df = bpd.read_gbq(sql) + + # When downloading results to an in-memory pandas DataFrame, + # bigquery-dataframes automatically uses the BigQuery Storage API if + # installed. + pandas_df = df.to_pandas() + return pandas_df +# [END bigquery_bigframes_query_bqstorage] diff --git a/bigquery/bigframes/query_bqstorage_test.py b/bigquery/bigframes/query_bqstorage_test.py new file mode 100644 index 00000000000..d02d858da30 --- /dev/null +++ b/bigquery/bigframes/query_bqstorage_test.py @@ -0,0 +1,20 @@ +# 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 +# +# http://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 query_bqstorage + + +def test_query_bqstorage() -> None: + pandas_df = query_bqstorage.query_bqstorage() + assert pandas_df is not None diff --git a/bigquery/bigframes/query_parameters.py b/bigquery/bigframes/query_parameters.py new file mode 100644 index 00000000000..584a6b35ad7 --- /dev/null +++ b/bigquery/bigframes/query_parameters.py @@ -0,0 +1,45 @@ +# 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 +# +# http://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_bigframes_query_parameters] +import bigframes.pandas as bpd + +# Set partial ordering mode as the default configuration for BigQuery +# DataFrames. +bpd.options.bigquery.ordering_mode = "partial" + + +def query_parameters() -> bpd.DataFrame: + sql = """ + SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current` + WHERE state = @state + LIMIT 100 + """ + + query_config = { + "query": { + "parameterMode": "NAMED", + "queryParameters": [ + { + "name": "state", + "parameterType": {"type": "STRING"}, + "parameterValue": {"value": "TX"}, + } + ], + } + } + + df = bpd.read_gbq(sql, configuration=query_config) + return df +# [END bigquery_bigframes_query_parameters] diff --git a/bigquery/bigframes/query_parameters_test.py b/bigquery/bigframes/query_parameters_test.py new file mode 100644 index 00000000000..e6be1c21424 --- /dev/null +++ b/bigquery/bigframes/query_parameters_test.py @@ -0,0 +1,20 @@ +# 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 +# +# http://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 query_parameters + + +def test_query_parameters() -> None: + df = query_parameters.query_parameters() + assert df is not None diff --git a/bigquery/bigframes/query_standard_sql.py b/bigquery/bigframes/query_standard_sql.py new file mode 100644 index 00000000000..5636b226b11 --- /dev/null +++ b/bigquery/bigframes/query_standard_sql.py @@ -0,0 +1,39 @@ +# 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 +# +# http://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_bigframes_query] +import bigframes.pandas as bpd + +# Set partial ordering mode as the default configuration for BigQuery +# DataFrames. +bpd.options.bigquery.ordering_mode = "partial" + + +def query_standard_sql(project_id: str = "your-project-id") -> bpd.DataFrame: + sql = """ + SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current` + WHERE state = 'TX' + LIMIT 100 + """ + + # Run a query alongside existing SQL. The project will be determined from + # default credentials. + df = bpd.read_gbq(sql) + + # Run a query after explicitly specifying a project. + bpd.close_session() + bpd.options.bigquery.project = project_id + df = bpd.read_gbq(sql) + return df +# [END bigquery_bigframes_query] diff --git a/bigquery/bigframes/query_standard_sql_test.py b/bigquery/bigframes/query_standard_sql_test.py new file mode 100644 index 00000000000..a4ba779220e --- /dev/null +++ b/bigquery/bigframes/query_standard_sql_test.py @@ -0,0 +1,20 @@ +# 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 +# +# http://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 query_standard_sql + + +def test_query_standard_sql(project_id: str) -> None: + df = query_standard_sql.query_standard_sql(project_id=project_id) + assert df is not None diff --git a/bigquery/bigframes/upload_from_dataframe.py b/bigquery/bigframes/upload_from_dataframe.py new file mode 100644 index 00000000000..6bd3a8bed05 --- /dev/null +++ b/bigquery/bigframes/upload_from_dataframe.py @@ -0,0 +1,43 @@ +# 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 +# +# http://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_bigframes_upload_from_dataframe] +import bigframes.pandas as bpd + +import pandas as pd + +# Set partial ordering mode as the default configuration for BigQuery +# DataFrames. +bpd.options.bigquery.ordering_mode = "partial" + + +def upload_from_dataframe( + table_id: str = "your-project.your_dataset.your_table_name", +) -> bpd.DataFrame: + # Create a local pandas DataFrame. + df = pd.DataFrame( + { + "my_string": ["a", "b", "c"], + "my_int64": [1, 2, 3], + "my_float64": [4.0, 5.0, 6.0], + } + ) + + # Convert the local pandas DataFrame to a BigQuery DataFrame. + bq_df = bpd.read_pandas(df) + + # Write the DataFrame to a BigQuery table. + bq_df.to_gbq(table_id, if_exists="replace") + return bq_df +# [END bigquery_bigframes_upload_from_dataframe] diff --git a/bigquery/bigframes/bigframes_queries_test.py b/bigquery/bigframes/upload_from_dataframe_test.py similarity index 60% rename from bigquery/bigframes/bigframes_queries_test.py rename to bigquery/bigframes/upload_from_dataframe_test.py index b5c7685539f..799e52618a0 100644 --- a/bigquery/bigframes/bigframes_queries_test.py +++ b/bigquery/bigframes/upload_from_dataframe_test.py @@ -12,25 +12,10 @@ # See the License for the specific language governing permissions and # limitations under the License. -import bigframes_queries - - -def test_query_standard_sql(project_id: str) -> None: - df = bigframes_queries.query_standard_sql(project_id=project_id) - assert df is not None - - -def test_query_bqstorage() -> None: - pandas_df = bigframes_queries.query_bqstorage() - assert pandas_df is not None - - -def test_query_parameters() -> None: - df = bigframes_queries.query_parameters() - assert df is not None +import upload_from_dataframe def test_upload_from_dataframe(project_id: str, dataset_id: str) -> None: table_id = f"{project_id}.{dataset_id}.upload_from_dataframe" - bq_df = bigframes_queries.upload_from_dataframe(table_id=table_id) + bq_df = upload_from_dataframe.upload_from_dataframe(table_id=table_id) assert bq_df is not None From 6eb1852a16ad9e420c1392e6b56df1587600af93 Mon Sep 17 00:00:00 2001 From: Shuowei Li Date: Thu, 23 Jul 2026 18:23:07 +0000 Subject: [PATCH 11/11] feat: add __main__ entrypoints to sample scripts --- bigquery/bigframes/query_bqstorage.py | 4 ++++ bigquery/bigframes/query_parameters.py | 4 ++++ bigquery/bigframes/query_standard_sql.py | 7 +++++++ bigquery/bigframes/upload_from_dataframe.py | 9 +++++++++ 4 files changed, 24 insertions(+) diff --git a/bigquery/bigframes/query_bqstorage.py b/bigquery/bigframes/query_bqstorage.py index 8eb7a022983..02dc6b0f323 100644 --- a/bigquery/bigframes/query_bqstorage.py +++ b/bigquery/bigframes/query_bqstorage.py @@ -38,3 +38,7 @@ def query_bqstorage() -> pd.DataFrame: pandas_df = df.to_pandas() return pandas_df # [END bigquery_bigframes_query_bqstorage] + + +if __name__ == "__main__": + print(query_bqstorage()) diff --git a/bigquery/bigframes/query_parameters.py b/bigquery/bigframes/query_parameters.py index 584a6b35ad7..557fb5f72d7 100644 --- a/bigquery/bigframes/query_parameters.py +++ b/bigquery/bigframes/query_parameters.py @@ -43,3 +43,7 @@ def query_parameters() -> bpd.DataFrame: df = bpd.read_gbq(sql, configuration=query_config) return df # [END bigquery_bigframes_query_parameters] + + +if __name__ == "__main__": + print(query_parameters()) diff --git a/bigquery/bigframes/query_standard_sql.py b/bigquery/bigframes/query_standard_sql.py index 5636b226b11..adee2b05845 100644 --- a/bigquery/bigframes/query_standard_sql.py +++ b/bigquery/bigframes/query_standard_sql.py @@ -37,3 +37,10 @@ def query_standard_sql(project_id: str = "your-project-id") -> bpd.DataFrame: df = bpd.read_gbq(sql) return df # [END bigquery_bigframes_query] + + +if __name__ == "__main__": + import os + + project = os.environ.get("GOOGLE_CLOUD_PROJECT", "your-project-id") + print(query_standard_sql(project_id=project)) diff --git a/bigquery/bigframes/upload_from_dataframe.py b/bigquery/bigframes/upload_from_dataframe.py index 6bd3a8bed05..4f878d02add 100644 --- a/bigquery/bigframes/upload_from_dataframe.py +++ b/bigquery/bigframes/upload_from_dataframe.py @@ -41,3 +41,12 @@ def upload_from_dataframe( bq_df.to_gbq(table_id, if_exists="replace") return bq_df # [END bigquery_bigframes_upload_from_dataframe] + + +if __name__ == "__main__": + import os + + table_id = os.environ.get( + "TABLE_ID", "your-project.your_dataset.your_table_name" + ) + print(upload_from_dataframe(table_id=table_id))