Firestore エクスポートからのデータの読み込み

BigQuery では、Firestore マネージド インポートおよびエクスポート サービスを使用して作成された Firestore のエクスポートからのデータの読み込みをサポートしています。マネージド インポートおよびエクスポート サービスでは、Firestore のドキュメントを Cloud Storage バケットにエクスポートします。このエクスポートされたデータを BigQuery テーブルに読み込むことができます。

注: Firestore のすべてのエクスポートを読み込むことはできません。BigQuery テーブルに読み込める Firestore エクスポートを作成する場合は、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 のエクスポート形式は同じです。

注: bq コマンドライン ツールで --projection_fields フラグを使用するか、load ジョブ構成で projectionFields プロパティを設定すると、特定のフィールドを読み込むことができます。

Console

1. Cloud Console で、[BigQuery] ページを開きます。

   [BigQuery] に移動

2. [エクスプローラ] パネルでプロジェクトを開いて、データセットを選択します。

3. アクション オプションを開いて、[開く] をクリックします。

4. 詳細パネルで [テーブルを作成] をクリックします。

5. [テーブルの作成] ページの [ソース] セクションで、次の操作を行います。

   • [テーブルの作成元] で [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 で生成されたファイルの名前です。

     注: 末尾が overall_export_metadata のファイルは使用しないでください。このファイルは BigQuery では使用できません。

     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 のエクスポート形式は同じです。

6. [テーブルの作成] ページの [送信先] セクションで、次の操作を行います。

   • [データセット名] で、該当するデータセットを選択します。

     

   • [テーブル名] に、BigQuery で作成するテーブルの名前を入力します。

   • [テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。

7. [Schema] セクションでは、何もする必要はありません。スキーマは Firestore のエクスポートから推定されます。

8. [詳細オプション] セクションで該当する項目を選択します。既存のテーブルを上書きする場合は、[書き込み設定] を [テーブルを上書きする] に設定します。

   

9. [テーブルを作成] をクリックします。

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 のエクスポート データを読み込むには、次のプロパティを設定します。

1. Cloud Storage のソースデータを参照する load ジョブ構成を作成します。

2. ジョブリソースの jobReference セクションにある location プロパティでロケーションを指定します。

3. 読み込みジョブの構成で sourceUris を gs://BUCKET/OBJECT の形式で完全修飾する必要があります。ファイル（オブジェクト）名の末尾は、KIND_NAME.export_metadata でなければなりません。Firestore のエクスポートに使用できる URI は 1 つのみです。URI にワイルドカードは使用できません。

4. 読み込みジョブの構成で sourceFormat プロパティを DATASTORE_BACKUP に設定し、データ形式を指定します。Firestore の場合、適切なオプションは Datastore Backup です。Firestore と Datastore のエクスポート形式は同じです。

5. 特定のフィールドだけを読み込むには、projectionFields プロパティを設定します。

6. 既存のテーブルを上書きする場合は、writeDisposition プロパティを WRITE_TRUNCATE に設定して、書き込み処理を指定します。

Python

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用にある Python の設定手順を行ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。

エディタで開く GitHub で表示 フィードバック

# TODO(developer): Set table_id to the ID of the table to create.
table_id = "your-project.your_dataset.your_table_name"

# TODO(developer): Set uri to the path of the kind export metadata
uri = (
    "gs://cloud-samples-data/bigquery/us-states"
    "/2021-07-02T16:04:48_70344/all_namespaces/kind_us-states"
    "/all_namespaces_kind_us-states.export_metadata"
)

# TODO(developer): Set projection_fields to a list of document properties
#                  to import. Leave unset or set to `None` for all fields.
projection_fields = ["name", "post_abbr"]

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

job_config = bigquery.LoadJobConfig(
    source_format=bigquery.SourceFormat.DATASTORE_BACKUP,
    projection_fields=projection_fields,
)

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

注: 読み込みプロセスをスキップする場合、エクスポートを外部データソースとして設定すると、エクスポートに対して直接クエリを実行できます。詳細については、外部データソースをご覧ください。

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