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