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.adminbigquery.jobs.create 権限を含む)
  • bigquery.userbigquery.jobs.create 権限を含む)
  • bigquery.jobUserbigquery.jobs.create 権限を含む)

また、bigquery.datasets.create 権限がある場合は、作成するデータセットで読み込みジョブを使用してテーブルの作成と更新を行えます。

BigQuery での IAM のロールと権限については、事前定義ロールと権限をご覧ください。

Cloud Storage からデータを読み込む権限

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

IAM 事前定義ロール roles/storage.objectViewer には、Cloud Storage バケットからデータを読み込むために必要なすべての権限が含まれています。

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

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

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

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 で生成されたファイルの名前です。

      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_formatDATASTORE_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 という名前のテーブルに読み込みます。mybucketmydatasetUS マルチリージョン ロケーションに作成されています。

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. 読み込みジョブの構成で sourceUrisgs://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 のリファレンス ドキュメントをご覧ください。

# 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 projectionFieldsJavaPython (省略可)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