よく使うbqコマンドの目的別リファレンス
認証と設定
bqコマンドを使用するための初期設定やプロジェクトの確認を行います。
| 目的 | コマンド例 | 説明 |
|---|---|---|
| 初期設定 (プロジェクト選択、認証) | | 対話形式またはオプション指定でデフォルトプロジェクトや認証方法を設定します。サービスアカウント認証も可能です。多くの場合、gcloud auth login や gcloud config set project の方が推奨されます。 |
| 現在の設定確認 | | bqコマンドの現在の設定 (デフォルトプロジェクトIDなど) をJSON形式で表示します。gcloud コマンドでも確認できます。 |
| Google Cloud SDKの認証 | | bqコマンドはGoogle Cloud SDKの一部であり、認証情報は共有されます。ユーザーアカウントまたはサービスアカウントで認証します。 |
| デフォルトプロジェクト設定 | | コマンド実行時にプロジェクトIDを省略した場合に使用されるデフォルトプロジェクトを設定します。 |
プロジェクト、データセット、テーブルの操作
リソースの一覧表示、作成、削除、詳細確認、コピーなどを行います。
| 目的 | コマンド例 | 説明 |
|---|---|---|
| プロジェクト一覧表示 | | アクセス可能なプロジェクトの一覧を表示します。gcloudコマンドでも可能です。 |
| データセット一覧表示 | | デフォルトプロジェクト、または指定したプロジェクト内のデータセット一覧を表示します。 |
| テーブル/ビュー/モデル一覧表示 | | 指定したデータセット内のテーブル、ビュー、MLモデルなどの一覧を表示します。 |
| データセット作成 | | 新しいデータセットを作成します。ロケーション、説明、デフォルトのテーブル有効期限などを指定できます。 |
| テーブル作成 (スキーマ指定) | | スキーマを指定して新しい空のテーブルを作成します。スキーマはコマンドラインで直接指定するか、JSONファイルで指定します。パーティション分割やクラスタリングも指定可能です。 |
| テーブル作成 (クエリ結果から) | | クエリの実行結果を新しいテーブルとして保存します。(詳細はクエリ実行のセクションを参照) |
| データセット削除 | | データセットを削除します。-r (--recursive) はデータセット内のテーブルも削除します。-f (--force) は確認プロンプトなしで削除します。注意して使用してください。 |
| テーブル/ビュー削除 | | テーブルまたはビューを削除します。-t (--table) でテーブルタイプを明示的に指定できます。-f は確認なしで削除します。注意して使用してください。 |
| データセット/テーブル詳細表示 | | データセットまたはテーブルの詳細情報(作成日時、最終更新日時、ロケーション、スキーマ、行数、サイズなど)を表示します。--schema でスキーマ情報のみを表示、--format=prettyjson でJSON形式で表示します。 |
| テーブルコピー | | テーブルをコピーします。プロジェクト間コピーも可能です。 -a (--append_table): 宛先テーブルに追記します。 -f (--force): 宛先テーブルが存在する場合、上書きします。 -n (--no_clobber): 宛先テーブルが存在する場合、何もしません。 @<SNAPSHOT_TIME_MS>: 特定時点のスナップショットをコピーします(過去7日間)。 |
| テーブル情報更新 | | テーブルの説明や有効期限(秒数、0で無期限)を更新します。スキーマの更新も可能です(詳細はスキーマ操作のセクションを参照)。 |
| データセット情報更新 | | データセットの説明やデフォルトのテーブル有効期限を更新します。 |
データの表示・取得
テーブル内のデータをプレビュー表示します。
| 目的 | コマンド例 | 説明 |
|---|---|---|
| テーブルの先頭行を表示 | | テーブルの先頭から指定した行数(デフォルトは5行)のデータを表示します。-nで行数指定、--selected_fieldsで列指定、--start_rowで開始行指定、--format=csvでCSV形式出力などが可能です。大量データの取得には向きません。 |
| テーブルデータを全件取得 (非推奨) | | bq query --format=csv で全件取得するのは、データ量が多い場合に非効率的で失敗する可能性があります。大量データのエクスポートには bq extract コマンドを使用してください。(詳細はデータ書き出しのセクションを参照) |
データの読み込み (Load)
ローカルファイルやCloud Storage上のファイルからデータをBigQueryテーブルに読み込みます。
注意: Cloud Shell以外のローカル環境からローカルファイルを直接
bq loadで読み込むことは非推奨です。通常はCloud Storage経由で読み込みます。 | 目的 / オプション | コマンド例 | 説明 |
|---|---|---|
| Cloud StorageからCSV読み込み (スキーマ自動検出) | | GCS上のCSVファイルを読み込みます。--autodetectでスキーマを自動検出します。 |
| Cloud StorageからCSV読み込み (スキーマ指定) | | スキーマをコマンドラインまたはJSONファイルで指定してCSVファイルを読み込みます。 |
| Cloud StorageからJSON (Newline Delimited) 読み込み | | GCS上の改行区切りJSON (JSONL) ファイルを読み込みます。スキーマ自動検出または指定が可能です。 |
| Cloud StorageからAvro/Parquet/ORC読み込み | | Avro, Parquet, ORC形式はスキーマがファイル自体に含まれているため、通常スキーマ指定や--autodetectは不要です。 |
| ローカルファイルからCSV読み込み (Cloud Shellなど) | | ローカルのCSVファイルを読み込みます。Cloud Shell環境などで利用可能です。大規模ファイルには不向きです。 |
| ワイルドカードによる複数ファイル読み込み | | GCS上のパスにワイルドカードを使用して複数のファイルを一度に読み込みます。 |
| テーブル上書き (Replace) | | --replaceフラグを指定すると、読み込み先に同名テーブルが存在する場合、そのテーブルを削除してから新しいデータでテーブルを作成します。 |
| テーブル追記 (Append) | | --noreplace (またはフラグなしのデフォルト) は、読み込み先に同名テーブルが存在する場合、データを追記します。スキーマが一致しない場合はエラーになることがあります。 |
| スキーマ更新オプション (追記時) | | 追記時にスキーマの変更を許可します。 ALLOW_FIELD_ADDITION: 新しい列の追加を許可します。 ALLOW_FIELD_RELAXATION: REQUIRED列がNULLABLEに変更されるのを許可します。 |
| ヘッダー行スキップ (CSV) | | --skip_leading_rows=<N> で、CSVファイルの先頭N行をスキップします。ヘッダー行を除外する場合によく使われます。 |
| 区切り文字指定 (CSV) | | --field_delimiter でCSVの区切り文字を指定します。デフォルトはカンマ(,)です。タブ区切り(TSV)の場合は \t を指定します。 |
| 不正な行の許容 | | --max_bad_records=<N> で、スキーマに合わないなどの理由で不正と判断される行がN行まで許容されます。デフォルトは0です。 |
| 同期/非同期実行 | | --sync=true を指定すると、ロードジョブが完了するまでコマンドが待機します。デフォルト(false)ではジョブを開始してすぐにコマンドプロンプトが返ります。 |
データの書き出し (Extract)
BigQueryテーブルのデータをCloud Storageにファイルとして書き出します。
| 目的 / オプション | コマンド例 | 説明 |
|---|---|---|
| テーブルデータをCSV形式でGCSに書き出し | | テーブルデータをCSV形式でGCSに書き出します。デフォルトの形式はCSVです。データサイズが大きい場合、ファイルは分割されるため、出力パスにワイルドカード * を含める必要があります(例: data_*.csv)。 |
| JSON (Newline Delimited) 形式で書き出し | | 改行区切りJSON (JSONL) 形式で書き出します。 |
| Avro形式で書き出し | | Avro形式で書き出します。 |
| Parquet形式で書き出し | | Parquet形式で書き出します。 |
| 圧縮形式の指定 | | --compression で圧縮形式を指定します。CSV, JSONでは GZIP、Avroでは DEFLATE, SNAPPY が指定可能です。Parquetは通常内部で圧縮されます。ファイル名に適切な拡張子 (例: .gz) を付けることが推奨されます。 |
| 区切り文字の指定 (CSV) | | --field_delimiter でCSV書き出し時の区切り文字を指定します。デフォルトはカンマ(,)です。 |
| ヘッダー行の出力 (CSV) | | --print_header=true (デフォルト) でCSVファイルの先頭にヘッダー行を出力します。false でヘッダーなしになります。 |
| 同期/非同期実行 | | --sync=true を指定すると、エクスポートジョブが完了するまでコマンドが待機します。デフォルト(false)ではジョブを開始してすぐにコマンドプロンプトが返ります。 |
クエリの実行
SQLクエリを実行し、結果を表示したり、新しいテーブルに保存したりします。
| 目的 / オプション | コマンド例 | 説明 |
|---|---|---|
| 標準SQLクエリ実行 (結果表示) | | --nouse_legacy_sql または --use_legacy_sql=false を指定して標準SQL (GoogleSQL) を実行します。結果はコンソールに表示されます。テーブル名はバッククォート(`)で囲みます。 |
| レガシーSQLクエリ実行 (結果表示) | | --use_legacy_sql (または --use_legacy_sql=true) を指定してレガシーSQLを実行します。テーブル名は角括弧([])で囲みます。特別な理由がない限り、標準SQLの使用が推奨されます。 |
| クエリ結果を新しいテーブルに保存 | | --destination_table オプションで、クエリ結果を保存する新しいテーブルを指定します。テーブルが存在しない場合は作成されます。 |
| クエリ結果を既存テーブルに追記 | | --destination_table と --append_table (または --append) を指定すると、既存のテーブルにクエリ結果を追記します。スキーマが一致する必要があります。 |
| クエリ結果で既存テーブルを上書き | | --destination_table と --replace を指定すると、既存のテーブルを削除し、クエリ結果で新しいテーブルを作成(上書き)します。 |
| バッチモードでの実行 | | --batch フラグを指定すると、クエリはバッチジョブとしてキューイングされ、インタラクティブクエリよりも低い優先度で実行されます。実行開始まで時間がかかる場合がありますが、長時間実行されるクエリに適しています。 |
| 結果サイズ制限の緩和 (宛先テーブル指定時) | | --allow_large_results フラグは、クエリ結果が無料枠のキャッシュサイズ制限を超える場合に必要です。宛先テーブル (--destination_table) の指定が必須です。レガシーSQLではデフォルトで有効です。 |
| 最大課金バイト数の設定 | | --maximum_bytes_billed <BYTES> で、クエリがスキャンする最大バイト数を制限します。意図しない高額課金を防ぐのに役立ちます。超えた場合はエラーになります。 |
| クエリパラメータの使用 | | --parameter='<NAME>:<TYPE>:<VALUE>' 形式でクエリパラメータを指定します。SQLインジェクションを防ぎ、クエリの再利用性を高めます。標準SQLでのみ利用可能です。 |
| ドライラン (Dry Run) | | --dry_run フラグを指定すると、実際にクエリを実行せずに、構文チェックやスキャンされるデータ量(課金対象バイト数)の見積もりを行います。コストの見積もりに便利です。--nouse_cache を併用するとキャッシュを無視してバイト数を見積もります。 |
| SQLファイルを指定して実行 | | ファイルに保存されたSQLクエリを標準入力から読み込んで実行します。 |
| 結果のフォーマット指定 (コンソール出力時) | | --format オプションで、コンソールに出力される結果のフォーマットを指定できます (csv, json, prettyjson, none など)。bq head と同様に、大量データの取得には向きません。 |
ジョブの管理
実行中のジョブや過去のジョブの状態を確認したり、キャンセルしたりします。
| 目的 | コマンド例 | 説明 |
|---|---|---|
| ジョブ一覧表示 | | 最近実行されたジョブ(クエリ、ロード、エクスポートなど)の一覧を表示します。 -j (--jobs): ジョブ一覧を表示します。 --all: 全てのユーザーのジョブを表示します(権限が必要)。 -n <NUM>: 表示する最大ジョブ数を指定します。 --project_id: 対象のプロジェクトを指定します。 --state: ジョブの状態 (running, pending, done) でフィルタリングします。 |
| ジョブ詳細表示 | | 指定したジョブIDの詳細情報(ジョブタイプ、状態、開始/終了時刻、処理バイト数、エラー情報など)を表示します。ジョブIDは bq ls -j で確認できます。プロジェクトIDやロケーションが必要な場合もあります。 |
| ジョブのキャンセル | | 実行中 (RUNNING) または待機中 (PENDING) のジョブをキャンセルします。キャンセルが必ず成功するとは限りません。 |
スキーマの操作
テーブルのスキーマ定義を確認したり、変更したりします。
| 目的 | コマンド例 | 説明 |
|---|---|---|
| スキーマ表示 | | テーブルのスキーマ情報をJSON形式で表示します。--format=prettyjson を付けると見やすくなります。 |
| スキーマ定義をファイルに保存 | | bq show --schema の出力をリダイレクトして、スキーマ定義をJSONファイルとして保存します。 |
| スキーマの更新 (列の追加など) | | 既存のテーブルスキーマを更新します。JSONファイルで新しいスキーマ全体を指定します。 可能な変更:
|
その他の便利なコマンド
その他の便利なbqコマンドやオプションです。
| 目的 | コマンド例 | 説明 |
|---|---|---|
| ヘルプ表示 | | bqコマンド全体、または特定のサブコマンド (load, query など) のヘルプメッセージを表示します。 |
| バージョン表示 | | bqコマンドツールのバージョンを表示します。 |
| グローバルフラグ: プロジェクトID指定 | | --project_id フラグを付けると、そのコマンド実行時のみ対象のプロジェクトIDを指定できます。デフォルト設定を一時的に上書きします。 |
| グローバルフラグ: ロケーション指定 | | --location フラグで、データセット作成時などのロケーションを指定します (例: US, EU, asia-northeast1)。 |
| APIリクエスト/レスポンス表示 | | --apilog フラグを指定すると、bqコマンドが内部で呼び出しているBigQuery APIのリクエストとレスポンスの詳細を標準出力または指定ファイルに出力します。デバッグに役立ちます。 |