BigQuery と %%bqsql マジックで SQL と Python のギャップを埋める

※この投稿は米国時間 2026 年 7 月 17 日に、Google Cloud blog に投稿されたものの抄訳です。

データ サイエンティストとデータ エンジニアは SQL と Python の使い分けに頭を悩ませることがよくあります。特に BigQuery のような強力なエンジンと組み合わせて大規模データを処理する場合に、SQL はより直感的に使えると感じる人がいる一方、ライブラリやランタイムの豊富なエコシステムを活用できる Python の方が使いやすいと感じる人もいます。従来、1 つのノートブックでこれらの言語を併用するには、まずデータを SQL の結果からインメモリに移動し、Python のメモリから一時テーブルに書き込んだうえで、SQL からアクセスする必要がありました。

この手間を解消するため、Google Cloud チームは Colab Enterprise に SQL セルを導入しました。このたび、そのシームレスな体験を、より広範なオープンソース エコシステムへと拡大しました。今後は %%bqsql IPython セルマジックを使用して、SQL と Python のコードセル間でデータ処理ワークロードを簡単に連携させることができます。

Jupyter、pandas、BigFrames、BigQuery サンドボックスなどのオープンソース パッケージのおかげで、このガイドに記載されたすべての手順は無料で*クレジット カードなしで実行していただけます。

* 制限事項については、BigQuery サンドボックスのドキュメントをご確認ください。

環境を設定する

事前準備：

1. BigQuery サンドボックスを有効にします。Google Cloud プロジェクト ID をメモしておきます。

2. ローカルの Python 開発環境を設定するか、Python 環境がすでにインストールされている Colab でこのノートブックを開きます。

ローカルの Python 環境を設定する方法については、Google Cloud ドキュメントの手順をご確認ください。ローカルの Python 環境を設定する場合は、次の手順に進みます。設定しない場合は、次のセクションにスキップしてください。

3. 前のステップで作成した venv を有効にして、Python の依存関係を分離します。

Linux または macOS では、次のコマンドを使用します（お好みの Python バージョンに更新してください）。

4. Jupyter、bigframes、python-calamine パッケージをインストールします。

5. JupyterLab を起動します。

6. ウェブブラウザを開き、出力に表示された URL にアクセスします。表示される URL は、http://localhost:8888/lab?token=somesupersecretvaluehere のような形式になります。

7. Jupyter Lab UI を使用して新しいノートブックを作成します（[File] > [New] > [Notebook]）。または、BigQuery DataFrames GitHub リポジトリからこのチュートリアルに関連付けられたノートブックをダウンロードして開きます。

ローカルデータにアクセスして準備する

このチュートリアルでは、USDA の小麦データを分析します。Pandas はデータをダウンロードし、一般的なローカル データ分析ワークフローを模倣します。

次に、データをローカルの pandas DataFrame に読み込みます。SQL 処理用のローカルの pandas データを準備する際は、pyarrow dtype_backend を使用します。これにより、データを BigQuery SQL エンジンに渡す際の NULL 値の処理で一貫性が維持され、スキーマ マッピングもシームレスに行えるようになります。この例では、小麦の年間供給量と消失量のデータが含まれている「Table05」シートを読み込みます。

SQL でローカルの DataFrame に対してクエリを実行する前に、SQL に適した列名になっているか確認してください。BigQuery は柔軟な列名をサポートしており、ほとんどの Unicode 文字を使用できますが、"/" や "" などの特殊文字は削除または置き換えておく必要があります。

標準的な Python と pandas の構文を使用して基本的なフィルタリングを行い、欠損データのある行を削除します。これは、処理チェーンにおける最初の Python のみのステップとなります。

BigQuery SQL マジックを初期化する

BigQuery DataFrames ライブラリには、Python 環境と SQL 環境の橋渡し役となる %%bqsql マジックが用意されています。このマジックを使うことで、BigQuery クエリエンジンがローカルの pandas DataFrame（一時テーブルとして暗黙的にアップロードする）だけでなく、実際の BigQuery テーブルや、GCS（Parquet、Iceberg、CSV）内の外部テーブルを直接参照してクエリできるようになります。

ノートブックでこの統合を有効にするには、bigframes 拡張機能を読み込みます。

注: この拡張機能は、BigQuery Studio 環境と Colab 環境にプリロードされています。

無料枠内での利用を含め、クエリの使用料が適切な Google Cloud プロジェクトに対して課金されるように、マジックで使用するプロジェクト ID を設定します。無料のサンドボックス ティアであっても、クエリリソースを割り当てるにはプロジェクト ID が必要です。明示的に設定しない場合、BigFrames は環境（アプリケーションのデフォルト認証情報など）から検出を試みます。

SQL を使用したローカルの pandas DataFrame にクエリを実行する

プロジェクトの設定が完了し、ローカルの pandas DataFrame（full_rows）に対して BigQuery のテーブルと同様に、SQL クエリを直接実行できるようになりました。SQL クエリ内で、変数名を波括弧 {full_rows} で囲んで記述するだけです。認証コードの入力を求められる場合がありますが、その場合は同じメッセージに含まれているリンクをクリックして認証コードを取得してください。

SQL と Python のチェーン: SQL の結果を保存する

%%bqsql マジックの真の力は、処理を連結できる点にあります。%%bqsql の引数に保存先の変数名を指定すると（例: %%bqsql destination_var）、クエリ結果が BigQuery DataFrame としてその変数に保存されます。

この DataFrame は BigQuery エンジン上で処理されますが、Python では pandas DataFrame と同じように操作できます。この結果は、後続の Python セルですぐに使用したり、別の SQL セルから再度参照したりできます。これにより、マルチステップのハイブリッドな処理パイプラインを構築できます。

SQL を使用してデータをフィルタリングし、年単位のエントリのみを抽出して、その結果を「yearly」という名前の新しい BigFrames DataFrame に保存します。

これで、別の SQL オペレーションをチェーンできます。作成したばかりの年単位の BigFrames DataFrame を参照し、SQL の正規表現を使用して年を抽出します。それをタイムスタンプにキャストして、結果を timeseries という名前の新しい BigFrames DataFrame に保存します。

Python から SQL、そして再び Python へと処理のチェーンが構築されていることに注目してください。

Python に戻って可視化する

SQL 変換が完了したので、次は Python へとチェーンを戻して可視化を行います。BigFrames の DataFrame は pandas API を実装しているため、データセット全体を事前にダウンロードすることなく、標準的な可視化メソッド（.plot.line() など）を時系列 DataFrame で直接呼び出すことができます。計算は BigQuery で行われ、要約されたグラフデータのみがノートブックに返されます。

または、時系列を pandas DataFrame としてダウンロードして、選択した可視化ライブラリで使用することもできます。

ハイブリッド パイプラインが重要である理由

BigQuery DataFrames と %%bqsql マジックを組み合わせることで、SQL と Python をシームレスに橋渡しする強力で相互運用性に優れたパイプラインが構築されました。

• ローカルの pandas df と full_rows DataFrame

• SQL フィルタへ

• BigFrames の yearly DataFrame へ

• SQL 変換へ

• BigFrames の timeseries DataFrame へ

• Python によるデータ可視化へ

• ローカルの pandas DataFrame へ

このアーキテクチャの主な利点:

• 最適なツールの使い分け: SQL が得意な処理（大規模な集計、ウィンドウ関数、複雑な結合）は SQL に、Python が得意な処理（可視化、統計モデリング、ML オーケストレーション）は Python に任せられます。

• コードの可読性が向上: 数十もの共通テーブル式（CTE）が連なる巨大な SQL クエリを書いたり、SQL に比べて複雑になりがちな pandas API で集計を行ったりする代わりに、パイプラインを論理的なステップに分割し、SQL と Python を交互に組み合わせて記述できます。

• シームレスなスケーリング: %%bqsql コードは、ローカルの小さな pandas DataFrame から本番環境の BigQuery テーブルの数十億行まで、まったく同じコードでスケールできます。最初のローカルの pandas DataFrame を BigQuery DataFrame 参照に置き換えるだけです。

次のステップとスケールアップ

BigFrames API リファレンス サイトでその他のノートブックもご確認ください。%%bqsql セルマジックに加えて、BigFrames は標準の pandas DataFrame に BigQuery Accessor も登録します。これにより、ローカルの pandas データに対して SQL スカラー関数を直接実行できるようになります。

たとえば、df.bigquery.sql_scalar(...) を使用して、BigQuery Utils、BigFunctions、CARTO Analytics Toolbox for BigQuery などで公開されている Google Cloud コミュニティの強力な UDF を呼び出すことができます。

BigQuery サンドボックスは、これらのハイブリッド Python-SQL ワークフローを無料でテストできる強力な環境ですが、BigQuery Machine Learning（BQML）などの高度な機能は制限されています。請求先アカウントを Google Cloud プロジェクトに接続すると、bigframes.bigquery.ai.forecast 関数などの高度な機能を利用できるようになります。この関数を使用すれば、SQL と Python のチェーンで Google 最先端の基盤モデルを直接使用して時系列データを予測できます。

ハイブリッド Python-SQL エクスペリエンスに関するフィードバックを BigFrames チームまでぜひお寄せください。

• メール: bigframes-feedback@google.com

• 問題: オープンソースの BigFrames リポジトリでバグ報告や機能リクエストを提出してください。

• 最新情報: ニュースや最新情報を受け取るには、BigFrames のメーリング リストにご登録ください。

• 詳細: ドキュメントで BigFrames API リファレンスとユーザーガイドをご確認ください。

- BigQuery DataFrames チームリーダー、Tim Swena