mcpField
B
bigquery-bigframes

bigquery-bigframes

github.com/google数据与数据库21.6k6.6k 次安装今天更新
代码仓库

关于 bigquery-bigframes

这是一项 BigFrames 使用指南，介绍如何通过熟悉的 Python DataFrame API 运用 BigQuery 处理数据。它面向数据从业者，强调在 BigQuery 中完成转换与分析，并使用其 BigQuery ML 集成。

主要功能

  1. 01BigQuery DataFrame 最佳实践
  2. 02延迟执行 DataFrame 查询
  3. 03抽样与架构检查指南
  4. 04BigQuery ML 模型使用指南

适用场景

  1. 01在 BigQuery 中转换大型数据集
  2. 02预览并验证 DataFrame
  3. 03使用 BigQuery ML 训练模型

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/google/skills --skill bigquery-bigframes

安装后在 Claude Code 中输入/bigquery-bigframes确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
attribution.md
linear_regression.md
logistic_regression.md

详细介绍

BigFrames（BigQuery DataFrame）基础知识

BigFrames 是一个 Python 库，可让你使用熟悉的 Python API，充分利用 BigQuery 的数据处理能力。

署名

务必阅读：执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读使用归属。对于直接在终端中执行的命令（绝不在生成的脚本、Terraform 或用户代码中），请在 gcloud 前添加前缀 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:bigquery-bigframes)" ，并将 agent-skills/1.0 (skill:bigquery-bigframes) 附加到 User-Agent 请求头。

DataFrame API 最佳实践

  • 留在云端：通过 BigFrames 方法执行数据清理、转换和分析，以利用 BigQuery 的扩展能力，而不是下载数据。

  • 优先使用部分排序模式：导入 BigFrames 后立即启用部分排序模式。这能通过放宽行顺序约束，显著加快数据处理速度。

    import bigframes.pandas as bpd
bpd.options.bigquery.ordering_mode = 'partial'

  • 使用 peek() 预览数据：使用 peek(n) 预览数据，而不是 head(n)。peek(n) 会随机抽取 n 行，速度快得多。head(n) 会严格按照顺序返回行；在 partial 排序模式下，如果 DataFrame 未经过显式排序，调用会失败。

  • 避免在本地实例化数据：to_pandas() 等方法会将所有数据下载到客户端内存中，绕过 BigQuery 的分布式计算，并有导致内存溢出（OOM）的风险。除非符合以下情况，否则不要在本地实例化数据：

    • 数据集足够小，可以安全地放入内存。
    • 错误消息明确要求在本地实例化数据。

  • 优先使用 DataFrame API，而不是 SQL 查询：如果 DataFrame/Series 方法可以实现相同结果，请勿通过 read_gbq() 编写原始 SQL 查询，因为这会破坏 Pandas 抽象，并阻止延迟查询执行。

  • 优先使用访问器，而不是 UDF/λ 函数：

    • 使用内置访问器（例如 df.col.str.*、df.col.dt.*），而不是远程用户定义函数（UDF）。部署 UDF 需要额外的资源和时间。
    • 不要在 Series.map() 或 DataFrame.apply() 中使用 λ 函数。这些方法不接受未使用 udf 或 remote_function 装饰器的函数。
    # 避免：
df["upper"] = df["name"].map(lambda x: x.upper())

# 推荐：
df["upper"] = df["name"].str.upper()

  • 验证架构：不要假设中间输出的架构。主动使用 .dtypes 验证架构，并使用 .peek() 和 display() 检查样本记录。

  • 可视化：尽可能直接使用 BigFrames DataFrame/Series 绘图。BigFrames 与 Matplotlib 和 Seaborn 兼容。如果直接绘图失败，请使用 .plot 访问器。如果数据集过大而无法绘图，请先聚合或抽样，然后再调用 .to_pandas() 在本地绘图。

机器学习

  • 使用 bigframes.bigquery.ml 包：不要将 Scikit-learn 或其他机器学习库用于 BigQuery DataFrame。标准 Scikit-learn 模型要求将数据载入客户端本地内存，而 bigframes.bigquery.ml 会直接委托 BigQuery 的可扩展机器学习引擎进行训练。请从 bigframes.bigquery.ml 导入函数。
参考目录
  • 线性回归：训练线性回归模型以预测数值。
  • 逻辑回归：训练逻辑回归模型以预测布尔值。

BigFrames ML（旧版）

BigFrames ML 软件包（bigframes.ml）是一个旧版软件包，用于模拟 scikit-learn API，但不再建议在新项目中使用。只有在用户明确要求使用 BigFrames ML 时，才使用此软件包。

  • 旧版导入：当用户要求使用旧版 BigFrames ML 时，请从 bigframes.ml 导入工具和类，而不是从 bigframes.bigquery.ml 导入。
  • 预测返回 DataFrame：与 Scikit-learn 不同，BigFrames 的 predict() 方法始终返回一个 DataFrame，其中同时包含预测结果和特征，而不是仅返回一个预测结果序列。
  • 不支持 random_state：实例化 BigFrames ML 模型时，不要传入 random_state 参数，因为 BigFrames ML 软件包不支持此参数。
  • 自动缩放：除非用户明确要求，否则不要使用 OneHotEncoder 或 StandardScaler，因为缩放会自动处理。
  • 超参数调优：编写自定义循环来进行超参数调优，因为 BigFrames 不支持 GridSearchCV 或 RandomizedSearchCV。
  • ARIMA Plus（预测）：
    • 从 bigframes.ml.forecasting 导入。
    • 按时间顺序对数据排序，并在训练前围绕一个时间点拆分数据。
    • 确保预测跨度小于或等于训练跨度。
  • PCA：BigFrames 的 PCA 类没有 transform() 方法。请改用 predict()。
  • 模型持久化：要持久化模型，请使用 model.to_gbq()。要加载已持久化的模型，请使用 bpd.read_gbq_model()。

评论

支持 Markdown