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 バケットからデータを読み込むために必要な権限を取得するには、バケットに対するストレージ管理者（roles/storage.admin）IAM ロールを付与するよう管理者に依頼してください。ロールの付与の詳細については、アクセス権の管理に関する記事をご覧ください。

この事前定義ロールには、Cloud Storage バケットからデータを読み込むために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

Cloud Storage バケットからデータを読み込むには、次の権限が必要です。

• storage.buckets.get
• storage.objects.get
• storage.objects.list (required if you are using a URI wildcard)

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

Firestore のエクスポート サービスデータの読み込み

Firestore のエクスポート メタデータ ファイルからデータを読み込むには、Google Cloud コンソール、bq コマンドライン ツール、または API を使用します。

Google Cloud コンソールと bq コマンドライン ツールでは Datastore の用語が使用されることがありますが、次の手順は Firestore のエクスポート ファイルに対応しています。Firestore と Datastore のエクスポート形式は同じです。

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

コンソール

1. Google Cloud コンソールで [BigQuery] ページに移動します。

   [BigQuery] に移動

2. [エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。
3. [データセット情報] セクションで、[ テーブルを作成] をクリックします。
4. [テーブルを作成] パネルで、次の詳細を指定します。
1. [ソース] セクションの [テーブルの作成元] リストで [Google Cloud Storage] を選択します。次に、以下の操作を行います。
   1. Cloud Storage バケットからファイルを選択するか、Cloud Storage URI を入力します。Google Cloud コンソールで複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
      Firestore エクスポート ファイルの URI の末尾は KIND_COLLECTION_ID.export_metadata にします。たとえば、default_namespace_kind_Book.export_metadata では、Book がコレクション ID、default_namespace_kind_Book が Firestore によって生成されたファイル名です。URI が KIND_COLLECTION_ID.export_metadata で終わっていない場合、次のエラー メッセージが表示されます。 does not contain valid backup metadata.(error code: invalid).
      注: 末尾が overall_export_metadata のファイルは使用しないでください。このファイルは BigQuery では使用できません。
      
   2. [ファイル形式] で [Cloud Datastore バックアップ] を選択します。Firestore と Datastore のエクスポート形式は同じです。
2. [宛先] セクションで、次の詳細を指定します。
   1. [データセット] で、テーブルを作成するデータセットを選択します。
   2. [テーブル] フィールドに、作成するテーブルの名前を入力します。
   3. [テーブルタイプ] フィールドが [ネイティブ テーブル] に設定されていることを確認します。
3. [スキーマ] セクションでは、何もする必要はありません。スキーマは Firestore のエクスポートから推定されます。
4. 省略可: [パーティションとクラスタの設定] を指定します。詳細については、パーティション分割テーブルの作成とクラスタ化テーブルの作成と使用をご覧ください。
5. [詳細オプション] をクリックして、次の操作を行います。
   • [書き込み設定] で、[空の場合に書き込む] を選択したままにします。これにより、新しいテーブルが作成され、データが読み込まれます。
   • テーブルのスキーマに存在しない行の値を無視する場合は、[不明な値] を選択します。
   • Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] クリックします。[Google が管理する暗号鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。
6. [テーブルを作成] をクリックします。

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 のリファレンス ドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

# 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 のエクスポート データを解析する方法を変更するには、次のオプションを指定します。

Google Cloud コンソールのオプション	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