bigquery-bigframes

BigFrames（BigQuery DataFrame）の基本

BigFrames は、使い慣れた Python API を使って BigQuery のデータ処理を活用できる Python ライブラリです。

帰属情報

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、必ず使用状況の帰属情報をお読みください。ターミナルで直接実行するコマンド（生成されたスクリプト、Terraform、ユーザーコード内での実行は不可）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:bigquery-bigframes)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:bigquery-bigframes) を追加してください。

DataFrame API のベストプラクティス

• クラウド内で処理する：データをダウンロードするのではなく、BigFrames のメソッドを使ってデータのクリーニング、変換、分析を行い、BigQuery のスケーラビリティを活用してください。

• 部分順序モードを優先する：BigFrames をインポートした直後に部分順序モードを有効にしてください。行の順序に関する制約を緩和することで、データ処理が大幅に高速化します。

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

• データのプレビューには peek() を使用する：データをプレビューするには head(n) ではなく peek(n) を使用してください。peek(n) は n 行をランダムにサンプリングするため、大幅に高速です。head(n) は厳密な順序で行を返すため、DataFrame が明示的にソートされていない場合、部分順序モードでは失敗します。

• データのローカルでの実体化を避ける：to_pandas() のようなメソッドは、すべてのデータをクライアントのメモリにダウンロードします。これは BigQuery の分散計算を迂回し、メモリ不足（OOM）エラーのリスクを高めます。次の場合を除き、データをローカルで実体化しないでください。

  • データセットが十分に小さく、安全にメモリへ収まる場合。
  • エラーメッセージでローカルでの実体化が明示的に求められている場合。

• SQL クエリより DataFrame API を優先する：DataFrame／Series のメソッドで同じ結果を得られる場合は、read_gbq() を使って生の SQL クエリを書かないでください。Pandas の抽象化が損なわれ、遅延クエリ実行ができなくなります。

• UDF／ラムダよりアクセサーを使用する：

  • リモートのユーザー定義関数（UDF）ではなく、組み込みアクセサー（例：df.col.str.*、df.col.dt.*）を使用してください。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 パッケージを使用する：BigQuery DataFrame で Scikit-learn などの ML ライブラリを使用しないでください。標準的な Scikit-learn モデルでは、データをクライアントのローカルメモリに取り込む必要があります。一方、bigframes.bigquery.ml はトレーニングを BigQuery のスケーラブルな ML エンジンに直接委任します。bigframes.bigquery.ml から関数をインポートしてください。

リファレンスディレクトリ

• 線形回帰：数値を予測する線形回帰モデルをトレーニングします。
• ロジスティック回帰：ブール値を予測するロジスティック回帰モデルをトレーニングします。

BigFrames ML（レガシー）

BigFrames ML パッケージ（bigframes.ml）は、scikit-learn API を模倣するレガシーパッケージですが、新しいプロジェクトには推奨されなくなっています。このパッケージは、ユーザーが BigFrames ML を明示的に指定した場合にのみ使用してください。

• レガシーインポート：レガシーの BigFrames ML が指定された場合は、bigframes.bigquery.ml ではなく bigframes.ml からツールとクラスをインポートしてください。
• 予測時の DataFrame の返却：Scikit-learn とは異なり、BigFrames の predict() メソッドは、予測値だけの単一の Series ではなく、予測値と特徴量の両方を含む DataFrame を常に返します。
• random_state は使用不可：このパラメーターは BigFrames ML パッケージでサポートされていないため、BigFrames ML モデルのインスタンス化時に random_state 引数を渡さないでください。
• 自動スケーリング：スケーリングは自動的に処理されるため、明示的に要求された場合を除き、OneHotEncoder や StandardScaler は使用しないでください。
• ハイパーパラメーター調整：BigFrames には GridSearchCV や RandomizedSearchCV がないため、ハイパーパラメーター調整にはカスタムループを記述してください。
• ARIMA Plus（予測）：
  • bigframes.ml.forecasting からインポートしてください。
  • 学習前にデータを時系列順に並べ、ある時点を基準に分割してください。
  • 予測期間が学習期間以下であることを確認してください。
• PCA：BigFrames の PCA クラスには transform() メソッドがありません。代わりに predict() を使用してください。
• モデルの永続化：モデルを永続化するには、model.to_gbq() を使用してください。永続化されたモデルを読み込むには、bpd.read_gbq_model() を使用してください。