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 バケットからデータを読み込むために必要な権限を取得するには、バケットに対するストレージ管理者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 のエクスポート形式は同じです。

コンソール

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

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 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