docs: add notebooks to user guide page

docs/conf.py

@@ -59,7 +59,15 @@
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
     "sphinx_sitemap",
-    "myst_parser",
+    "myst_nb",
+]
+
+# myst-nb configuration
+nb_execution_mode = "off"
+
+# Suppress warnings
+suppress_warnings = [
+    "myst.header",
 ]
 
 # autodoc/autosummary flags

docs/notebooks

@@ -0,0 +1 @@
+../notebooks

docs/user_guide/index.rst

@@ -9,3 +9,117 @@ User Guide
 
    Getting Started <https://docs.cloud.google.com/bigquery/docs/dataframes-quickstart>
    Cloud Docs User Guides <https://docs.cloud.google.com/bigquery/docs/bigquery-dataframes-introduction>
+
+.. toctree::
+   :caption: Getting Started
+   :maxdepth: 1
+
+   Quickstart Template <../notebooks/getting_started/bq_dataframes_template.ipynb>
+   Getting Started <../notebooks/getting_started/getting_started_bq_dataframes.ipynb>
+   Magics <../notebooks/getting_started/magics.ipynb>
+   ML Fundamentals <../notebooks/getting_started/ml_fundamentals_bq_dataframes.ipynb>
+   Pandas Extensions <../notebooks/getting_started/pandas_extensions.ipynb>
+
+.. toctree::
+   :caption: DataFrames
+   :maxdepth: 1
+
+   Anywidget Mode <../notebooks/dataframes/anywidget_mode.ipynb>
+   Dataframe <../notebooks/dataframes/dataframe.ipynb>
+   Index Col Null <../notebooks/dataframes/index_col_null.ipynb>
+   Integrations <../notebooks/dataframes/integrations.ipynb>
+   Pypi <../notebooks/dataframes/pypi.ipynb>
+
+.. toctree::
+   :caption: Data Types
+   :maxdepth: 1
+
+   Array <../notebooks/data_types/array.ipynb>
+   Json <../notebooks/data_types/json.ipynb>
+   Struct <../notebooks/data_types/struct.ipynb>
+   Timedelta <../notebooks/data_types/timedelta.ipynb>
+
+.. toctree::
+   :caption: Generative AI
+   :maxdepth: 1
+
+   AI Functions <../notebooks/generative_ai/ai_functions.ipynb>
+   AI Forecast <../notebooks/generative_ai/bq_dataframes_ai_forecast.ipynb>
+   LLM Code Generation <../notebooks/generative_ai/bq_dataframes_llm_code_generation.ipynb>
+   LLM KMeans <../notebooks/generative_ai/bq_dataframes_llm_kmeans.ipynb>
+   LLM Output Schema <../notebooks/generative_ai/bq_dataframes_llm_output_schema.ipynb>
+   LLM Vector Search <../notebooks/generative_ai/bq_dataframes_llm_vector_search.ipynb>
+   Drug Name Generation <../notebooks/generative_ai/bq_dataframes_ml_drug_name_generation.ipynb>
+   Large Language Models <../notebooks/generative_ai/large_language_models.ipynb>
+
+.. toctree::
+   :caption: Machine Learning
+   :maxdepth: 1
+
+   ML Cross Validation <../notebooks/ml/bq_dataframes_ml_cross_validation.ipynb>
+   Linear Regression <../notebooks/ml/bq_dataframes_ml_linear_regression.ipynb>
+   Linear Regression BBQ <../notebooks/ml/bq_dataframes_ml_linear_regression_bbq.ipynb>
+   Linear Regression Big <../notebooks/ml/bq_dataframes_ml_linear_regression_big.ipynb>
+   Easy Linear Regression <../notebooks/ml/easy_linear_regression.ipynb>
+   Sklearn Linear Regression <../notebooks/ml/sklearn_linear_regression.ipynb>
+   Timeseries Analysis <../notebooks/ml/timeseries_analysis.ipynb>
+
+.. toctree::
+   :caption: Visualization
+   :maxdepth: 1
+
+   COVID Line Graphs <../notebooks/visualization/bq_dataframes_covid_line_graphs.ipynb>
+   Tutorial <../notebooks/visualization/tutorial.ipynb>
+
+.. toctree::
+   :caption: Geospatial Data
+   :maxdepth: 1
+
+   Geoseries <../notebooks/geo/geoseries.ipynb>
+
+.. toctree::
+   :caption: Regionalized BigQuery
+   :maxdepth: 1
+
+   Regionalized <../notebooks/location/regionalized.ipynb>
+
+.. toctree::
+   :caption: Multimodal
+   :maxdepth: 1
+
+   Multimodal Dataframe <../notebooks/multimodal/multimodal_dataframe.ipynb>
+
+.. toctree::
+   :caption: Remote Functions
+   :maxdepth: 1
+
+   Remote Function <../notebooks/remote_functions/remote_function.ipynb>
+   Remote Function Usecases <../notebooks/remote_functions/remote_function_usecases.ipynb>
+   Remote Function Vertex Claude Model <../notebooks/remote_functions/remote_function_vertex_claude_model.ipynb>
+
+.. toctree::
+   :caption: Streaming
+   :maxdepth: 1
+
+   Streaming Dataframe <../notebooks/streaming/streaming_dataframe.ipynb>
+
+.. toctree::
+   :caption: Experimental
+   :maxdepth: 1
+
+   AI Operators <../notebooks/experimental/ai_operators.ipynb>
+   Semantic Operators <../notebooks/experimental/semantic_operators.ipynb>
+
+.. toctree::
+   :caption: Apps
+   :maxdepth: 1
+
+   Synthetic Data Generation <../notebooks/apps/synthetic_data_generation.ipynb>
+
+.. toctree::
+   :caption: Kaggle
+   :maxdepth: 1
+
+   AI Forecast <../notebooks/kaggle/bq_dataframes_ai_forecast.ipynb>
+   Describe Product Images <../notebooks/kaggle/describe-product-images-with-bigframes-multimodal.ipynb>
+   Vector Search Over National Jukebox <../notebooks/kaggle/vector-search-with-bigframes-over-national-jukebox.ipynb>

notebooks/getting_started/pandas_extensions.ipynb

@@ -0,0 +1,83 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Pandas Extension for BigQuery DataFrames\n",
+    "\n",
+    "BigQuery DataFrames provides a pandas extension to execute BigQuery SQL scalar functions directly on pandas DataFrames."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pandas as pd\n",
+    "import bigframes.pandas as bpd\n",
+    "import bigframes"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Using `sql_scalar`\n",
+    "\n",
+    "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."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df = pd.DataFrame({\"a\": [1.5, 2.5, 3.5]})\n",
+    "result = df.bigquery.sql_scalar(\"ROUND({0}, 0)\")\n",
+    "result"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can also use multiple columns."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df = pd.DataFrame({\"a\": [1, 2, 3], \"b\": [10, 20, 30]})\n",
+    "result = df.bigquery.sql_scalar(\"{0} + {1}\")\n",
+    "result"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

noxfile.py

@@ -508,6 +508,7 @@ def docs(session):
         "sphinx==8.2.3",
         "sphinx-sitemap==2.9.0",
         "myst-parser==4.0.1",
+        "myst-nb==1.4.0",
         "pydata-sphinx-theme==0.16.1",
     )
 

tests/unit/extensions/__init__.py

@@ -0,0 +1,13 @@
+# 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.

tests/unit/extensions/pandas/__init__.py

@@ -0,0 +1,13 @@
+# 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.

tests/unit/extensions/pandas/test_dataframe_accessor.py

@@ -0,0 +1,67 @@
+# 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 unittest.mock as mock
+
+import pandas as pd
+
+# Importing bigframes registers the accessor.
+import bigframes  # noqa: F401
+
+
+def test_dataframe_accessor_sql_scalar():
+    df = pd.DataFrame({"a": [1, 2], "b": [3, 4]})
+
+    with mock.patch("bigframes.pandas.io.api.read_pandas") as mock_read_pandas:
+        with mock.patch("bigframes.bigquery.sql_scalar") as mock_sql_scalar:
+            mock_bf_df = mock.MagicMock()
+            mock_bf_df.columns = ["a", "b"]
+            mock_bf_df.__getitem__.side_effect = lambda x: f"series_{x}"
+            mock_read_pandas.return_value = mock_bf_df
+
+            mock_result_series = mock.MagicMock()
+            mock_sql_scalar.return_value = mock_result_series
+            mock_result_series.to_pandas.return_value = pd.Series([4, 6])
+
+            # This should trigger the accessor
+            result = df.bigquery.sql_scalar("ROUND({0} + {1})")
+
+            mock_read_pandas.assert_called_once()
+            # check it was called with df
+            assert mock_read_pandas.call_args[0][0] is df
+
+            mock_sql_scalar.assert_called_once_with(
+                "ROUND({0} + {1})", ["series_a", "series_b"]
+            )
+
+            pd.testing.assert_series_equal(result, pd.Series([4, 6]))
+
+
+def test_dataframe_accessor_sql_scalar_with_session():
+    df = pd.DataFrame({"a": [1]})
+    mock_session = mock.MagicMock()
+
+    with mock.patch("bigframes.pandas.io.api.read_pandas") as mock_read_pandas:
+        with mock.patch("bigframes.bigquery.sql_scalar") as mock_sql_scalar:
+            mock_bf_df = mock.MagicMock()
+            mock_bf_df.columns = ["a"]
+            mock_bf_df.__getitem__.side_effect = lambda x: f"series_{x}"
+            mock_read_pandas.return_value = mock_bf_df
+
+            mock_result_series = mock.MagicMock()
+            mock_sql_scalar.return_value = mock_result_series
+
+            df.bigquery.sql_scalar("template", session=mock_session)
+
+            mock_read_pandas.assert_called_once_with(df, session=mock_session)

tests/unit/extensions/pandas/test_registration.py

@@ -0,0 +1,27 @@
+# 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 pandas as pd
+
+# Importing bigframes registers the accessor.
+import bigframes  # noqa: F401
+
+
+def test_bigframes_import_registers_accessor():
+    df = pd.DataFrame({"a": [1]})
+    # If bigframes was imported, df.bigquery should exist
+    assert hasattr(df, "bigquery")
+    from bigframes.extensions.pandas.dataframe_accessor import BigQueryDataFrameAccessor
+
+    assert isinstance(df.bigquery, BigQueryDataFrameAccessor)