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

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

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

始める前に

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

Google Cloud アカウントにログインします。Google Cloud を初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

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

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

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

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

Cloud Shell で `bq` コマンドを入力する

Cloud Shell で bq コマンドラインツールのコマンドを入力するには、Google Cloud Console または Cloud SDK を使用します。

Cloud Console から bq コマンドラインツールを使用するには、Cloud Shell をアクティブにします。

Cloud Shell をアクティブにする
Cloud SDK から bq コマンドラインツールを使用するには、Cloud SDK をインストールして構成します。

フラグと引数の配置

bq コマンドラインツールは、次の 2 種類のフラグをサポートしています。

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

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

グローバルフラグを bq コマンドの前に配置し、次にコマンド固有のフラグを含めます。複数のグローバルフラグまたはコマンド固有のフラグを含めることができます。次に例を示します。

bq --location=us mk --reservation --project_id=project reservation_name

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

--FLAG ARGUMENT（前の例で示しています）
--FLAG=ARGUMENT
--FLAG='ARGUMENT'
--FLAG="ARGUMENT"
--FLAG 'ARGUMENT'
--FLAG "ARGUMENT"

次のように置き換えます。

FLAG: グローバルまたはコマンド固有のフラグ
ARGUMENT: フラグの引数

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

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

ブール値を持つフラグは、引数なしで指定できます。true または false を指定する場合は、FLAG=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` コマンドラインツールからのクエリの実行

Google Cloud Console で作成したクエリを受け取り、そのクエリを bq コマンドラインツールから実行するには、次の手順を行います。

bq query --use_legacy_sql=false 'QUERY' のように、bq query コマンドにクエリを含めます。QUERY はクエリに置き換えます。
クエリ内の一重引用符（'）は二重引用符（"）に置き換えます。
クエリからコメントを削除します。

たとえば、次の Google Cloud Console クエリを変換します。

-- count Shakespeare's use of the string "raisin"
SELECT
  word,
  SUM(word_count) AS count
FROM
  `bigquery-public-data`.samples.shakespeare
WHERE
  word LIKE '%raisin%'
GROUP BY
  word

次のように bq コマンドラインツールのクエリに変換します。

bq query --use_legacy_sql=false \
'SELECT
  word,
  SUM(word_count) AS count
FROM
  `bigquery-public-data`.samples.shakespeare
WHERE
  word LIKE "%raisin%"
GROUP BY
  word'

詳細については、インタラクティブクエリとバッチクエリのジョブの実行をご覧ください。

困ったときは

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

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

COMMAND は、ヘルプが必要なコマンドで置き換えます。

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

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

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

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

.bigqueryrc にコマンドラインフラグのデフォルト値を追加するには:

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

例:

--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

上の例では、次のフラグにデフォルト値を設定しています。

グローバルフラグ --apilog が stdout に設定されており、デバッグ出力が Cloud Console に出力されます。
グローバルフラグ --format が prettyjson に設定されており、人が読める JSON 形式でコマンド出力が表示されます。
グローバルフラグ --location が US マルチリージョンロケーションに設定されています。
query コマンド固有のフラグ --use_legacy_sql が false に設定されており、標準 SQL がデフォルトのクエリ構文になります。

注: .bigqueryrc で --nouse_legacy_sql は使用できません。
query コマンド固有のフラグ --max_rows が 100 に設定されており、クエリ出力の行数が制御されます。
query コマンド固有のフラグ --maximum_bytes_billed が 10,000,000 バイト（10 MB）に設定されており、10 MB を超えるデータを読み取るクエリが失敗します。
load コマンド固有のフラグ --destination_kms_key が projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey に設定されています。

対話型シェルでの `bq` コマンドラインツールの実行

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

スクリプトでの `bq` コマンドラインツールの実行

gcloud コマンドラインツールのコマンドを実行するように、スクリプトで bq コマンドラインツールを実行できます。次に、bash スクリプトの gcloud コマンドと bq コマンドの例を示します。

#!/bin/bash
gcloud config set project myProject
bq query --use_legacy_sql=false --destination_table=myDataset.myTable \
'SELECT
   word,
   SUM(word_count) AS count
 FROM
   `bigquery-public-data`.samples.shakespeare
 WHERE
   word LIKE "%raisin%"
 GROUP BY
   word'

サービスアカウントからの `bq` コマンドの実行

サービスアカウントを使用して bq コマンドを実行するには、サービスアカウントから Google Cloud へのアクセスを承認する必要があります。詳細については、gcloud auth activate-service-account をご覧ください。

例

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

リソースの作成

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

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

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

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

リソースの一覧表示

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

リソースの更新

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

データの読み込み

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

データのクエリ

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

外部データソースの使用

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

データのエクスポート

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

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

BigQuery Data Transfer Service の使用

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

`bq` コマンドラインツールのトラブルシューティング

このセクションでは、bq コマンドラインツールの問題の解決方法を説明します。

Cloud SDK を最新の状態に保つ

Cloud SDK の bq コマンドラインツールを使用している場合は、Cloud SDK を常に最新の状態にし、bq コマンドラインツールの最新の機能と修正を使用できるようにします。Cloud SDK の最新バージョンを実行しているかどうかを確認するには、Cloud Shell で次のコマンドを入力します。

gcloud components list

出力の最初の 2 行に、現在の Cloud SDK のバージョン番号と、最新の Cloud SDK のバージョン番号が表示されます。バージョンが最新でない場合は、Cloud Shell で次のコマンドを入力すると、Cloud SDK の最新バージョンに更新できます。

gcloud components update

デバッグ

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

送受信されたリクエストを確認する。--apilog=PATH_TO_FILE フラグを追加して、オペレーションのログをローカルファイルに保存します。PATH_TO_FILE は、ログを保存するパスで置き換えます。bq コマンドラインツールは、標準の REST ベースの API 呼び出しを行うことで動作します。これは、表示すると有用な場合があります。また、問題を報告するときにはこのログを添付することをおすすめします。パスの代わりに - または stdout を使用すると、Google Cloud Console にログが出力されます。--apilog を stderr に設定すると、標準のエラーファイルに出力されます。
エラーのトラブルシューティング。ジョブのステータスを取得する場合、またはテーブルやデータセットなどのリソースに関する詳細情報を表示する場合は、--format=prettyjson フラグを入力します。このフラグを使用すると、reason プロパティを含む JSON 形式のレスポンスが出力されます。reason プロパティを使用すると、トラブルシューティングの手順を参照できます。