From cf7d2cd728367e0a1bd22f383a4decdac894365d Mon Sep 17 00:00:00 2001 From: Shuowei Li Date: Thu, 16 Jul 2026 21:58:37 +0000 Subject: [PATCH 1/5] 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 2/5] 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 3/5] 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 4/5] 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 5/5] 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(