BigQuery には、Cloud Storage またはローカル ファイルからバッチ オペレーションとしてデータを読み込むことができます。ソースデータは次のいずれかの形式になります。
- Avro
- カンマ区切り値(CSV)
- JSON(改行区切り)
- ORC
- Parquet
- Cloud Storage に保存されている Firestore のエクスポート
BigQuery Data Transfer Service を使用して、Cloud Storage から BigQuery への定期的な読み込みを設定することもできます。
必要な権限
BigQuery にデータを読み込むには、読み込みジョブを実行する権限が必要です。また、新規または既存の BigQuery テーブルやパーティションへのデータの読み込みが可能な権限も必要です。Cloud Storage からデータを読み込む場合は、データを含むバケットに対するアクセス権限も必要です。
BigQuery の権限
BigQuery にデータを読み込むには、少なくとも以下の権限が必要です。これらの権限は、データを新しいテーブルまたはパーティションに読み込む場合や、テーブルまたはパーティションに対してデータの追加や上書きを行う場合に必要になります。
bigquery.tables.create
bigquery.tables.updateData
bigquery.jobs.create
bigquery.tables.create
権限および bigquery.tables.updateData
権限はいずれも、事前定義された以下の IAM ロールに含まれています。
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
次の事前定義済みの IAM ロールには bigquery.jobs.create
権限が含まれています。
bigquery.user
bigquery.jobUser
bigquery.admin
また、bigquery.datasets.create
権限を持つユーザーがデータセットを作成すると、そのデータセットに対する bigquery.dataOwner
アクセス権がユーザーに付与されます。bigquery.dataOwner
アクセス権により、読み込みジョブを使用してデータセット内のテーブルを作成または更新できます。
BigQuery での IAM ロールと権限の詳細については、アクセス制御をご覧ください。
Cloud Storage の権限
Cloud Storage バケットからデータを読み込むには、storage.objects.get
権限が付与されている必要があります。URI のワイルドカードを使用する場合は storage.objects.list
権限も必要です。
IAM 事前定義ロール storage.objectViewer
が付与されると、storage.objects.get
権限と storage.objects.list
権限の両方が与えられます。
Cloud Storage からのデータの読み込み
BigQuery では以下の Cloud Storage ストレージ クラスからデータを読み込むことができます。
- Standard
- Nearline
- Coldline
- アーカイブ
BigQuery にデータを読み込む方法については、以下のデータ形式のページをご覧ください。
Cloud Storage から BigQuery への定期的な読み込みを構成する方法については、Cloud Storage の転送をご覧ください。
ロケーションに関する留意事項
データのロケーションを選択するときは、次の点を考慮してください。
- データを読み込むには、Cloud Storage バケットを同じリージョンに配置する
- BigQuery データセットがマルチリージョン ロケーションにある場合、読み込み対象のデータが含まれている Cloud Storage バケットは、同じロケーションのリージョン バケットまたはマルチリージョン バケット内になければなりません。たとえば、BigQuery データセットが EU にある場合、Cloud Storage バケットは EU のリージョンまたはマルチリージョン バケットに存在する必要があります。
- データセットがリージョン ロケーションにある場合、Cloud Storage バケットは同じロケーションのリージョン バケットに存在する必要があります。たとえば、データセットが東京リージョンにある場合、Cloud Storage バケットは東京のリージョン バケットである必要があります。
- 例外: データセットが米国のマルチリージョン ロケーションにある場合、任意のリージョンまたはマルチリージョン ロケーションにある Cloud Storage バケットからデータを読み込むことができます。
- データ管理計画を作成する
- BigQuery データセットや Cloud Storage バケットなどのリージョン ストレージ リソースを選択する場合は、データの地理的管理を行うための計画を作成します。
Cloud Storage のロケーションの詳細については、Cloud Storage ドキュメントのバケットのロケーションをご覧ください。
データセットの作成後にそのロケーションを変更することはできませんが、データセットのコピーを作成できます。また、手動で移動することもできます。詳細情報
Cloud Storage URI の取得
Cloud Storage データソースからデータを読み込むには、Cloud Storage URI を指定する必要があります。
Cloud Storage URI は、バケット名とオブジェクト(ファイル名)で構成されます。たとえば、Cloud Storage バケットの名前が mybucket
でデータファイルの名前が myfile.csv
の場合、バケットの URI は gs://mybucket/myfile.csv
になります。データが複数のファイルに分かれている場合は、URI にワイルドカードを使用できます。詳細については、Cloud Storage のリクエスト URI をご覧ください。
BigQuery は、最初のダブル スラッシュ以降に複数の連続スラッシュが含まれるソース URI をサポートしていません。Cloud Storage では、オブジェクト名に複数の連続スラッシュ("/")文字を含めることができます。一方、BigQuery では、複数の連続スラッシュは単一のスラッシュに変換されます。たとえば、gs://bucket/my//object//name
というソース URI は Cloud Storage では有効ですが、BigQuery では機能しません。
Cloud Storage URI を取得するには:
Cloud Storage Console を開きます。
ソースデータを含むオブジェクト(ファイル)の場所に移動します。
Cloud Storage Console の上部に、オブジェクトのパスが表示されます。URI を作成するには、
gs://bucket/file
を適切なパス(例:gs://mybucket/myfile.json
)に置き換えます。bucket は Cloud Storage バケット名で、file はデータを含むオブジェクト(ファイル)の名前です。
Cloud Storage の URI でのワイルドカードの使用
Cloud Storage データを分割し、共通のベース名を持つ複数のファイルに保存した場合、そのデータを読み込むときに URI でワイルドカードを使用できます。
Cloud Storage の URI にワイルドカードを追加するには、ベース名にアスタリスク(*
)を追加します。たとえば、fed-sample000001.csv
と fed-sample000002.csv
という 2 つのファイルがある場合、バケット URI は gs://mybucket/fed-sample*
になります。このワイルドカード URI は、Cloud Console、bq
コマンドライン ツール、API、クライアント ライブラリで使用できます。
バケット内のオブジェクト(ファイル名)について使用できるワイルドカードは 1 つのみです。ワイルドカードは、オブジェクト名の中や末尾に使用できます。バケット名にワイルドカードを付けることはできません。
Google Datastore のエクスポートで指定できる URI は 1 つのみです。また、URI の末尾は .backup_info
または .export_metadata
である必要があります。
以下の場合、ワイルドカード文字(アスタリスク)は使用できません。
- Datastore または Firestore のエクスポートにリンクされる外部テーブルを作成する。
- Cloud Storage から Datastore または Firestore のエクスポート データを読み込む。
制限事項
Cloud Storage バケットから BigQuery にデータを読み込む際には、次の制限があります。
- データセットのロケーションが
US
以外の値に設定されている場合は、リージョンまたはマルチリージョンの Cloud Storage バケットがデータセットと同じリージョンに存在する必要があります。 - BigQuery では外部データソースに対して整合性が保証されません。クエリの実行中に基になるデータを変更すると、予期しない動作が発生する可能性があります。
Cloud Storage のソースデータの形式によっては、追加の制限が適用される場合があります。詳細情報
ローカル ファイルからのデータの読み込み
次のいずれかを使用して、読み取り可能なデータソース(ローカルマシンなど)からデータを読み込むことができます。
- Google Cloud Console
bq
コマンドライン ツールのbq load
コマンド- API
- クライアント ライブラリ
Cloud Console または bq
コマンドライン ツールを使用してデータを読み込むと、読み込みジョブが自動的に作成されます。
データをローカル データソースから読み込むには:
Console
Cloud Console で [BigQuery] ページを開きます。
ナビゲーション パネルの [リソース] セクションで、Google Cloud プロジェクトを展開し、データセットを選択します。
ウィンドウの右側の詳細パネルで、[テーブルを作成] をクリックします。データを読み込むプロセスは、空のテーブルを作成するプロセスと同じです。
[テーブルの作成] ページの [ソース] セクションで、次の操作を行います。
[テーブルの作成元] で [アップロード] を選択します。
[ファイルを選択] の下の [参照] をクリックします。
一覧からファイルを選択して [開く] をクリックします。ワイルドカードやカンマ区切りのリストは、ローカル ファイルに対してはサポートされないことに注意してください。
ファイル形式として、CSV、JSON(改行区切り)、Avro、Parquet または ORC を選択します。
[テーブルを作成] ページの [送信先] セクションで、次の操作を行います。
[データセット名] で、該当するデータセットを選択します。
[テーブル名] に、BigQuery で作成するテーブルの名前を入力します。
[テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。
[スキーマ] セクションでスキーマ定義を入力します。
CSV や JSON ファイルの場合は、自動検出オプションをオンにしてスキーマの自動検出を有効にできます。スキーマ情報は、サポートされているその他のファイル形式のソースデータで自己記述されます。
次の方法でスキーマ情報を手動で入力することもできます。
[テキストとして編集] をクリックし、テーブル スキーマを JSON 配列として入力します。
[フィールドを追加] を使用して、スキーマを手動で入力します。
[詳細オプション] セクションで該当する項目を選択します。使用可能なオプションについては、CSV のオプションと JSON のオプションをご覧ください。
省略可: [詳細オプション] で書き込み処理を選択します。
- 空の場合に書き込む: テーブルが空の場合にのみデータを書き込みます。
- テーブルに追加する: テーブルの末尾にデータを追加します。これがデフォルトの設定です。
- テーブルを上書きする: 新しいデータを書き込む前に、テーブル内の既存のデータをすべて削除します。
[テーブルを作成] をクリックします。
bq
bq load
コマンドを使用して source_format
を指定し、ローカル ファイルへのパスも指定します。
(省略可)--location
フラグを指定して、その値をロケーションに設定します。
デフォルト プロジェクト以外のプロジェクトのデータを読み込む場合は、PROJECT_ID:DATASET
の形式でプロジェクト ID をデータセットに追加します。
bq --location=LOCATION load \ --source_format=FORMAT \ PROJECT_ID:DATASET.TABLE \ PATH_TO_SOURCE \ SCHEMA
以下を置き換えます。
LOCATION
: ロケーション。--location
フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値をasia-northeast1
に設定します。ロケーションのデフォルト値は、.bigqueryrc ファイルを使用して設定できます。FORMAT
:CSV
、AVRO
、PARQUET
、ORC
、NEWLINE_DELIMITED_JSON
。project_id
: プロジェクト ID。dataset
: 既存のデータセット。table
: データの読み込み先のテーブル名。path_to_source
: ローカル ファイルへのパス。schema
: 有効なスキーマ。スキーマはローカルの JSON ファイルにすることも、コマンドの一部としてインラインで入力することもできます。また、スキーマ定義を指定する代わりに、--autodetect
フラグを使用することもできます。
その他にも、BigQuery によるデータの解析方法を制御するオプションに対応するフラグを追加できます。たとえば、--skip_leading_rows
フラグを使用すると、CSV ファイル内のヘッダー行が無視されます。詳細については、CSV のオプションと JSON のオプションをご覧ください。
例:
次のコマンドは、ローカルの改行区切りの JSON ファイル(mydata.json
)をデフォルト プロジェクトの mydataset
内にある mytable
というテーブルに読み込みます。スキーマは、myschema.json
という名前のローカル スキーマ ファイルで定義されています。
bq load \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
./mydata.json \
./myschema.json
次のコマンドは、ローカルの CSV ファイル(mydata.csv
)を myotherproject
の mydataset
内にある mytable
という名テーブルに読み込みます。スキーマは、FIELD:DATA_TYPE, FIELD:DATA_TYPE
の形式でインラインで定義されます。
bq load \
--source_format=CSV \
myotherproject:mydataset.mytable \
./mydata.csv \
qtr:STRING,sales:FLOAT,year:STRING
次のコマンドは、ローカルの CSV ファイル(mydata.csv
)をデフォルト プロジェクトの mydataset
内にある mytable
というテーブルに読み込みます。スキーマはスキーマ自動検出を使用して定義されます。
bq load \
--autodetect \
--source_format=CSV \
mydataset.mytable \
./mydata.csv
C#
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の C# の設定手順を実施してください。詳細については、BigQuery C# API のリファレンス ドキュメントをご覧ください。
次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、UploadCsvOptions
の代わりに、JobCreationOptions 基本クラスから適切な形式のアップデート オプション クラスを選択します。
Go
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。
次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、NewReaderSource
の DataFormat プロパティを適切な形式に設定します。
Java
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、FormatOptions を該当の形式に設定します。
Node.js
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、load 関数のmetadata
パラメータを適切な形式に設定します。
PHP
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用にある PHP 向けの手順に従って設定を行ってください。詳細については、BigQuery PHP API のリファレンス ドキュメントをご覧ください。
次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、sourceFormat を該当の形式に設定します。
Python
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、LoadJobConfig.source_format プロパティを適切な形式に設定します。
Ruby
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用で説明している Ruby 向けの手順に沿って設定を行ってください。詳細については、BigQuery Ruby API のリファレンス ドキュメントをご覧ください。
次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカル ファイルを読み込むには、Table#load_job メソッドのformat
パラメータを適切な形式に設定します。
制限事項
ローカル データソースからのデータの読み込みには、次の制限があります。
- ワイルドカードやカンマ区切りのリストは、ローカル データソースからファイルを読み込む場合にはサポートされません。ファイルは個別に読み込む必要があります。
- 従来の BigQuery ウェブ UI を使用するときは、ローカル データソースから読み込まれるファイルのサイズが 10 MB 以下で、ファイル内の行数が 16,000 未満である必要があります。
圧縮データと非圧縮データを読み込む
Avro バイナリ形式は、圧縮データと非圧縮データの両方の読み込みに適しています。データブロックが圧縮されていても、Avro データは並行して読み取ることができるため、より高速に読み込みが行われます。圧縮 Avro ファイルはサポート対象外ですが、圧縮データブロックはサポートされています。BigQuery では、Avro ファイル内の圧縮データブロックに対して DEFLATE コーデックと Snappy コーデックがサポートされています。
Parquet の効率的な列単位のエンコーディングでは通常、圧縮率が高くなり、ファイルサイズが小さくなるため、Parquet バイナリ形式も適しています。Parquet ファイルは、ファイルの並列読み込みが可能な圧縮手法も使用します。圧縮 Parquet ファイルはサポート対象外ですが、圧縮データブロックはサポートされています。BigQuery では、Parquet ファイルの圧縮データブロックに対して Snappy コーデック、GZip コーデック、LZO_1X コーデックがサポートされています。
ORC バイナリ形式には、Parquet 形式に似た利点があります。データ ストライプを並列で読み取ることができるため、ORC ファイルのデータは高速で読み取ることができます。各データ ストライプの行が順番に読み込まれます。読み込み時間を短縮するには、データ ストライプのサイズを 256 MB 以下にします。圧縮 ORC ファイルはサポート対象外ですが、圧縮ファイルのフッターとストライプはサポートされています。 BigQuery では、ORC ファイルのフッターとストライプに対して Zlib 圧縮、Snappy 圧縮、LZO 圧縮、LZ4 圧縮がサポートされています。
CSV や JSON などのデータ形式の場合、BigQuery では非圧縮ファイルを並列読み取りできるため、非圧縮ファイルを圧縮ファイルよりかなり速く読み込むことができます。ただし、非圧縮ファイルはサイズが大きいため、使用すると帯域幅の制限に達し、BigQuery に読み込まれる前に Cloud Storage にステージングされるデータのために Cloud Storage のコストが高くなる可能性があります。圧縮ファイルや非圧縮ファイルの場合、行の順序が保証されないことにもご注意ください。使用状況に応じて、どちらを重視するかを決定する必要があります。
一般に、帯域幅が限られている場合は、CSV ファイルや JSON ファイルを gzip で圧縮してから Cloud Storage にアップロードします。現在のところ、BigQuery にデータを読み込む CSV ファイルと JSON ファイルに対してサポートされているファイル圧縮形式は gzip のみです。読み込み速度が重要なアプリを使用していて、データの読み込み用に豊富な帯域幅がある場合は、ファイルを圧縮しないでおきます。
テーブルへの追加または上書き
テーブルに追加のデータを読み込むには、ソースファイルを使用するか、クエリ結果を追加します。データのスキーマが追加先のテーブルまたはパーティションのスキーマと一致しない場合は、追加または上書きするときにスキーマを更新できます。
データの追加時にスキーマを更新する場合、BigQuery では次のことが可能です。
- 新しいフィールドを追加する
- フィールドのモードを
REQUIRED
からNULLABLE
に緩和する
テーブルを上書きする場合、スキーマは必ず上書きされます。テーブルを上書きするとき、スキーマの更新は制限されません。
Cloud Console では、[書き込み設定] オプションを使用して、ソースファイルやクエリ結果からデータを読み込むときに行う操作を指定します。bq
コマンドライン ツールと API には、次のオプションがあります。
Console のオプション | bq ツールのフラグ |
BigQuery API のプロパティ | 説明 |
---|---|---|---|
Write if empty | なし | WRITE_EMPTY | テーブルが空の場合にのみデータを書き込みます。 |
テーブルに追加する | --noreplace または --replace=false (--replace を指定しない場合、デフォルトは追加) |
WRITE_APPEND | (デフォルト)テーブルの末尾にデータを追加します。 |
テーブルを上書きする | --replace または --replace=true |
WRITE_TRUNCATE | 新しいデータを書き込む前に、テーブル内の既存のデータをすべて消去します。 |
割り当てポリシー
データのバッチ読み込みの割り当てポリシーについては、割り当てと上限のページの読み込みジョブをご覧ください。
料金
現在、BigQuery にデータを読み込むための料金はかかりません。詳細については、料金のページをご覧ください。