Skip to content
This repository was archived by the owner on Apr 1, 2026. It is now read-only.

Commit 06e684b

Browse files
tswasttswast
committed
docs: add notebooks to user guide page
1 parent 077cb2e commit 06e684b

File tree

14 files changed

+432
-1
lines changed

14 files changed

+432
-1
lines changed

‎bigframes/__init__.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,9 @@
3232
)
3333
import bigframes.enums as enums # noqa: E402
3434
import bigframes.exceptions as exceptions # noqa: E402
35+
36+
# Register pandas extensions
37+
import bigframes.extensions.pandas.dataframe_accessor # noqa: F401, E402
3538
from bigframes.session import connect, Session # noqa: E402
3639
from bigframes.version import __version__ # noqa: E402
3740

‎bigframes/extensions/__init__.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Copyright 2026 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.

‎bigframes/extensions/pandas/__init__.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Copyright 2026 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.

‎bigframes/extensions/pandas/dataframe_accessor.py‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Copyright 2026 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
from typing import cast
16+
17+
import pandas
18+
import pandas.api.extensions
19+
20+
import bigframes.core.global_session as bf_session
21+
import bigframes.pandas as bpd
22+
23+
24+
@pandas.api.extensions.register_dataframe_accessor("bigquery")
25+
class BigQueryDataFrameAccessor:
26+
"""
27+
Pandas DataFrame accessor for BigQuery DataFrames functionality.
28+
29+
This accessor is registered under the ``bigquery`` namespace on pandas DataFrame objects.
30+
"""
31+
32+
def __init__(self, pandas_obj: pandas.DataFrame):
33+
self._obj = pandas_obj
34+
35+
def sql_scalar(self, sql_template: str, session=None):
36+
"""
37+
Compute a new pandas Series by applying a SQL scalar function to the DataFrame.
38+
39+
The DataFrame is converted to BigFrames by calling ``read_pandas``, then the SQL
40+
template is applied using ``bigframes.bigquery.sql_scalar``, and the result is
41+
converted back to a pandas Series using ``to_pandas``.
42+
43+
Args:
44+
sql_template (str):
45+
A SQL format string with Python-style {0}, {1}, etc. placeholders for each of
46+
the columns in the DataFrame (in the order they appear in ``df.columns``).
47+
session (bigframes.session.Session, optional):
48+
The BigFrames session to use. If not provided, the default global session is used.
49+
50+
Returns:
51+
pandas.Series:
52+
The result of the SQL scalar function as a pandas Series.
53+
"""
54+
if session is None:
55+
session = bf_session.get_global_session()
56+
57+
bf_df = cast(bpd.DataFrame, session.read_pandas(self._obj))
58+
59+
# Import bigframes.bigquery here to avoid circular imports
60+
import bigframes.bigquery
61+
62+
columns = [cast(bpd.Series, bf_df[col]) for col in bf_df.columns]
63+
result = bigframes.bigquery.sql_scalar(sql_template, columns)
64+
65+
return result.to_pandas()

‎docs/conf.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,15 @@
5959
"sphinx.ext.todo",
6060
"sphinx.ext.viewcode",
6161
"sphinx_sitemap",
62-
"myst_parser",
62+
"myst_nb",
63+
]
64+
65+
# myst-nb configuration
66+
nb_execution_mode = "off"
67+
68+
# Suppress warnings
69+
suppress_warnings = [
70+
"myst.header",
6371
]
6472

6573
# autodoc/autosummary flags

‎docs/notebooks‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../notebooks

‎docs/reference/index.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,16 @@ packages.
1919
bigframes.pandas.api.typing
2020
bigframes.streaming
2121

22+
Pandas Extensions
23+
~~~~~~~~~~~~~~~~~
24+
25+
BigQuery DataFrames provides extensions to pandas DataFrame objects.
26+
27+
.. autosummary::
28+
:toctree: api
29+
30+
bigframes.extensions.pandas.dataframe_accessor.BigQueryDataFrameAccessor
31+
2232
ML APIs
2333
~~~~~~~
2434

‎docs/user_guide/index.rst‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,117 @@ User Guide
99

1010
Getting Started <https://docs.cloud.google.com/bigquery/docs/dataframes-quickstart>
1111
Cloud Docs User Guides <https://docs.cloud.google.com/bigquery/docs/bigquery-dataframes-introduction>
12+
13+
.. toctree::
14+
:caption: Getting Started
15+
:maxdepth: 1
16+
17+
Quickstart Template <../notebooks/getting_started/bq_dataframes_template.ipynb>
18+
Getting Started <../notebooks/getting_started/getting_started_bq_dataframes.ipynb>
19+
Magics <../notebooks/getting_started/magics.ipynb>
20+
ML Fundamentals <../notebooks/getting_started/ml_fundamentals_bq_dataframes.ipynb>
21+
Pandas Extensions <../notebooks/getting_started/pandas_extensions.ipynb>
22+
23+
.. toctree::
24+
:caption: DataFrames
25+
:maxdepth: 1
26+
27+
Anywidget Mode <../notebooks/dataframes/anywidget_mode.ipynb>
28+
Dataframe <../notebooks/dataframes/dataframe.ipynb>
29+
Index Col Null <../notebooks/dataframes/index_col_null.ipynb>
30+
Integrations <../notebooks/dataframes/integrations.ipynb>
31+
Pypi <../notebooks/dataframes/pypi.ipynb>
32+
33+
.. toctree::
34+
:caption: Data Types
35+
:maxdepth: 1
36+
37+
Array <../notebooks/data_types/array.ipynb>
38+
Json <../notebooks/data_types/json.ipynb>
39+
Struct <../notebooks/data_types/struct.ipynb>
40+
Timedelta <../notebooks/data_types/timedelta.ipynb>
41+
42+
.. toctree::
43+
:caption: Generative AI
44+
:maxdepth: 1
45+
46+
AI Functions <../notebooks/generative_ai/ai_functions.ipynb>
47+
AI Forecast <../notebooks/generative_ai/bq_dataframes_ai_forecast.ipynb>
48+
LLM Code Generation <../notebooks/generative_ai/bq_dataframes_llm_code_generation.ipynb>
49+
LLM KMeans <../notebooks/generative_ai/bq_dataframes_llm_kmeans.ipynb>
50+
LLM Output Schema <../notebooks/generative_ai/bq_dataframes_llm_output_schema.ipynb>
51+
LLM Vector Search <../notebooks/generative_ai/bq_dataframes_llm_vector_search.ipynb>
52+
Drug Name Generation <../notebooks/generative_ai/bq_dataframes_ml_drug_name_generation.ipynb>
53+
Large Language Models <../notebooks/generative_ai/large_language_models.ipynb>
54+
55+
.. toctree::
56+
:caption: Machine Learning
57+
:maxdepth: 1
58+
59+
ML Cross Validation <../notebooks/ml/bq_dataframes_ml_cross_validation.ipynb>
60+
Linear Regression <../notebooks/ml/bq_dataframes_ml_linear_regression.ipynb>
61+
Linear Regression BBQ <../notebooks/ml/bq_dataframes_ml_linear_regression_bbq.ipynb>
62+
Linear Regression Big <../notebooks/ml/bq_dataframes_ml_linear_regression_big.ipynb>
63+
Easy Linear Regression <../notebooks/ml/easy_linear_regression.ipynb>
64+
Sklearn Linear Regression <../notebooks/ml/sklearn_linear_regression.ipynb>
65+
Timeseries Analysis <../notebooks/ml/timeseries_analysis.ipynb>
66+
67+
.. toctree::
68+
:caption: Visualization
69+
:maxdepth: 1
70+
71+
COVID Line Graphs <../notebooks/visualization/bq_dataframes_covid_line_graphs.ipynb>
72+
Tutorial <../notebooks/visualization/tutorial.ipynb>
73+
74+
.. toctree::
75+
:caption: Geospatial Data
76+
:maxdepth: 1
77+
78+
Geoseries <../notebooks/geo/geoseries.ipynb>
79+
80+
.. toctree::
81+
:caption: Regionalized BigQuery
82+
:maxdepth: 1
83+
84+
Regionalized <../notebooks/location/regionalized.ipynb>
85+
86+
.. toctree::
87+
:caption: Multimodal
88+
:maxdepth: 1
89+
90+
Multimodal Dataframe <../notebooks/multimodal/multimodal_dataframe.ipynb>
91+
92+
.. toctree::
93+
:caption: Remote Functions
94+
:maxdepth: 1
95+
96+
Remote Function <../notebooks/remote_functions/remote_function.ipynb>
97+
Remote Function Usecases <../notebooks/remote_functions/remote_function_usecases.ipynb>
98+
Remote Function Vertex Claude Model <../notebooks/remote_functions/remote_function_vertex_claude_model.ipynb>
99+
100+
.. toctree::
101+
:caption: Streaming
102+
:maxdepth: 1
103+
104+
Streaming Dataframe <../notebooks/streaming/streaming_dataframe.ipynb>
105+
106+
.. toctree::
107+
:caption: Experimental
108+
:maxdepth: 1
109+
110+
AI Operators <../notebooks/experimental/ai_operators.ipynb>
111+
Semantic Operators <../notebooks/experimental/semantic_operators.ipynb>
112+
113+
.. toctree::
114+
:caption: Apps
115+
:maxdepth: 1
116+
117+
Synthetic Data Generation <../notebooks/apps/synthetic_data_generation.ipynb>
118+
119+
.. toctree::
120+
:caption: Kaggle
121+
:maxdepth: 1
122+
123+
AI Forecast <../notebooks/kaggle/bq_dataframes_ai_forecast.ipynb>
124+
Describe Product Images <../notebooks/kaggle/describe-product-images-with-bigframes-multimodal.ipynb>
125+
Vector Search Over National Jukebox <../notebooks/kaggle/vector-search-with-bigframes-over-national-jukebox.ipynb>

‎notebooks/getting_started/pandas_extensions.ipynb‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"# Pandas Extension for BigQuery DataFrames\n",
8+
"\n",
9+
"BigQuery DataFrames provides a pandas extension to execute BigQuery SQL scalar functions directly on pandas DataFrames."
10+
]
11+
},
12+
{
13+
"cell_type": "code",
14+
"execution_count": null,
15+
"metadata": {},
16+
"outputs": [],
17+
"source": [
18+
"import pandas as pd\n",
19+
"import bigframes.pandas as bpd\n",
20+
"import bigframes"
21+
]
22+
},
23+
{
24+
"cell_type": "markdown",
25+
"metadata": {},
26+
"source": [
27+
"## Using `sql_scalar`\n",
28+
"\n",
29+
"The `bigquery.sql_scalar` method allows you to apply a SQL scalar function to a pandas DataFrame by converting it to BigFrames, executing the SQL in BigQuery, and returning the result as a pandas Series."
30+
]
31+
},
32+
{
33+
"cell_type": "code",
34+
"execution_count": null,
35+
"metadata": {},
36+
"outputs": [],
37+
"source": [
38+
"df = pd.DataFrame({\"a\": [1.5, 2.5, 3.5]})\n",
39+
"result = df.bigquery.sql_scalar(\"ROUND({0}, 0)\")\n",
40+
"result"
41+
]
42+
},
43+
{
44+
"cell_type": "markdown",
45+
"metadata": {},
46+
"source": [
47+
"You can also use multiple columns."
48+
]
49+
},
50+
{
51+
"cell_type": "code",
52+
"execution_count": null,
53+
"metadata": {},
54+
"outputs": [],
55+
"source": [
56+
"df = pd.DataFrame({\"a\": [1, 2, 3], \"b\": [10, 20, 30]})\n",
57+
"result = df.bigquery.sql_scalar(\"{0} + {1}\")\n",
58+
"result"
59+
]
60+
}
61+
],
62+
"metadata": {
63+
"kernelspec": {
64+
"display_name": "Python 3",
65+
"language": "python",
66+
"name": "python3"
67+
},
68+
"language_info": {
69+
"codemirror_mode": {
70+
"name": "ipython",
71+
"version": 3
72+
},
73+
"file_extension": ".py",
74+
"mimetype": "text/x-python",
75+
"name": "python",
76+
"nbconvert_exporter": "python",
77+
"pygments_lexer": "ipython3",
78+
"version": "3.12.9"
79+
}
80+
},
81+
"nbformat": 4,
82+
"nbformat_minor": 4
83+
}

‎noxfile.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -508,6 +508,7 @@ def docs(session):
508508
"sphinx==8.2.3",
509509
"sphinx-sitemap==2.9.0",
510510
"myst-parser==4.0.1",
511+
"myst-nb==1.4.0",
511512
"pydata-sphinx-theme==0.16.1",
512513
)
513514

0 commit comments

Comments
 (0)