bq
コマンドライン ツールの使用
bq
コマンドライン ツールは、Python をベースにした BigQuery 用のコマンドライン ツールです。このページでは、bq
コマンドライン ツールの使い方を説明します。
すべての bq
コマンドとフラグの詳細なリファレンスについては、bq
コマンドライン ツール リファレンスをご覧ください。
準備
bq
コマンドライン ツールを使用する前に、Google Cloud Console を使用して、プロジェクトを作成または選択する必要があります。
- Google Cloud アカウントにログインします。Google Cloud を初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。
-
Google Cloud Console の [プロジェクト セレクタ] ページで、Google Cloud プロジェクトを選択または作成します。
-
Google Cloud Console の [プロジェクト セレクタ] ページで、Google Cloud プロジェクトを選択または作成します。
- 新しいプロジェクトでは、BigQuery が自動的に有効になります。既存のプロジェクトで BigQuery を有効にするには、
BigQuery API を有効にします。
に移動します。 - (省略可)プロジェクトに対する課金を有効にします。課金を有効にしない場合や、クレジット カードを指定しない場合でも、このドキュメントの手順は行えます。BigQuery には、この手順を実施するためのサンドボックスが用意されています。詳細については、BigQuery サ2ンドボックスを有効にするをご覧ください。
Cloud Shell で bq
コマンドを入力する
Cloud Shell で bq
コマンドライン ツールのコマンドを入力するには、Google Cloud Console または Google Cloud CLI を使用します。
Google Cloud コンソールから
bq
コマンドライン ツールを使用するには、Cloud Shell をアクティブにします。gcloud CLI から
bq
コマンドライン ツールを使用するには、gcloud CLI をインストールして構成します。
フラグと引数の配置
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
に設定されており、デバッグ出力が Google Cloud コンソールに出力されます。 - グローバル フラグ
--format
がprettyjson
に設定されており、人が読める JSON 形式でコマンド出力が表示されます。 - グローバル フラグ
--location
がUS
マルチリージョン ロケーションに設定されています。 query
コマンド固有のフラグ--use_legacy_sql
がfalse
に設定されており、Google 標準 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
コマンドライン ツールの実行
Google Cloud CLI コマンドを実行するように、スクリプト内で 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
コマンドライン ツールを使用してデータを読み込む方法については、次をご覧ください。
- Cloud Storage からの Avro データの読み込み
- Cloud Storage からの JSON データの読み込み
- Cloud Storage からの CSV データの読み込み
- ローカル ファイルからのデータの読み込み
データのクエリ
bq
コマンドライン ツールを使用してデータをクエリする方法については、次をご覧ください。
外部データソースの使用
bq
コマンドライン ツールを使用して外部データソースのデータをクエリする方法については、次をご覧ください。
- JSON スキーマ ファイルを使用してテーブル定義を作成する
- 外部の永続テーブルを使用して Cloud Bigtable データをクエリする
- 外部の永続テーブルを使用して Cloud Storage データをクエリする
- 永続外部テーブルを使用して Google ドライブのデータをクエリする
データのエクスポート
bq
コマンドライン ツールを使用してデータをエクスポートする方法については、次をご覧ください。
BigQuery Data Transfer Service の使用
BigQuery Data Transfer Service で bq
コマンドライン ツールを使用する方法については、以下をご覧ください。
- Amazon S3 の転送の設定
- キャンペーン マネージャーの転送の設定
- Cloud Storage の転送の設定
- Google アド マネージャーの転送の設定
- Google 広告の転送の設定
- Google Merchant Center の転送の設定(ベータ版)
- Google Play の転送の設定
- 検索広告 360 の転送の設定(ベータ版)
- YouTube チャンネルの転送の設定
- YouTube コンテンツ所有者の転送の設定
- Amazon Redshift からのデータ移行
- Teradata からのデータ移行
bq
コマンドライン ツールのトラブルシューティング
このセクションでは、bq
コマンドライン ツールの問題の解決方法を説明します。
gcloud CLI を最新の状態に保つ
Google Cloud CLI の bq
コマンドライン ツールを使用している場合は、gcloud CLI を常に最新の状態にし、bq
コマンドライン ツールの最新の機能と修正を使用できるようにします。gcloud CLI の最新バージョンを実行しているかどうかを確認するには、Cloud Shell で次のコマンドを入力します。
gcloud components list
出力の最初の 2 行には、現在の gcloud CLI インストールのバージョン番号と最新の gcloud CLI のバージョン番号が表示されます。バージョンが最新でない場合は、Cloud Shell で次のコマンドを入力すると、gcloud CLI の最新のインストール バージョンに更新できます。
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
プロパティを使用すると、トラブルシューティングの手順を参照できます。