bq コマンドライン ツール

bq は、コマンドラインから BigQuery にアクセスする python ベースのツールです。

インストール

Google Cloud SDK をインストールします

一般的な使用方法

フラグの配置

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

bq --common_flags <bq_command> --command-specific_flags <command_arguments>
  • 共通フラグは、--project_id--apilog など、すべてのコマンドに適用されるフラグです。よく使用される共通フラグのリストを表示するには、bq --helpshort を呼び出します。
  • コマンド固有のフラグは、特定のコマンドに適用される任意のフラグです。たとえば、-p コマンドの -j-dls(それぞれ、プロジェクト、ジョブ、データセットをリスト表示する)です。

通常、コマンドの後に共通フラグを配置すると失敗します。

例: bq --format=json ls -d

ヘルプとデバッグ

  • コマンドの完全なリストを参照するには、bq help を実行します。
  • 特定のコマンドのヘルプを参照するには、bq help <command> を実行します。
  • 送受信した実際のリクエストを表示するには(アプリケーションのデバッグに役立ちます)、フラグ --apilog=<file> を追加してオペレーションのログを file に保存します。 ファイルパスの代わりに - を使用すると、コンソールにログが出力されます。bq は標準の REST ベースの API 呼び出しを行うことで動作します。これは、表示すると有用な場合があります。また、問題を報告するときにも、このログを添付すると有用です。
  • エラーのトラブルシューティングに役立つ情報を表示するには、--format=prettyjson フラグを使用してジョブのステータスを表示します。このフラグは、エラーが発生したオブジェクトを出力します。これに含まれる reason プロパティを使用して、エラーのトラブルシューティングでトラブルシューティングの手順を探すことができます。たとえば bq --format=prettyjson show -j <job id> です。

共通フラグのデフォルト値の設定

bq を初めて実行すると、デフォルトのプロジェクト ID の入力が求められます。この ID は .bigqueryrc ファイルに格納されます。

.bigqueryrc ファイルを編集して、共通フラグのデフォルト値を更新したり、追加したりできます。新しいデフォルト値は、1 行ずつ、flagname=flagvalue のように追加します。このファイルで設定できるのは、共通フラグのデフォルト値だけです。コマンド固有のフラグを設定すると、bq を実行するときにエラーが発生します。このファイルは、単一使用モードで bq を実行するたびに読み込まれるため、変更はすぐに反映されます。ただし、bq を対話モードbq shell)で実行する場合は、シェルを再起動して変更をインポートする必要があります。

cat ~/.bigqueryrc
戻り値:
project_id = 1092187650
dataset_id=mydataset

非同期オペレーションの実行

bq ツールは、コマンドラインでステータス カウンタを更新することにより、非同期コマンドを実行します。コマンドの実行に長い時間がかかる場合は、ジョブを開始するときにジョブ ID を要求してすぐに制御を戻し、その後、実行中のジョブにフックするように bq で指定できます。これにより、コマンドラインを解放して他の処理を実行できます。ただし、これはクエリや読み込みなど、長時間走行するジョブでのみ有用です。

非同期ジョブを開始して ID を要求するには、--nosync フラグと共に bq コマンドを呼び出します。これによりジョブ ID が返されます。ジョブの結果を取得する(またはジョブのステータスを印刷する)には、このジョブ ID をコマンド bq wait <job_id> に渡します。

次の例では、非同期読み込みジョブを開始し、現在のデータベースのデータセットをリスト表示し、その後でジョブの結果を取得するための呼び出しを行います。

$ bq --nosync load mydataset.names2010 gs://bigquerybucket/yob2010.txt name:string,gender:string,count:integer
Successfully started load job job_f0afc92f7a9043849e5cae7b2e7ea2f9
$ bq ls
   datasetId
 -------------
  olddataset
  mydataset
$ bq wait job_f0afc92f7a9043849e5cae7b2e7ea2f9

対話モードでの bq の実行

bq は対話型モードで実行でき、コマンドに「bq」という接頭辞を付ける必要はありません。対話モードを開始するには、bq shell を呼び出します。プロンプトは、デフォルトのプロジェクトの ID です。対話モードを終了するには、「exit」と入力します。

bq shell
Welcome to BigQuery! (Type help for more information.)
10000000021> ls
   datasetId
 -------------
  mydataset
10000000021> exit
Goodbye.

有用な共通フラグ

共通フラグは bq とコマンドの間に使用されます。フラグの全リストについては、bq --help を呼び出してください。

最も役に立つフラグのいくつかを次に示します:

  • --apilog - すべてのサーバー リクエストと応答のログを有効にします。文字列が指定されていない(--apilog=)場合は、stdout にログを記録し、文字列が指定されている(--apilog=filename)場合は、そのファイルにログを記録します。
  • --format [none|json|prettyjson|csv|sparse|pretty] - 出力形式です。

プロジェクト、データセット、テーブルのリスト表示

オブジェクトをリスト表示するには、bq ls コマンドを次の構文で使用します:

bq ls [<project_id>:][<dataset_id>]

<project_id><dataset_id> は、これらの値が .bigqueryrc ファイルで定義されている場合は省略できます。ただし、bq ls に渡す値は .bigqueryrc で定義される値よりも優先されます。プロジェクト ID は分かりやすい名前ではなく、通常は数値の文字列です。

詳細情報:

プロジェクトでの作業

プロジェクトのリスト表示

すべてのプロジェクトをリスト表示するには:

bq ls -p

デフォルト プロジェクトの設定

初めて bq を実行するときに、デフォルトのプロジェクト ID を入力する必要があります。入力した ID は bigqueryrc ファイルに保存されます。このファイルを編集して、デフォルトのプロジェクトの値を変更できます。

デフォルトのプロジェクトの表示

デフォルト値を表示するには、cat ~/.bigqueryrc を実行します。または、対話モードで実行するときに、デフォルトのプロジェクト ID がプロンプトに表示されます。

データセットの操作

データセットの作成

bq mk コマンドを使用してデータセットを作成します。

bq mk [DATASET_ID]

[DATASET_ID] は有効なデータセット ID です。有効なデータセット ID とは、以下の条件を満たすものです。

  • 文字、数字、アンダースコアだけで構成されている [a-zA-Z0-9_]
  • プロジェクト内で一意

データセット ID は、大文字と小文字が区別されます。たとえば、my_datasetMy_Dataset は異なる ID で、同じプロジェクト内で同時に使用できます。

デフォルトのデータセットの設定

デフォルトのデータセットを使用する場合、データセットの ID を使用してテーブルまたはその他のアクションを修飾する必要がないように、デフォルトのデータセットを指定できます。これを行うには、bigqueryrc ファイルに次の行を追加します。

dataset_id=[DATASET_ID]

以下のようにすると簡単です([DATASET_ID] は、使用するデータセット ID に置き換えてください)。

echo dataset_id=[DATASET_ID] >> ~/.bigqueryrc

データセットのリスト表示

デフォルトのプロジェクトまたはデータセットを定義しているかどうかに応じて、構文は異なります。

# List datasets in the default project:
bq ls

# List datasets in another project:
bq ls [PROJECT_ID]:

# List datasets when you have a default dataset defined:
bq ls -d
  OR
bq ls :

テーブルの操作

テーブル情報の取得

bq show <project_id>:<dataset_id>.<table_id>

bq show publicdata:samples.shakespeare
    tableId      Last modified                  Schema
 ------------- ----------------- ------------------------------------
  shakespeare   01 Sep 13:46:28   |- word: string (required)
                                  |- word_count: integer (required)
                                  |- corpus: string (required)
                                  |- corpus_date: integer (required)

テーブルデータのプレビュー

bq head [-n <rows>] <project_id>:<dataset_id>.<table_id>

bq head -n 10 publicdata:samples.shakespeare
+--------------+------------+--------------+-------------+
|     word     | word_count |    corpus    | corpus_date |
+--------------+------------+--------------+-------------+
| brave        |          6 | 1kinghenryiv |        1597 |
| profession   |          1 | 1kinghenryiv |        1597 |
| treason      |          2 | 1kinghenryiv |        1597 |
| Ned          |          9 | 1kinghenryiv |        1597 |
| answered     |          1 | 1kinghenryiv |        1597 |
| Perceived    |          1 | 1kinghenryiv |        1597 |
| 'You         |          1 | 1kinghenryiv |        1597 |
| degenerate   |          1 | 1kinghenryiv |        1597 |
| neighbouring |          1 | 1kinghenryiv |        1597 |
| grandam      |          1 | 1kinghenryiv |        1597 |
+--------------+------------+--------------+-------------+

このオペレーションはテーブルの内容をプレビューすることのみを目的としていて、テーブルの大部分を抽出する場合は効率的な方法ではありません。明示的に指定しない場合、コマンドはデフォルトで 100 行を返します。

テーブルのリスト表示

デフォルトのプロジェクトまたはデータセットを定義しているかどうかに応じて、構文は異なります。

# In the default project:
  bq ls dataset_id

# In the default project and dataset:
bq ls

# In another project or dataset:
  bq ls [project_id:][dataset_id]

ファイルからのテーブルの作成

テーブルを作成するか既存のテーブルにデータを追加するには、次のファイル形式をロードします。

  • Google Cloud Storage の非圧縮 CSV、JSON、Avro ファイル
  • スキーマ ファイルは Google Cloud Storage からロードできません。データファイルとスキーマ ファイルの両方を使用してテーブルを作成する場合は、スキーマ ファイルはローカルである必要があります。

  • Google Cloud Storage の圧縮(gzip 圧縮) CSV または JSON ファイル
  • Google Cloud Storage の Cloud Datastore バックアップ ファイル
  • ローカル ディスクの非圧縮 CSV、JSON、Avro ファイル

新しいテーブルを作成するには、新しいスキーマを作成し、ファイルを別の呼び出しで読み込むか、次の構文を使用して両方のオペレーションを 1 つの呼び出しに組み合わせます。

bq load <destination_table> <data_source_uri> <table_schema>
destination_table
作成するテーブルの完全修飾されたテーブル名。既にテーブルが存在する場合は、追加するテーブルの完全修飾されたテーブル名
data_source_uri
テーブルに入力するために使用されるソース CSV データファイル。これには圧縮されていないローカル ファイルを指定できますが、圧縮されていないファイルか gzip 圧縮されたファイルを参照する Google Cloud Storage の完全修飾 URI(形式は gs://bucket/file)にすることもできます。たとえば、my_file.csvgs://[BUCKET_NAME]/my_file.csv.gzmy_file.csv.gz はすべてファイルタイプとして有効です。

ファイルをカンマで区切って指定するか、ワイルドカード文字(*)を 1 つ使用すると、複数のファイルをテーブルにロードできます。ワイルドカード文字をバケット名の一部として使用することはできません。

table_schema
使用するテーブル スキーマの説明。ローカル ファイル名か、column_name:datatype ペアのカンマ区切りのリストを使用できます。この例では、カンマ区切りのリストを使用します。実際のテーブルには、次のスキーマ記述子を使用してみてください: name:string,gender:string,count:integer。ここで、"name"、"gender"、"count" は、新しいテーブルの列に割り当てられるラベルです。

必要な場合は、別のファイルでスキーマを指定し、そのファイルをテーブル スキーマとして使用できます。スキーマ ファイルには、次のプロパティを提供するエントリを持つ単一の配列オブジェクトを含める必要があります。

  • "name": 列の名前
  • "type": string などのデータ型。使用可能なすべてのデータ型については、BigQuery のデータ型をご覧ください。
  • "mode"(省略可能): このフィールドを null にできるかどうか

サンプル スキーマ ファイルを次に示します。

[
  {"name": "name", "type": "string", "mode": "required"},
  {"name": "gender", "type": "string", "mode": "nullable"},
  {"name": "count", "type": "integer", "mode": "required"}
]

bq を使用したテーブルの作成と設定の詳細なチュートリアルについては、bq コマンドライン ツールのクイックスタートを参照してください。

bq load コマンドを使用する場合は、次のオプションのフラグを指定できます:

--source_format
型: string
説明: ソースファイルのタイプ。JSON、CSV、Avro ファイル、または Cloud Datastore バックアップ ファイルを使用できます。デフォルト値は CSV です。
有効な値:
  • CSV
  • NEWLINE_DELIMITED_JSON
  • AVRO
  • DATASTORE_BACKUP
使用方法:
bq load [--source_format=NEWLINE_DELIMITED_JSON|CSV|AVRO|DATASTORE_BACKUP]  <destination_table> <data_source_uri> [<table_schema>]
--field_delimiter-F
型: string
説明: 入力ファイル内の列間の境界を示す文字。デフォルトではカンマです。
有効な値: BigQuery は、区切り文字を ISO-8859-1 エンコードに変換し、エンコードされた文字列の先頭バイトを使用してバイナリ状態の RAW データを分割します。また、BigQuery はタブ区切りを示すエスケープ シーケンス "\t" もサポートします。デフォルト値はカンマ(',')です。
使用方法:
bq load -F '|'  <destination_table> <data_source_uri> [<table_schema>]
bq load --field_delimiter='|' <destination_table> <data_source_uri> [<table_schema>]
--encoding-E
型: string
説明: 入力ファイルで使われている文字エンコード
有効な値:
  • UTF-8
  • ISO-8859-1
使用方法:
bq load -E ISO-8859-1 <destination_table> <data_source_uri> [<table_schema>]
bq load --encoding=UTF-8 <destination_table> <data_source_uri> [<table_schema>]
--max_bad_records
型: integer
説明: 読み込みジョブが中止され、更新が実行されなくなる最大の不良行数。この値が 0 より大きい場合、不正なレコードの数がこの値を超えない限り、ジョブは成功します。これは、不正なレコードが含まれている可能性のあるファイルを読み込む場合に便利です。このパラメータのデフォルト値は 0 (すべての行が有効である必要がある)です。
有効な値: 任意の整数
使用方法:
bq load --max_bad_records=3 <destination_table> <data_source_uri> [<table_schema>]
--skip_leading_rows
型: integer
説明: 先頭から指定された行数をスキップします。これは、ソース CSV ファイルのヘッダー行をスキップする場合に便利です。このパラメータのデフォルト値は 0 (すべての行がデータ行であると見なされる)です。
有効な値: 任意の整数
使用方法:
bq load --skip_leading_rows=1 <destination_table> <data_source_uri> [<table_schema>]
--[no]autodetect
型: boolean
説明: スキーマや形式オプション(CSV、JSON など)が指定されていない場合に、自動検出を有効にします。デフォルト値は --noautodetect です。
有効な値: --autodetect--noautodetect
使用方法:
bq load --autodetect <destination_table> <data_source_uri>

文字エンコード

デフォルトでは、BigQuery サービスは、すべてのソースデータが UTF-8 でエンコードされることを想定しています。ISO-8859-1 形式でエンコードされたデータを含む CSV ファイルがある場合は、データをインポートするときに、BigQuery がインポート処理中にデータを UTF-8 に正しく変換できるように、明示的にエンコードを指定する必要があります。現時点では、ISO-8859-1 または UTF-8 でエンコードされたデータのみをインポートできます。データの文字エンコードを指定する際は、以下の点に留意してください。

  • エンコードを指定しないか、データが UTF-8 であることを明示的に指定した後で UTF-8 でエンコードされていない CSV ファイルを提供した場合、BigQuery は CSV ファイルを UTF-8 に変換しようとします。

    通常、データは正常にインポートされますが、バイトごとには期待どおりの結果が得られない場合があります。これを回避するには、正しいエンコードを指定して、再度インポートしてみてください。

  • 区切り文字は、ISO-8859-1 でエンコードする必要があります。

    通常は、タブ、パイプ、カンマなどの標準的な区切り文字を使用することをおすすめします。

  • BigQuery が文字を変換できない場合は、標準の Unicode 置換文字 � に変換されます。
  • JSON ファイルは、常に UTF-8 でエンコードする必要があります。

既存のテーブルのコピー

テーブルをコピーするには、次の bq cp コマンドを実行します。

bq cp <source_table> <destination_table>

たとえば、サンプルのコピーコマンドは次のようになります:

bq cp dataset.mytable dataset2.mynewtable

また、次のようにコピー元のパスとコピー先のパスにプロジェクト ID を指定することによって、異なるプロジェクト間でテーブルをコピーできます。

bq cp 123456789123:dataset.mytable 0987654321098:dataset2.mynewtable

テーブルのコピーを実行するときは、一意のコピー先テーブルを指定する必要があります。たとえば、既に dataset2 で mynewtable というテーブルを持っている場合、上記のコマンドは失敗し、コマンドライン ツールは例外をスローします。既存のテーブルを追加または上書きする場合は、API を使用して既存のテーブルを追加または上書きするコピージョブをプログラムで開始できます。

クエリからのテーブルの作成

クエリを実行し、--destination_table フラグを指定します。

bq query --destination_table=mydataset.happyhalloween "SELECT name,count FROM mydataset.babynames WHERE gender = 'M' ORDER BY count DESC LIMIT 6"

空のテーブルの作成

-t フラグを設定した bq mk コマンドを実行し、空のテーブルを作成します。

bq mk --schema name:string,value:integer -t mydataset.newtable

mydataset は既存のデータセットの名前で、newtable は新しいテーブルの名前です。この例では、--schema の値でフィールドのカンマ区切りリストを指定しています。スキーマをファイルに保存して、このファイルの名前を --schema の値として指定することもできます。

クエリの操作

クエリの実行

次のコマンドを実行して、クエリを実行します。

bq query <query_string>
  • クエリ文字列は、二重引用符で囲む必要があります。
  • 最後の ;(セミコロン)記号は必要ありません。
  • デフォルト値が定義されている場合、プロジェクト ID またはデータセット ID を指定する必要はありません。
  • 一般的な --format フラグを使用して、JSON や CSV など他の出力形式を指定できます。
  • クエリの実行に時間がかかる場合は、コマンドラインで非同期に実行することができます。
  • テーブルに結果を保存するには、--destination_table フラグを使用します。

次の例では、このコマンドライン ツールのクイックスタート ページの新しいテーブルの作成で示した、一般公開されている新生児の名前のデータセットを使用します。

bq ls -d
   datasetId
 -------------
  mydataset
bq ls :mydataset
     tableId
 ---------------
  babynames
bq query "SELECT name,count FROM mydataset.babynames WHERE gender = 'M' ORDER BY count DESC LIMIT 6"
Waiting on job_a4e77f793e7b4d5bbc1fd69244d9e792 ... (0s) Current status: DONE
+----------+-------+
|   name   | COUNT |
+----------+-------+
| Zachary  | 22731 |
| Alfred   | 20477 |
| Gregory  | 17179 |
| Ned      | 16860 |
| Ulrich   | 15300 |
| Thomas   | 14995 |
+----------+-------+

--batch フラグを使用してバッチクエリを実行することもできます。

次の例は、非同期のバッチクエリを開始する方法を示しています。

bq --nosync query --batch "SELECT name,count FROM mydataset.babynames WHERE gender = 'M' ORDER BY count DESC LIMIT 6"

標準 SQL の有効化

クエリの標準 SQL を有効にするには、--use_legacy_sql フラグを false に設定します。たとえば、次のクエリは標準 SQL を使用して実行します。

bq query --use_legacy_sql=false "SELECT word FROM publicdata.samples.shakespeare"

クエリ結果の操作

大容量の結果の許可

クエリ結果が最大レスポンス サイズを超える場合は、大容量の結果を許可し、結果セットを宛先のテーブルに書き込むことができます。--allow_large_results フラグと --destination_table フラグを使用して、大容量結果セットを格納する宛先テーブルを作成します。

bq query --destination_table '[DATASET].[TABLE_NAME]' --allow_large_results "[QUERY]"

大容量の結果を許可する方法について詳しくは、大きいクエリ結果を返すをご覧ください。

結果の平坦化

ネストされたデータや繰り返しデータに対してクエリを実行したとき、結果セットを平坦化する必要がある場合は、--flatten_results フラグを使用します。

bq query --flatten_results "[QUERY]"

結果の平坦化について詳しくは、FLATTEN をご覧ください。

外出先でもリソースをモニタリング

Google Cloud Console アプリを入手して、プロジェクトの管理にお役立てください。

フィードバックを送信...

BigQuery のドキュメント