feat: add `df.bigquery.ai.forecast` method to pandas dataframe accessor by tswast · Pull Request #2518 · googleapis/python-bigquery-dataframes · GitHub
Skip to content
This repository was archived by the owner on Apr 1, 2026. It is now read-only.

feat: add df.bigquery.ai.forecast method to pandas dataframe accessor#2518

Merged
tswast merged 3 commits intomainfrom
add-pandas-ai-forecast-accessor-14604090974587392182
Mar 17, 2026
Merged

feat: add df.bigquery.ai.forecast method to pandas dataframe accessor#2518
tswast merged 3 commits intomainfrom
add-pandas-ai-forecast-accessor-14604090974587392182

Conversation

@tswast
Copy link
Copy Markdown
Contributor

@tswast tswast commented Mar 16, 2026

Adds the .bigquery.ai.forecast() method to pandas DataFrame objects, which proxies to bigframes.bigquery.ai.forecast(). Added unit tests and mocked session responses.

PR created automatically by Jules for task 14604090974587392182 started by @tswast

@google-labs-jules @tswast
feat: Add ai.forecast method to pandas DataFrame accessor
c3fdcbb 
This adds a new `ai` property to `BigQueryDataFrameAccessor` which returns an `AIAccessor`. The `AIAccessor` provides a `forecast` method that calls `bigframes.bigquery.ai.forecast`, converting the Pandas DataFrame to a BigFrames DataFrame and the result back to a Pandas DataFrame.

Co-authored-by: tswast <247555+tswast@users.noreply.github.com>
@google-labs-jules
Copy link
Copy Markdown
Contributor

google-labs-jules Bot commented Mar 16, 2026

@tswast tswast requested review from a team as code owners March 16, 2026 19:27
@tswast tswast requested a review from chelsea-lin March 16, 2026 19:27
@product-auto-label product-auto-label Bot added size: m Pull request size is medium. api: bigquery Issues related to the googleapis/python-bigquery-dataframes API. labels Mar 16, 2026
@tswast tswast removed the request for review from chelsea-lin March 16, 2026 19:44
tswast
tswast commented Mar 16, 2026
View reviewed changes
Comment thread bigframes/extensions/pandas/dataframe_accessor.py Outdated
The time points column provides the time points used to generate the forecast.
The time points column must use one of the following data types: TIMESTAMP, DATE and DATETIME
model (str, default "TimesFM 2.0"):
A str value that specifies the name of the model. TimesFM 2.0 is the only supported value, and is the default value.
Copy link
Copy Markdown
Contributor Author

@tswast tswast Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jules According to https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/bigqueryml-syntax-ai-forecast, "TimesFM 2.5" is also supported. We should link to https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/bigqueryml-syntax-ai-forecast in the docstring, above.

Copy link
Copy Markdown
Contributor

@google-labs-jules google-labs-jules Bot Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a link to the standard-sql documentation for ai.forecast and updated the model param documentation to include TimesFM 2.5.

Comment thread bigframes/extensions/pandas/dataframe_accessor.py Outdated
Comment on lines +47 to +49
The DataFrame is converted to BigFrames by calling ``read_pandas``, then the forecast
is generated using ``bigframes.bigquery.ai.forecast``, and the result is
converted back to a pandas DataFrame using ``to_pandas``.
Copy link
Copy Markdown
Contributor Author

@tswast tswast Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jules This is an implementation detail that doesn't belong in the docstring.

Copy link
Copy Markdown
Contributor

@google-labs-jules google-labs-jules Bot Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed the implementation details regarding read_pandas and to_pandas from the docstring.

Comment thread bigframes/extensions/pandas/dataframe_accessor.py
model: str = "TimesFM 2.0",
id_cols: Optional[Iterable[str]] = None,
horizon: int = 10,
confidence_level: float = 0.95,
Copy link
Copy Markdown
Contributor Author

@tswast tswast Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jules Missing the output_historical_time_series boolean parameter.

Copy link
Copy Markdown
Contributor

@google-labs-jules google-labs-jules Bot Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added the missing output_historical_time_series boolean parameter and documented it.

Comment thread tests/system/small/extensions/test_dataframe_accessor.py Outdated
@@ -0,0 +1,25 @@
import pandas as pd
Copy link
Copy Markdown
Contributor Author

@tswast tswast Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jules missing the license header.

Copy link
Copy Markdown
Contributor

@google-labs-jules google-labs-jules Bot Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added the missing Apache 2.0 license header to tests/system/small/extensions/test_dataframe_accessor.py.

@google-labs-jules @tswast
feat: Update ai.forecast accessor per PR review
f949fe1 
* Updated documentation to refer to BigQuery AI.FORECAST syntax.
* Removed internal implementation details (`read_pandas` and `to_pandas`) from docstring.
* Added missing `output_historical_time_series` parameter.
* Added missing copyright headers to `tests/system/small/extensions/test_dataframe_accessor.py`.

Co-authored-by: tswast <247555+tswast@users.noreply.github.com>
@tswast tswast changed the title Add ai.forecast method to pandas dataframe accessor feat: add df.bigquery.ai.forecast method to pandas dataframe accessor Mar 16, 2026
@tswast tswast requested a review from chelsea-lin March 16, 2026 20:50
sycai
sycai reviewed Mar 17, 2026
View reviewed changes
Comment thread bigframes/extensions/pandas/dataframe_accessor.py
Copy link
Copy Markdown
Contributor

@sycai sycai Mar 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm curious if this triggers our logger.

My gut feeling says yes, because our logger only seems to track the call stack of annotated classes / functions. However, I still feel like to double check with you on this.

Copy link
Copy Markdown
Contributor Author

@tswast tswast Mar 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should trigger the logger, but I think we should probably add labels that are specific to the dataframe accessor. I'll follow-up with that.

@tswast tswast merged commit 1126cec into main Mar 17, 2026
21 of 25 checks passed
@tswast tswast deleted the add-pandas-ai-forecast-accessor-14604090974587392182 branch March 17, 2026 19:05
@tswast tswast mentioned this pull request Mar 18, 2026
Merged
tswast added a commit that referenced this pull request Mar 21, 2026
@tswast
chore: include pandas accessors in api logging (#2524)
b5a7652 
Follow-up to #2518 

🦕
@sycai sycai mentioned this pull request Mar 31, 2026
Merged
sycai added a commit that referenced this pull request Apr 1, 2026
@sycai
chore: librarian release pull request: 20260331T225508Z (#2547)
be33279 
PR created by the Librarian CLI to initialize a release. Merging this PR
will auto trigger a release.

Librarian Version: v0.7.0
Language Image:
us-central1-docker.pkg.dev/cloud-sdk-librarian-prod/images-prod/python-librarian-generator@sha256:160860d189ff1c2f7515638478823712fa5b243e27ccc33a2728669fa1e2ed0c
<details><summary>bigframes: 2.39.0</summary>

##
[2.39.0](v2.38.0...v2.39.0)
(2026-03-31)

### Features

* add `df.bigquery.ai.forecast` method to pandas dataframe accessor
(#2518)
([1126cec](1126cec9))

* support full round-trip persistence for multimodal reference cols
(#2511)
([494a0a1](494a0a11))

* expose DataFrame.bigquery in both pandas and bigframes DataFrames
(#2533)
([69fe317](69fe3176))

### Bug Fixes

* to_gbq may swap data columns when replace table (#2532)
([17ecc65](17ecc65e))

* handle aggregate operations on empty selections (#2510)
([34fb5da](34fb5daa))

* Localize BigQuery log suppression for gbq.py (#2541)
([af49ca2](af49ca29))

* Respect remote function config changes even if logic unchanged (#2512)
([b952428](b9524284))

* support melting empty DataFrames without crashing (#2509)
([e8c4603](e8c46032))

### Performance Improvements

* Make executor data uploads async internally (#2529)
([96597f0](96597f0b))

### Documentation

* gemini retouch of the index page for seo (#2514)
([2e5311e](2e5311e2))

* Rename Blob column references to ObjectRef column (#2535)
([44e0ffd](44e0ffd9))

</details>
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Reviewers

@chelsea-lin chelsea-lin Awaiting requested review from chelsea-lin

2 more reviewers

@google-labs-jules google-labs-jules[bot] google-labs-jules[bot] left review comments

@sycai sycai sycai approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

@mpovoa mpovoa

Labels

api: bigquery Issues related to the googleapis/python-bigquery-dataframes API. size: m Pull request size is medium.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@tswast @sycai @drylks-work @mpovoa