diff --git a/bigquery/bigframes/bigframes_queries.py b/bigquery/bigframes/bigframes_queries.py new file mode 100644 index 00000000000..08eb2c5e716 --- /dev/null +++ b/bigquery/bigframes/bigframes_queries.py @@ -0,0 +1,139 @@ +# 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. + project_id = "your-project-id" + 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 + + # 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/bigframes_queries_test.py b/bigquery/bigframes/bigframes_queries_test.py new file mode 100644 index 00000000000..e155ca5c312 --- /dev/null +++ b/bigquery/bigframes/bigframes_queries_test.py @@ -0,0 +1,50 @@ +# 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_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() + 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(): + pandas_df = bigframes_queries.query_bqstorage() + assert pandas_df is not None + + +def test_query_parameters(): + 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() + assert bq_df is not None