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 に読み込むことはできません。

必要な権限

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 権限の両方が与えられます。

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