bq コマンドラインツールの使用

bq コマンドラインツールは、BigQuery 用の Python ベースのコマンドラインツールです。このページでは、bq コマンドラインツールの使い方を概説します。

すべての bq コマンドとフラグの詳細なリファレンスについては、bq コマンドラインツールリファレンスをご覧ください。

準備

bq コマンドラインツールを使用する前に、Google Cloud Console を使用して、プロジェクトを作成または選択し、Cloud SDK をインストールする必要があります。

Google アカウントにログインします。
Google アカウントをまだお持ちでない場合は、新しいアカウントを登録します。

Cloud Console のプロジェクトセレクタページで、Cloud プロジェクトを選択または作成します。

注: この手順で作成するリソースをそのまま保持する予定でない場合、既存のプロジェクトを選択するのではなく、新しいプロジェクトを作成してください。チュートリアルの終了後にそのプロジェクトを削除すれば、プロジェクトに関連するすべてのリソースを削除できます。

プロジェクトセレクタのページに移動

Cloud SDK をインストールして初期化します。

新しいプロジェクトでは、BigQuery が自動的に有効になります。既存のプロジェクトで BigQuery を有効にするには、 BigQuery API を有効にします。
API を有効にする
にアクセスします。
BigQuery には、クレジットカード情報の登録やプロジェクトに対する課金の有効化を行わないで使用できるサンドボックスがあります。このトピックの手順は、プロジェクトへの課金が有効かどうかに関係なく機能します。必要に応じて課金を有効にする場合は、課金を有効にする方法についてをご覧ください。

Cloud SDK をダウンロードしてインストールする代わりに、Google Cloud Shell でプリインストール版の Cloud SDK も使用できます。

一般的な使用方法

フラグの配置

bq は、グローバルフラグとコマンドフラグの 2 種類のフラグをサポートしています。これは、次に示す順序で使用する必要があります。

bq --global_flag argument bq_command --command-specific_flag argument

グローバルフラグ（共通フラグ）は、すべてのコマンドで使用できます。
コマンド固有のフラグは、特定のコマンドに適用されます。

複数のグローバルフラグまたはコマンド固有のフラグを区切るには、スペースを使用します。次に例を示します。

bq \
--global_flag argument \
--global_flag argument \
bq_command \
--command-specific_flag argument \
--command-specific_flag argument

コマンド引数は、次のいずれかの方法で指定できます。

--flag=argument
--flag='argument'
--flag="argument"
--flag argument
--flag 'argument'
--flag "argument"

これらの各メソッドは、BigQuery ドキュメント全体で使用されています。

コマンドによっては、引数の前後に一重引用符または二重引用符を使用する必要があります。これは、引数にスペース、カンマ、またはその他の特殊文字が含まれている多くのコマンドに当てはまります。次に例を示します。

bq query --nouse_legacy_sql \
'SELECT
   COUNT(*)
 FROM
   `bigquery-public-data`.samples.shakespeare'

ブール値を持つフラグは、引数なしで指定できます。true または false を指定する場合は、=argument を指定する必要があります。

たとえば、次のコマンドでは、ブールフラグ --use_legacy_sql の前に no を指定することによって、フラグを false に設定します。

bq query --nouse_legacy_sql \
'SELECT
   COUNT(*)
 FROM
   `bigquery-public-data`.samples.shakespeare'

あるいは、フラグの引数として false を指定するには、次のように入力します。

bq query --use_legacy_sql=false \
'SELECT
   COUNT(*)
 FROM
   `bigquery-public-data`.samples.shakespeare'

使用可能なグローバルフラグとコマンド固有のフラグのリストについては、bq コマンドラインツールリファレンスをご覧ください。

ヘルプの表示

次のコマンドを入力すると、bq コマンドラインツールのヘルプを表示できます。

インストールされている bq のバージョンを参照するには、「bq version」と入力します。
すべてのコマンドの一覧を参照するには、「bq help」と入力します。
グローバルフラグの一覧を参照するには、「bq --help」と入力します。
特定のコマンドのヘルプを参照するには、「bq help command」と入力します。
特定のコマンドのヘルプとグローバルフラグの一覧を参照するには、「bq command --help」と入力します。

デバッグ

次のコマンドを入力して、bq をデバッグできます。

送受信されたリクエストを確認する

--apilog=path_to_file フラグを追加して、オペレーションのログをローカルファイルに保存します。bq は標準の REST ベースの API 呼び出しを行うことで動作します。これは、表示すると有用な場合があります。また、問題を報告するときに、このログを添付することもできます。ファイルパスの代わりに - または stdout を使用すると、コンソールにログが出力されます。--apilog を stderr に設定すると、標準のエラーファイルに出力されます。
エラーのトラブルシューティングに活用する

ジョブのステータスを取得する場合、またはテーブルやデータセットなどのリソースに関する詳細情報を表示する場合は、--format=prettyjson フラグを入力します。このフラグを使用すると、reason プロパティを含む JSON 形式のレスポンスが出力されます。reason プロパティを使用すると、トラブルシューティングの手順を参照できます。

コマンドラインフラグのデフォルト値の設定

コマンドラインフラグのデフォルト値は、bq コマンドラインツールの構成ファイル（.bigqueryrc）に含めることで設定できます。デフォルトのオプションを構成する前に、まず .bigqueryrc ファイルを作成する必要があります。このファイルは、任意のテキストエディタを使用して作成できます。.bigqueryrc ファイルを作成した後、--bigqueryrc グローバルフラグを使用してファイルへのパスを指定できます。

--bigqueryrc フラグが指定されていない場合は、BIGQUERYRC 環境変数が使用されます。これが指定されていない場合、パス ~/.bigqueryrc が使用されます。デフォルトのパスは $HOME/.bigqueryrc です。

`.bigqueryrc` にフラグを追加する

.bigqueryrc にコマンドラインフラグのデフォルト値を追加するには、次の手順を行います。

ヘッダーなしでファイルの先頭にグローバルフラグを配置します。
コマンド固有のフラグについては、コマンド名（大かっこ内）を入力し、その下に次の形式でコマンド固有のフラグ（1 行に 1 つ）を追加します。

command
--command-specific_flag=argument
--command-specific_flag=argument

.bigqueryrc にコマンドラインフラグを入力するときは、フラグの引数を =argument の形式で指定する必要があります。

.bigqueryrc は、bq を実行するたびに読み取られるため、変更はすぐに反映されます。bq を対話モード（bq shell）で実行する場合、変更を反映するにはシェルを再起動する必要があります。

例

この例では、次のグローバルフラグのデフォルト値を設定します。

--apilog が stdout に設定されており、デバッグ情報がコンソールに出力されます。
--format が prettyjson に設定されており、人が読める JSON 形式でコマンド出力が表示されます。
--location が US マルチリージョンロケーションに設定されています。

この例では、次の query コマンド固有のフラグのデフォルト値を設定します。

標準 SQL をデフォルトのクエリ構文にするために、--use_legacy_sql を false に設定します。

注: .bigqueryrc で --nouse_legacy_sql は使用できません。
クエリ出力の行数を制御するために、--max_rows を 100 に設定します。
--maximum_bytes_billed が 10,000,000 バイト（10 MB）に設定されており、10 MB を超えるデータを読み取るクエリは失敗します。

この例では、次の load コマンド固有のフラグのデフォルト値を設定します。

--destination_kms_key が projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey に設定されます。

credential_file = path_to_credential_file
--apilog=stdout
--format=prettyjson
--location=US

[query]
--use_legacy_sql=false
--max_rows=100
--maximum_bytes_billed=10000000

[load]
--destination_kms_key=projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey

設定を確定するには、次のコマンドを入力します。

cat ~/.bigqueryrc

対話型シェルで `bq` を実行する

対話型シェルで bq を実行できます。対話型シェルでは、コマンドの前に bq を付ける必要はありません。インタラクティブモードを開始するには、bq shell と入力します。シェルを起動すると、プロンプトがデフォルトのプロジェクトの ID に変更されます。インタラクティブモードを終了するには、exit と入力します。

例

コマンドラインの例は、BigQuery ドキュメントの入門ガイドに多く記載されています。以下は、BigQuery リソースの作成、取得、一覧表示、削除、変更などの一般的なコマンドラインタスクへのリンクです。

リソースの作成

bq コマンドラインツールを使用してリソースを作成する方法については、次をご覧ください。

データファイルを使用してテーブルを作成する例については、データの読み込みをご覧ください。

リソースに関する情報の取得

bq コマンドラインツールを使用してリソースに関する情報を取得する方法については、次をご覧ください。

リソースの一覧表示

bq コマンドラインツールを使用してリソースを一覧表示する方法については、次をご覧ください。

リソースの更新

bq コマンドラインツールを使用してリソースを更新する方法については、次をご覧ください。

データの読み込み

bq コマンドラインツールを使用してデータを読み込む方法については、次をご覧ください。

データのクエリ

bq コマンドラインツールを使用してデータをクエリする方法については、次をご覧ください。

外部データソースの使用

bq コマンドラインツールを使用して外部データソースのデータをクエリする方法については、次をご覧ください。

データのエクスポート

bq コマンドラインツールを使用してデータをエクスポートする方法については、次をご覧ください。

BigQuery に保存されているデータのエクスポート

BigQuery Data Transfer Service の使用

BigQuery Data Transfer Service で bq コマンドラインツールを使用する方法については、次をご覧ください。