docs: add bigframes_queries sample snippets by shuoweil · Pull Request #14429 · GoogleCloudPlatform/python-docs-samples

shuoweil · 2026-07-16T22:13:32Z

Adds sample code snippets with region tags (# [START ...] / # [END ...]) for BigQuery DataFrames documentation welcome page (python-libraries.md).

Note here, we need to place all imports inside testcase functions for the following reasons:

Doc Ingestion Boundaries: Documentation generation tools only extract code between # [START] and # [END] tags. Any top-of-file imports get stripped out.
Copy-Paste Runnable: Placing imports inside the function ensures the rendered code snippet on cloud.google.com includes the import statements, allowing users to copy and run it without hitting a NameError.

Fixes #<522845525> 🦕

snippet-bot · 2026-07-16T22:13:37Z

Here is the summary of changes.

You are about to add 5 region tags.

bigquery/bigframes/bigframes_queries.py:17, tag bigquery_bigframes_query
bigquery/bigframes/bigframes_queries.py:41, tag bigquery_bigframes_query_legacy
bigquery/bigframes/bigframes_queries.py:61, tag bigquery_bigframes_query_bqstorage
bigquery/bigframes/bigframes_queries.py:84, tag bigquery_bigframes_query_parameters
bigquery/bigframes/bigframes_queries.py:115, tag bigquery_bigframes_upload_from_dataframe

This comment is generated by snippet-bot.
If you find problems with this result, please file an issue at:
https://github.com/googleapis/repo-automation-bots/issues.
To update this comment, add snippet-bot:force-run label or use the checkbox below:

Refresh this comment

gemini-code-assist

Code Review

This pull request introduces code examples and tests for BigQuery DataFrames, covering standard SQL queries, legacy SQL queries, storage API usage, parameterized queries, and uploading from a pandas DataFrame. The feedback recommends parameterizing placeholder values like project_id and table_id to make the examples flexible and enable their tests to run instead of being skipped. Additionally, it is recommended to remove the legacy SQL example and its test entirely, as legacy SQL is not supported by BigQuery DataFrames.

gemini-code-assist · 2026-07-16T22:15:08Z

+# limitations under the License.
+
+
+def query_standard_sql():


To make this snippet testable and avoid global side effects, parameterize the project_id in the function signature with a default value of "your-project-id". This allows tests to pass a valid project ID while keeping the placeholder for documentation.

Suggested change

def query_standard_sql():

def query_standard_sql(project_id: str = "your-project-id"):

This test case is for adding samples in welcome page. No past in variables should be allowed.

Gemini is correct in this case.

gemini-code-assist · 2026-07-16T22:15:08Z

+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


Since BigQuery DataFrames does not support Legacy SQL (as noted in the skipped test), providing a code snippet for it is misleading and will result in errors for users. Please remove the query_legacy_sql function entirely to avoid documenting unsupported behavior.

I update the error message to avoid confusion

gemini-code-assist · 2026-07-16T22:15:08Z

+    return df
+
+
+def upload_from_dataframe():


Parameterize the table_id in the function signature with a default value of "your-project.your_dataset.your_table_name". This makes the snippet more flexible and easier to test.

Suggested change

def upload_from_dataframe():

def upload_from_dataframe(table_id: str = "your-project.your_dataset.your_table_name"):

This test case is for adding samples in welcome page. No past in variables should be allowed.

Gemini is correct.

gemini-code-assist · 2026-07-16T22:15:08Z

+    bq_df = bpd.read_pandas(df)
+
+    # Write the DataFrame to a BigQuery table.
+    table_id = "your-project.your_dataset.your_table_name"


Remove the hardcoded table_id assignment since it is now passed as a parameter.

Suggested change

table_id = "your-project.your_dataset.your_table_name"

# Use the provided table_id parameter

I prefer the original line better

gemini-code-assist · 2026-07-16T22:15:08Z

+@pytest.mark.skip(reason="Placeholder project ID 'your-project-id' (b/522845525)")
+def test_query_standard_sql():
+    df = bigframes_queries.query_standard_sql()
+    assert df is not None


Now that query_standard_sql is parameterized, we can remove the @pytest.mark.skip decorator and run the test using the project_id fixture.

Suggested change

@pytest.mark.skip(reason="Placeholder project ID 'your-project-id' (b/522845525)")

def test_query_standard_sql():

df = bigframes_queries.query_standard_sql()

assert df is not None

def test_query_standard_sql(project_id):

df = bigframes_queries.query_standard_sql(project_id=project_id)

assert df is not None

This test case is for adding samples in welcome page. No past in variables should be allowed.

gemini-code-assist · 2026-07-16T22:15:08Z

+@pytest.mark.skip(reason="Legacy SQL syntax not supported by BigQuery DataFrames (b/522845525)")
+def test_query_legacy_sql():
+    df = bigframes_queries.query_legacy_sql()
+    assert df is not None


Since Legacy SQL is not supported by BigQuery DataFrames and the corresponding snippet should be removed, this test should also be removed.

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

shuoweil · 2026-07-16T22:20:54Z

cc @sycai for review

tswast · 2026-07-16T22:56:24Z

+# limitations under the License.
+
+
+def query_standard_sql():


Gemini is correct in this case.

tswast · 2026-07-16T22:57:22Z

+
+
+def query_standard_sql():
+    # [START bigquery_bigframes_query]


The Cloud samples rubric has the region tags outside of the function and move the imports to outside of the function. Refer to https://github.com/GoogleCloudPlatform/python-docs-samples/blob/main/AUTHORING_GUIDE.md

tswast · 2026-07-16T22:58:16Z

+    return df
+
+
+def upload_from_dataframe():


Gemini is correct.

tswast · 2026-07-16T22:58:53Z

+@pytest.mark.skip(
+    reason="Requires a writable destination table so pytest skips execution, but snippet is required for welcome page documentation."
+)


Don't skip this. Instead, parametrize the sample and pass in a writable destination.

tswast · 2026-07-16T22:59:16Z

+@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


Agreed with Gemini. It's better not to have a sample than to have one that doesn't work.

tswast · 2026-07-16T22:59:23Z

+@pytest.mark.skip(
+    reason="Placeholder project ID 'your-project-id' cannot be executed by pytest, but snippet is required for welcome page documentation."
+)


Don't skip this.

shuoweil added 2 commits July 16, 2026 21:58

docs: add python_libraries sample snippets

cf7d2cd

docs: rename python_libraries to bigframes_queries

154eed9

shuoweil requested review from a team and tswast as code owners July 16, 2026 22:13

product-auto-label Bot added api: bigquery Issues related to the BigQuery API. samples Issues that are directly related to samples. labels Jul 16, 2026

shuoweil changed the title ~~docs(bigquery/bigframes): add bigframes_queries sample snippets~~ docs: add bigframes_queries sample snippets Jul 16, 2026

gemini-code-assist Bot reviewed Jul 16, 2026

View reviewed changes

shuoweil mentioned this pull request Jul 16, 2026

docs: add code sample snippets for welcome page documentation googleapis/google-cloud-python#17744

Closed

Update bigquery/bigframes/bigframes_queries.py

b4f1c86

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

docs: update pytest skip reasons for welcome page snippets

d2d3d25

tswast requested changes Jul 16, 2026

View reviewed changes

docs: fix flake8 lint errors in bigframes_queries

7348654

	def query_standard_sql():
	def query_standard_sql(project_id: str = "your-project-id"):

	def upload_from_dataframe():
	def upload_from_dataframe(table_id: str = "your-project.your_dataset.your_table_name"):

	table_id = "your-project.your_dataset.your_table_name"
	# Use the provided table_id parameter

Uh oh!

Conversation

shuoweil commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

snippet-bot Bot commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gemini-code-assist Bot Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

shuoweil commented Jul 16, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

shuoweil commented Jul 16, 2026 •

edited

Loading

snippet-bot Bot commented Jul 16, 2026 •

edited

Loading