BigQuery では、Cloud Firestore マネージド インポートおよびエクスポート サービスを使用して作成された Cloud Firestore のエクスポートからのデータの読み込みをサポートしています。マネージド インポートおよびエクスポート サービスでは、Cloud Firestore のドキュメントを Cloud Storage バケットにエクスポートします。このエクスポートされたデータを BigQuery テーブルに読み込むことができます。
制限事項
Cloud Firestore のエクスポートから BigQuery にデータを読み込む場合は、次の制限事項に注意してください。
- データセットは、エクスポート ファイルが格納される Cloud Storage バケットと同じリージョンまたはマルチリージョンのロケーションに存在する必要があります。
- 指定できる Cloud Storage URI は 1 つのみで、URI ワイルドカードは使用できません。
- Cloud Firestore のエクスポートを正しく読み込むには、エクスポート データ内のドキュメントが一貫したスキーマを共有し、個別のフィールド名が 10,000 個未満でなければなりません。
- 新しいテーブルを作成してデータを保存することも、既存のテーブルを上書きすることもできますが、Cloud Firestore のエクスポート データを既存のテーブルに追加することはできません。
- エクスポート コマンドには、
collection-idsフィルタを指定する必要があります。コレクション ID フィルタを指定せずにエクスポートされたデータを BigQuery に読み込むことはできません。
必要な権限
BigQuery にデータを読み込むには、読み込みジョブを実行する権限が必要です。また、新規または既存の BigQuery テーブルやパーティションにデータを読み込むための権限も必要です。Cloud Storage からデータを読み込む場合は、データを含むバケットに対するアクセス権限が必要です。
BigQuery の権限
BigQuery にデータを読み込むには、少なくとも以下の権限が必要です。これらの権限は、データを新しいテーブルまたはパーティションに読み込む場合や、既存のテーブルまたはパーティションに対してデータの追加や上書きを行う場合に必要になります。
bigquery.tables.createbigquery.tables.updateDatabigquery.jobs.create
事前定義された以下の Cloud IAM 役割には、bigquery.tables.create と bigquery.tables.updateData の両方の権限が含まれています。
bigquery.dataEditorbigquery.dataOwnerbigquery.admin
bigquery.jobs.create 権限は、以下の事前定義された Cloud IAM 役割に含まれています。
bigquery.userbigquery.jobUserbigquery.admin
また、bigquery.datasets.create 権限を持つユーザーがデータセットを作成すると、作成したデータセットに対する bigquery.dataOwner アクセス権がそのユーザーに付与されます。
bigquery.dataOwner アクセス権により、読み込みジョブを使用してデータセット内のテーブルを作成または更新する権限が付与されます。
BigQuery での Cloud IAM 役割と権限については、アクセス制御をご覧ください。
Cloud Storage の権限
Cloud Storage バケットからデータを読み込むには、storage.objects.get 権限が付与されている必要があります。URI のワイルドカードを使用する場合は storage.objects.list 権限も必要です。
事前定義された Cloud IAM 役割 storage.objectViewer が付与されると、storage.objects.get 権限と storage.objects.list 権限が両方とも与えられます。
Cloud Firestore のエクスポート サービスデータの読み込み
BigQuery ウェブ UI、bq コマンドライン ツール、API を使用して Cloud Firestore のエクスポート メタデータ ファイルからデータを読み込むことができます。
UI やコマンドで Cloud Datastore の用語が使用されることがありますが、次の手順は Cloud Firestore のエクスポート ファイルにも対応しています。Cloud Firestore と Cloud Datastore のエクスポート形式は同じです。
Console
- GCP Console で BigQuery ウェブ UI を開きます。
BigQuery ウェブ UI に移動 - ナビゲーション パネルの [リソース] セクションでプロジェクトを展開し、データセットを選択します。[テーブルを作成] をクリックします。データを読み込むプロセスは、空のテーブルを作成するプロセスと同じです。
[テーブルの作成] ページの [ソース] セクションで、次の操作を行います。
[テーブルの作成元] で [Cloud Storage] を選択します。
ソース フィールドに Cloud Storage URI を入力します。Cloud Storage バケットは、データセットと同じロケーションに存在する必要があります。Cloud Firestore のエクスポート ファイルの URI は、末尾が
[KIND_COLLECTION_ID].export_metadataとなっています。たとえば、default_namespace_kind_Book.export_metadataとなります。この例では、Bookがコレクション ID で、default_namespace_kind_Bookが Cloud Firestore によって生成されたファイルの名前です。[KIND_COLLECTION_ID]が Cloud Storage URI で指定されていることを確認します。[KIND_COLLECTION_ID]を指定せずに URI を指定すると、「does not contain valid backup metadata. (error code: invalid)」というエラーが返されます。[File format] で [Cloud Datastore Backup] を選択します。Cloud Firestore の場合、適切なオプションは Cloud Datastore Backup です。Cloud Firestore と Cloud Datastore のエクスポート形式は同じです。
[テーブルを作成] ページの [送信先] セクションで、次の操作を行います。
[データセット名] で、該当するデータセットを選択します。
[テーブル名] フィールドに、BigQuery で作成するテーブルの名前を入力します。
[テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。
[Schema] セクションでは、何もする必要はありません。スキーマは Cloud Firestore のエクスポートから推定されます。
[詳細オプション] セクションで該当する項目を選択します。既存のテーブルを上書きする場合は、[書き込み設定] を [テーブルを上書きする] に設定します。
[テーブルを作成] をクリックします。
従来の UI
- 従来の BigQuery ウェブ UI に移動します。
BigQuery ウェブ UI に移動 - ナビゲーション パネルで、データセットにカーソルを合わせ、下矢印アイコン
をクリックして [Create new table] をクリックします。 [Create Table] ページの [Source Data] セクションで、次の操作を行います。
- [Create from source] をオンのままにします。
[Location] で [Cloud Storage] を選択し、ソース フィールドに Cloud Storage URI を入力します。Cloud Storage バケットは、データセットと同じロケーションに存在する必要があります。Cloud Firestore のエクスポート ファイルの URI は、末尾が
[KIND_COLLECTION_ID].export_metadataとなっています。たとえば、default_namespace_kind_Book.export_metadataとなります。この例では、Bookがコレクション ID で、default_namespace_kind_Bookが Cloud Firestore によって生成されたファイルの名前です。[KIND_COLLECTION_ID]が Cloud Storage URI で指定されていることを確認します。[KIND_COLLECTION_ID]を指定せずに URI を指定すると、「does not contain valid backup metadata. (error code: invalid)」というエラーが返されます。[File format] で [Cloud Datastore Backup] を選択します。Cloud Firestore の場合、適切なオプションは Cloud Datastore Backup です。Cloud Firestore と Cloud Datastore のエクスポート形式は同じです。
[Create Table] ページの [Destination Table] セクションで、次の操作を行います。
- [Table name] で適切なデータセットを選択し、BigQuery で作成するテーブルの名前をテーブル名のフィールドに入力します。
- [Table type] が [Native table] に設定されていることを確認します。
[Schema] セクションでは、何もする必要はありません。スキーマは Cloud Firestore のエクスポートから推定されます。
[Options] セクションで該当する項目を選択します。既存のテーブルを上書きする場合は、[Write preference] を [Overwrite table] に設定します。
[Create Table] をクリックします。
CLI
source_format を DATASTORE_BACKUP に設定した bq load コマンドを使用します。--location フラグを指定し、その値を該当するロケーションに設定します。既存のテーブルを上書きする場合は、--replace フラグを追加します。
特定のフィールドのみを読み込むには、--projection_fields フラグを使用します。
bq --location=[LOCATION] load \
--source_format=[FORMAT] \
[DATASET].[TABLE] \
[PATH_TO_SOURCE]
ここで
[LOCATION]はロケーションです。--locationフラグは省略可能です。[FORMAT]はDATASTORE_BACKUPです。Cloud Firestore の場合、適切なオプションは Cloud Datastore Backup です。Cloud Firestore と Cloud Datastore のエクスポート形式は同じです。[DATASET]は、データの読み込み先のテーブルを含むデータセットです。[TABLE]は、データの読み込み先のテーブルです。テーブルが存在しない場合は、新規に作成されます。[PATH_TO_SOURCE]は、Cloud Storage URI です。
たとえば次のコマンドは、Cloud Firestore のエクスポート ファイル gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata を book_data という名前のテーブルに読み込みます。
mybucket と mydataset は US マルチリージョン ロケーションに存在します。
bq --location=US load \
--source_format=DATASTORE_BACKUP \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata
API
API を使用して Cloud Firestore のエクスポート データを読み込むには、次のプロパティを設定します。
Cloud Storage のソースデータを参照する
loadジョブ構成を作成します。sourceUrisは完全修飾にする必要があります。読み込みジョブの構成で、gs://[BUCKET]/[OBJECT]の形式で指定します。ファイル（オブジェクト）名の末尾は、[KIND_NAME].export_metadataでなければなりません。Cloud Firestore のエクスポートに使用できる URI は 1 つのみです。URI にワイルドカードは使用できません。読み込みジョブの構成で
sourceFormatプロパティをDATASTORE_BACKUPに設定し、データ形式を指定します。Cloud Firestore の場合、適切なオプションは Cloud Datastore Backup です。Cloud Firestore と Cloud Datastore のエクスポート形式は同じです。特定のフィールドだけを読み込むには、
projectionFieldsプロパティを設定します。既存のテーブルを上書きする場合は、
writeDispositionプロパティをWRITE_TRUNCATEに設定して、書き込み処理を指定します。
Cloud Firestore のオプション
BigQuery が Cloud Firestore のエクスポート データを解析する方法を変更するには、次のオプションを指定します。
| CSV のオプション | 従来の UI のオプション | CLI のフラグ | BigQuery API のプロパティ | 説明 |
|---|---|---|---|---|
| Projection フィールド | なし | --projection_fields |
projectionFields |
（省略可）Cloud Firestore のエクスポートから読み込むドキュメント フィールドを示すカンマ区切りリスト。デフォルトでは、BigQuery はすべてのフィールドを読み込みます。フィールド名では大文字と小文字が区別されます。また、フィールドはエクスポート内に存在する必要があります。map.foo などのマップ フィールド内にフィールドパスを指定することはできません。
|
| 許可されている不良レコード数 | 許容されるエラー数 | --max_bad_records |
maxBadRecords |
（オプション）BigQuery でジョブの実行時に無視できる不良レコードの最大数。不良レコードの数がこの値を超えると、ジョブ結果で「無効」エラーが返されます。デフォルト値は 0、つまりすべてのレコードが有効である必要があります。 |
データ型の変換
BigQuery は、Cloud Firestore のエクスポート ファイル内の各ドキュメントのデータを BigQuery のデータ型に変換します。次の表に、変換前と変換後のデータ型を示します。
| Cloud Firestore のデータ型 | BigQuery のデータ型 |
|---|---|
| 配列 | RECORD |
| ブール値 | BOOLEAN |
| 参照 | RECORD |
| 日時 | TIMESTAMP |
| 地図 | RECORD |
| 浮動小数点数 | FLOAT |
| 地理的座標 |
RECORD
[{"lat","FLOAT"},
{"long","FLOAT"}]
|
| 整数 | INTEGER |
| 文字列 | STRING（64 KB で切り捨て） |
Firestore のキーのプロパティ
Cloud Firestore の各ドキュメントには、ドキュメント ID やドキュメント パスなどの情報を含む一意のキーが設定されています。次の表に示すように、BigQuery は、情報の各部分のネストされたフィールドで、キーに対して RECORD データ型（STRUCT とも呼ばれます）を作成します。
| キーのプロパティ | 説明 | BigQuery のデータ型 |
|---|---|---|
__key__.app |
Cloud Firestore アプリの名前。 | STRING |
__key__.id |
ドキュメントの ID、または null（__key__.name が設定されている場合）。 |
INTEGER |
__key__.kind |
ドキュメントのコレクション ID。 | STRING |
__key__.name |
ドキュメントの名前、または null（__key__.id が設定されている場合）。 |
STRING |
__key__.namespace |
Cloud Firestore はカスタム名前空間をサポートしていません。デフォルトの名前空間は空白の文字列で表されます。 | STRING |
__key__.path |
ドキュメントのパス: ドキュメントとルート コレクションからのコレクション ペアのシーケンス（例: "Country",
"USA", "PostalCode", 10011, "Route", 1234）。 |
STRING |
ご不明な点がありましたら、Google の