Bigquery Bigframes
Generates Python code using BigQuery DataFrames (BigFrames). Use by default for any Python data task involving BigQuery, including data processing, analysis, and machine learning. Don't use for SQL-first workflows or the google-cloud-bigquery client library — use bigquery-basics.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Bigquery Bigframes when an AI agent needs a reusable SKILL.md workflow for this job: Generates Python code using BigQuery DataFrames (BigFrames). Use by default for any Python data task involving BigQuery, including data processing, analysis, and machine learning. Don't use for SQL-first workflows or the google-cloud-bigquery client library — use bigquery-basics.
When not to use it
Skip Bigquery Bigframes when the task is outside the analysis category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/bigquery-bigframes # Save SKILL.md to ~/.claude/skills/bigquery-bigframes/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/bigquery-bigframes/SKILL.md. For a shared project, commit the folder at .claude/skills/bigquery-bigframes/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Bigquery Bigframes skill for this task: Use Bigquery Bigframes when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# BigFrames (BigQuery DataFrame) basics BigFrames is a Python library that lets you take advantage of BigQuery data processing by using familiar Python APIs.
## Attribution
**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST read [Usage Attribution](references/attribution.md). For commands executed directly in the terminal (never in generated scripts, Terraform, or user code), prefix `gcloud` with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:bigquery-bigframes)"` and append `agent-skills/1.0 (skill:bigquery-bigframes)` to `User-Agent` headers.
## Dataframe API best practices
* **Stay in the Cloud**: Perform data cleaning, transformation, and analysis via BigFrames methods to leverage BigQuery's scale rather than downloading data. * **Prefer partial ordering mode**: Enable partial ordering mode right after importing BigFrames. This speeds up data processing significantly by relaxing row-sequence constraints.
```python import bigframes.pandas as bpd bpd.options.bigquery.ordering_mode = 'partial' ``` * **Use `peek()` for data preview**: Use `peek(n)` to preview data instead of `head(n)`. `peek(n)` randomly samples `n` rows and is significantly faster. `head(n)` returns rows in strict order and fails in `partial` ordering mode unless the DataFrame has been explicitly sorted. * **Avoid materializing data locally**: Methods like `to_pandas()` download all data to client memory, bypassing BigQuery’s distributed computation and risking Out of Memory (OOM) errors. Do not materialize data locally unless: * The dataset is small enough to fit safely in memory. * An error message explicitly requires local materialization. * **Prefer Dataframe API over SQL queries**: Do not write raw SQL queries via `read_gbq()` if a DataFrame/Series method achieves the same result, as it breaks the Pandas abstraction and prevents lazy query execution. * **Accessors over UDFs/Lambdas**: * Use built-in accessors (e.g., `df.col.str.*`, `df.col.dt.*`) instead of remote User Defined Functions (UDFs). UDFs require extra resources and time to deploy. * Do not use lambdas with `Series.map()` or `DataFrame.apply()`. These methods do not accept functions without `udf` or `remote_function` decorators. ```python # Avoid: df["upper"] = df["name"].map(lambda x: x.upper())
# Prefer: df["upper"] = df["name"].str.upper() ``` * **Schema Verification**: Do not assume the schema of intermediate outputs. Proactively verify schemas using `.dtypes` and inspect sample records using `display()` with `.peek()`. * **Visualization**: Plot directly from the BigFrames DataFrame/Series when possible. BigFrames is compatible with Matplotlib and Seaborn. If direct plotting fails, use the `.plot` accessor. If the dataset is too large to plot, aggregate or sample the data before calling `.to_pandas()` to plot locally.
## Machine Learning * **Use `bigframes.bigquery.ml` package**: Do not use Scikit-learn or other ML libraries with BigQuery DataFrames. Standard Scikit-learn models require bringing data into local client memory, whereas `bigframes.bigquery.ml` delegates training directly to BigQuery's scalable ML engine. Import functions from `bigframes.bigquery.ml`.
### Reference Directory * [Linear Regression](references/linear_regression.md): Train a linear regression model to predict numerical values. * [Logistic Regression](references/logistic_regression.md): Train a logistic regression model to predict boolean values.
## BigFrames ML (Legacy)
The BigFrames ML package (`bigframes.ml`) is a legacy package that mimics the scikit-learn API but is no longer recommended for new projects. Only use this package if the user explicitly requests BigFrames ML.
* **Legacy Imports**: When legacy BigFrames ML is requested, import tools and classes from `bigframes.ml` instead of `bigframes.bigquery.ml`. * **DataFrame Return on Prediction**: Unlike Scikit-learn, BigFrames' `predict()` method always returns a **DataFrame** containing both predictions and features, rather than a single series of predictions. * **No `random_state`**: Do not pass a `random_state` argument when instantiating BigFrames ML models, as this parameter is not supported in the BigFrames ML package. * **Automatic Scaling**: Do not use `OneHotEncoder` or `StandardScaler` unless explicitly requested, as scaling is handled automatically. * **Hyperparameter Tuning**: Write custom loops for hyperparameter tuning, as BigFrames lacks `GridSearchCV` or `RandomizedSearchCV`. * **ARIMA Plus** (Forecasting): * Import from `bigframes.ml.forecasting`. * Sort data chronologically and split around a timepoint before training. * Ensure the prediction horizon is less than or equal to the training horizon. * **PCA**: BigFrames' PCA class lacks a `transform()` method. Use `predict()` instead. * **Model Persistence**: To persist a model, use `model.to_gbq()`. To load a persisted model, use `bpd.read_gbq_model()`.
Intended uses
- Use Bigquery Bigframes when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.