feat: expose DataFrame.bigquery in both pandas and bigframes DataFrames (#2533)

Thank you for opening a Pull Request! Before submitting your PR, there
are a few things you can do to make sure it goes smoothly:
- [ ] Make sure to open an issue as a
[bug/issue](https://github.com/googleapis/python-bigquery-dataframes/issues/new/choose)
before writing your code! That way we can discuss the change, evaluate
designs, and agree on the general idea
- [ ] Ensure the tests and linter pass
- [ ] Code coverage does not decrease (if any source code was changed)
- [ ] Appropriate docs were updated (if necessary)
Fixes #<issue_number_goes_here> 🦕

Author: tswast

bigframes/bigquery/_operations/ai.py

@@ -893,6 +893,25 @@ def forecast(
  and might have limited support. For more information, see the launch stage descriptions
  (https://cloud.google.com/products#product-launch-stages).
 
+ **Examples:**
+
+ Forecast using a pandas DataFrame:
+
+ >>> import pandas as pd
+ >>> import bigframes.pandas as bpd
+ >>> df = pd.DataFrame({"value": [1, 2, 3], "time": pd.to_datetime(["2020-01-01", "2020-01-02", "2020-01-03"])})
+ >>> bpd.options.display.progress_bar = None # doctest: +SKIP
+ >>> forecasted_pandas_df = df.bigquery.ai.forecast(data_col="value", timestamp_col="time", horizon=2) # doctest: +SKIP
+ >>> type(forecasted_pandas_df) # doctest: +SKIP
+ <class 'pandas.core.frame.DataFrame'>
+
+ Forecast using a BigFrames DataFrame:
+
+ >>> bf_df = bpd.DataFrame({"value": [1, 2, 3], "time": pd.to_datetime(["2020-01-01", "2020-01-02", "2020-01-03"])})
+ >>> forecasted_bf_df = bf_df.bigquery.ai.forecast(data_col="value", timestamp_col="time", horizon=2) # doctest: +SKIP
+ >>> type(forecasted_bf_df) # doctest: +SKIP
+ <class 'bigframes.dataframe.DataFrame'>
+
  Args:
  df (DataFrame):
  The dataframe that contains the data that you want to forecast. It could be either a BigFrames Dataframe or

bigframes/bigquery/_operations/sql.py

@@ -71,6 +71,25 @@ def sql_scalar(
  2 4.000000000
  dtype: decimal128(38, 9)[pyarrow]
 
+ You can also use the `.bigquery` DataFrame accessor to apply a SQL scalar function.
+
+ Compute SQL scalar using a pandas DataFrame:
+
+ >>> import pandas as pd
+ >>> df = pd.DataFrame({"x": [1, 2, 3]})
+ >>> bpd.options.display.progress_bar = None # doctest: +SKIP
+ >>> pandas_s = df.bigquery.sql_scalar("POW({0}, 2)") # doctest: +SKIP
+ >>> type(pandas_s) # doctest: +SKIP
+ <class 'pandas.core.series.Series'>
+
+ Compute SQL scalar using a BigFrames DataFrame:
+
+ >>> bf_df = bpd.DataFrame({"x": [1, 2, 3]})
+ >>> bf_s = bf_df.bigquery.sql_scalar("POW({0}, 2)") # doctest: +SKIP
+ >>> type(bf_s) # doctest: +SKIP
+ <class 'bigframes.series.Series'>
+
+
  Args:
  sql_template (str):
  A SQL format string with Python-style {0} placeholders for each of

bigframes/dataframe.py

@@ -37,6 +37,7 @@
 overload,
 Sequence,
 Tuple,
+TYPE_CHECKING,
 TypeVar,
 Union,
 )
@@ -47,6 +48,8 @@
 importbigframes_vendored.pandas.pandas._typingasvendored_pandas_typing
 importgoogle.api_core.exceptions
 importgoogle.cloud.bigqueryasbigquery
+importgoogle.cloud.bigquery.job
+importgoogle.cloud.bigquery.table
 importnumpy
 importpandas
 frompandas.apiimportextensionsaspd_ext
@@ -91,9 +94,10 @@
 importbigframes.session._io.bigquery
 importbigframes.session.execution_specasex_spec
 
-iftyping.TYPE_CHECKING:
+ifTYPE_CHECKING:
 from_typeshedimportSupportsRichComparison
 
+importbigframes.extensions.bigframes.dataframe_accessorasbigquery_accessor
 importbigframes.session
 
 SingleItemValue=Union[
@@ -144,7 +148,7 @@ def __init__(
  ):
 globalbigframes
 
-self._query_job: Optional[bigquery.QueryJob] =None
+self._query_job: Optional[google.cloud.bigquery.job.QueryJob] =None
 
 ifcopyisnotNoneandnotcopy:
 raiseValueError(
@@ -376,6 +380,25 @@ def bqclient(self) -> bigframes.Session:
 def_session(self) ->bigframes.Session:
 returnself._get_block().expr.session
 
+@property
+defbigquery(
+self,
+ ) ->bigquery_accessor.BigframesBigQueryDataFrameAccessor:
+"""
+ Accessor for BigQuery functionality.
+
+ Returns:
+ bigframes.extensions.core.dataframe_accessor.BigQueryDataFrameAccessor:
+ Accessor that exposes BigQuery functionality on a DataFrame,
+ with method names closer to SQL.
+ """
+# Import the accessor here to avoid circular imports.
+importbigframes.extensions.bigframes.dataframe_accessor
+
+returnbigframes.extensions.bigframes.dataframe_accessor.BigframesBigQueryDataFrameAccessor(
+self
+ )
+
 @property
 def_has_index(self) ->bool:
 returnlen(self._block.index_columns) >0
@@ -438,7 +461,9 @@ def _should_sql_have_index(self) -> bool:
 self.index.nameisnotNoneorlen(self.index.names) >1
  )
 
-def_to_placeholder_table(self, dry_run: bool=False) ->bigquery.TableReference:
+def_to_placeholder_table(
+self, dry_run: bool=False
+ ) ->google.cloud.bigquery.table.TableReference:
 """Compiles this DataFrame's expression tree to SQL and saves it to a
  (temporary) view or table (in the case of a dry run).
  """
@@ -488,11 +513,11 @@ def sql(self) -> str:
  ) frome
 
 @property
-defquery_job(self) ->Optional[bigquery.QueryJob]:
+defquery_job(self) ->Optional[google.cloud.bigquery.job.QueryJob]:
 """BigQuery job metadata for the most recent query.
 
  Returns:
- None or google.cloud.bigquery.QueryJob:
+ None or google.cloud.bigquery.job.QueryJob:
  The most recent `QueryJob
  <https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.job.QueryJob>`_.
  """
@@ -606,7 +631,9 @@ def select_dtypes(self, include=None, exclude=None) -> DataFrame:
  )
 returnDataFrame(self._block.select_columns(selected_columns))
 
-def_set_internal_query_job(self, query_job: Optional[bigquery.QueryJob]):
+def_set_internal_query_job(
+self, query_job: Optional[google.cloud.bigquery.job.QueryJob]
+ ):
 self._query_job=query_job
 
 def__getitem__(
@@ -1782,7 +1809,7 @@ def _to_pandas_batches(
 allow_large_results=allow_large_results,
  )
 
-def_compute_dry_run(self) ->bigquery.QueryJob:
+def_compute_dry_run(self) ->google.cloud.bigquery.job.QueryJob:
 _, query_job=self._block._compute_dry_run()
 returnquery_job
 

bigframes/extensions/bigframes/__init__.py

@@ -0,0 +1,20 @@
+# 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.
+
+frombigframes.extensions.bigframes.dataframe_accessorimport (
+BigframesAIAccessor,
+BigframesBigQueryDataFrameAccessor,
+)
+
+__all__= ["BigframesAIAccessor", "BigframesBigQueryDataFrameAccessor"]

bigframes/extensions/bigframes/dataframe_accessor.py

@@ -0,0 +1,71 @@
+# 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.
+
+from __future__ importannotations
+
+fromtypingimportcast, TypeVar
+
+frombigframes.core.loggingimportlog_adapter
+importbigframes.dataframe
+importbigframes.extensions.core.dataframe_accessorascore_accessor
+importbigframes.series
+
+T=TypeVar("T", bound="bigframes.dataframe.DataFrame")
+S=TypeVar("S", bound="bigframes.series.Series")
+
+
+@log_adapter.class_logger
+classBigframesAIAccessor(core_accessor.AIAccessor[T, S]):
+"""
+ BigFrames DataFrame accessor for BigQuery AI functions.
+ """
+
+def__init__(self, bf_obj: T):
+super().__init__(bf_obj)
+
+def_bf_from_dataframe(
+self, session: bigframes.session.Session|None
+ ) ->bigframes.dataframe.DataFrame:
+returnself._obj
+
+def_to_dataframe(self, bf_df: bigframes.dataframe.DataFrame) ->T:
+returncast(T, bf_df)
+
+def_to_series(self, bf_series: bigframes.series.Series) ->S:
+returncast(S, bf_series)
+
+
+@log_adapter.class_logger
+classBigframesBigQueryDataFrameAccessor(core_accessor.BigQueryDataFrameAccessor[T, S]):
+"""
+ BigFrames DataFrame accessor for BigQuery DataFrames functionality.
+ """
+
+def__init__(self, bf_obj: T):
+super().__init__(bf_obj)
+
+@property
+defai(self) ->BigframesAIAccessor:
+returnBigframesAIAccessor(self._obj)
+
+def_bf_from_dataframe(
+self, session: bigframes.session.Session|None
+ ) ->bigframes.dataframe.DataFrame:
+returnself._obj
+
+def_to_dataframe(self, bf_df: bigframes.dataframe.DataFrame) ->T:
+returncast(T, bf_df)
+
+def_to_series(self, bf_series: bigframes.series.Series) ->S:
+returncast(S, bf_series)

bigframes/extensions/core/__init__.py

@@ -0,0 +1,20 @@
+# 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.
+
+frombigframes.extensions.core.dataframe_accessorimport (
+AIAccessor,
+BigQueryDataFrameAccessor,
+)
+
+__all__= ["AIAccessor", "BigQueryDataFrameAccessor"]