G-gen の武井です。当記事では、BigQuery と Git リポジトリを連携する機能である BigQuery リポジトリを解説します。

はじめに
機能説明
検証1（セットアップ）
検証2（バージョン管理）
- デモの概要
- commit
- push
- pull
- 復元
- クエリ実行
検証3（GitHub リポジトリとの接続）
関連記事

はじめに

BigQuery リポジトリとは、BigQuery と Git リポジトリを連携する機能です。Google Cloud コンソールの BigQuery 操作画面である BigQuery Studio において、組み込みの Git リポジトリまたは GitHub 等の Git リポジトリと接続して、SQL ファイル等のバージョン管理をしたり、Git ワークフローを操作することができます。

これにより、以下のようなメリットを得ることができます。

Git リポジトリ上の SQL をそのまま BigQuery 上で実行できる
BigQuery Studio 上で SQL のバージョン管理ができる
チームでの共同作業が容易になる

当記事では、BigQuery リポジトリの機能、セットアップ方法、ならびに操作手順について説明します。

なお当機能は、2025年4月時点でプレビューです。

参考 : Preview版のサービスを使うとはどういうことなのか

機能説明

リポジトリ

BigQuery リポジトリでは、組み込みの BigQuery リポジトリを使用するか、以下のサードパーティーリポジトリと接続可能です。

Git プロバイダ	接続方法
Microsoft Azure DevOps Services	SSH
Bitbucket	SSH
GitHub	SSH または HTTPS
GitLab	SSH または HTTPS

参考：サードパーティのリポジトリ

リポジトリの利用形態

リポジトリの利用形態は以下の2通りです。

プライベートリポジトリ
- リポジトリ作成者のみ利用可能
共有リポジトリ
- 複数のプリンシパルで共有可能

参考：リポジトリを共有する

取り扱い可能なファイル

リポジトリにて取り扱い可能なファイルは以下の通りです。

SQL クエリ
Python ノートブック
データキャンバス
データプレパレーション
上記以外のファイル

参考：ワークスペース内のファイルを操作する

バージョン管理

リポジトリでは以下のバージョン管理操作が実行できます。

オプション	説明
変更	ワークスペースまたは選択したファイルのローカル変更を commit する
push	commit をデフォルトブランチ（main）または指定のブランチに push する
pull	デフォルトブランチをワークスペースに pull する
復元	ワークスペースにあるファイルを前回の commit に復元する

参考：ファイルでバージョン管理を使用する

IAM ロール

共有リポジトリとワークスペースの操作に必要な権限は以下の通りです。

操作	IAM ロール
共有リポジトリの作成・管理	コードオーナー（`roles/dataform.codeOwner`）
ワークスペースの作成・削除	コードエディタ（`roles/dataform.codeEditor`）
ファイルの作成・変更・バージョン管理	同上
リソースの表示	コード閲覧者（`roles/dataform.codeViewer`）

また、プライベートリポジトリとワークスペースの操作に必要な権限は以下の通りです。

操作	IAM ロール
プライベートリポジトリの作成・管理	コード作成者（`roles/dataform.codeCreator`）
ワークスペースの作成・削除	同上
ファイルの作成・変更・バージョン管理	同上

参考：必要なロール

料金

BigQuery リポジトリの利用に料金はかかりません。

参考：料金

検証1（セットアップ）

セットアップの概要

当記事では、BigQuery Studio に BigQuery リポジトリ（標準の組み込みリポジトリ）を接続し、SQL ファイルのバージョン管理を行います。

リポジトリの作成

BigQuery Studio > リポジトリを表示 > リポジトリの追加 の順で BigQuery リポジトリを作成します。

作成時点ではプライベートリポジトリですが、[︙]アイコン > 共有の順で共有リポジトリに変更できます。（作成者以外のプリンシパルに権限を付与することができます）

参考：リポジトリを作成する
参考：リポジトリを共有する

ワークスペースの作成

先ほど作成したリポジトリ名をクリックし、ワークスペースタブ > ワークスペースを追加の順でワークスペースを作成します。

なお、ワークスペースとは同じリポジトリで作業している他のユーザーに影響を与えることなく、リポジトリでファイルの作成、編集、削除を行うための仮想的な作業空間を意味します。

作成後は開く > 確認の順でクリックすると、BigQuery Studio にリポジトリを接続できます。

ディレクトリの作成

次に、ワークスペースにディレクトリを作成します。今回のデモでは、クエリ先の構成に合わせてディレクトリを作成します。

.
└── sample
    ├── customers
    │   └── demo.sql
    ├── products
    │   └── ...
    └── sales
        └── ...

[+] アイコン > リポジトリに作成 > ディレクトリ の順でディレクトリを作成します。

SQL ファイルの作成

各ディレクトリに SQL ファイルを作成し、クエリのバージョン管理を行います。

各ディレクトリの [︙] アイコン > リポジトリに作成 > SQL クエリの順で SQL ファイル作成します。

ファイルにクエリを入力すると（変更が検知したため）、Commit X Changeと表示されました。

検証2（バージョン管理）

デモの概要

先ほど作成した SQL クエリをもとに、バージョン管理操作を行います。

commit

変更を commit します。

Commit X change をクリックすると、変更内容が確認できます。commit メッセージ（必須）を入力後、すべて（あるいは X 個）のファイルを commit をクリックします。

push

次に、先ほどの commit をデフォルトブランチ（main）に push します。

プルダウン > デフォルトブランチに push を実行すると、デフォルトブランチにマージされます。

pull

共有リポジトリにおいて、他メンバーが push した内容を取り込みたい場合、プルダウン > デフォルトブランチから pull を実行します。

復元

変更の過程で前回の commit に戻したい場合、プルダウン > 前回の commit に戻す を実行します。

クエリ実行

リポジトリで管理する SQL ファイルは、BigQuery Studio 上で直接実行できます。

検証3（GitHub リポジトリとの接続）

GitHub リポジトリを BigQuery Studio に接続する場合、以下の準備が必要です。

GitHub リポジトリ
Secret Manager
- HTTPS の場合は個人アクセストークン、SSH の場合は秘密鍵を格納したシークレットを作成
IAM Policy
- 上記にアクセスできるよう、Dataform デフォルトサービスアカウントに対し以下の IAM ロールを付与
- Secret Manager シークレットアクセサー（roles/secretmanager.secretAccessor）

上記の準備が完了したら、リポジトリの追加 から GitHub リポジトリ接続用の BigQuery リポジトリを作成し、リポジトリの構成タブ > Git 接続を編集の順で設定を進めると GitHub リポジトリを接続できます。