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.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 のエクスポート形式は同じです。
コンソール
Google Cloud コンソールで [BigQuery] ページに移動します。
- [エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。
- [データセット情報] セクションで、[ テーブルを作成] をクリックします。
- [テーブルを作成] パネルで、次の詳細を指定します。
- [ソース] セクションの [テーブルの作成元] リストで [Google Cloud Storage] を選択します。次に、以下の操作を行います。
- 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). - [ファイル形式] で [Cloud Datastore バックアップ] を選択します。Firestore と Datastore のエクスポート形式は同じです。
- Cloud Storage バケットからファイルを選択するか、Cloud Storage URI を入力します。Google Cloud コンソールで複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
- [宛先] セクションで、次の詳細を指定します。
- [データセット] で、テーブルを作成するデータセットを選択します。
- [テーブル] フィールドに、作成するテーブルの名前を入力します。
- [テーブルタイプ] フィールドが [ネイティブ テーブル] に設定されていることを確認します。
- [スキーマ] セクションでは、何もする必要はありません。スキーマは Firestore のエクスポートから推定されます。
- 省略可: [パーティションとクラスタの設定] を指定します。詳細については、パーティション分割テーブルの作成とクラスタ化テーブルの作成と使用をご覧ください。
- [詳細オプション] をクリックして、次の操作を行います。
- [書き込み設定] で、[空の場合に書き込む] を選択したままにします。これにより、新しいテーブルが作成され、データが読み込まれます。
- テーブルのスキーマに存在しない行の値を無視する場合は、[不明な値] を選択します。
- Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] クリックします。[Google が管理する暗号鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。
- [テーブルを作成] をクリックします。
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 のエクスポート データを読み込むには、次のプロパティを設定します。
Cloud Storage のソースデータを参照する
load
ジョブ構成を作成します。読み込みジョブの構成で
sourceUris
をgs://BUCKET/OBJECT
の形式で完全修飾する必要があります。ファイル(オブジェクト)名の末尾は、KIND_NAME.export_metadata
でなければなりません。Firestore のエクスポートに使用できる URI は 1 つのみです。URI にワイルドカードは使用できません。読み込みジョブの構成で
sourceFormat
プロパティをDATASTORE_BACKUP
に設定し、データ形式を指定します。Firestore の場合、適切なオプションは Datastore Backup です。Firestore と Datastore のエクスポート形式は同じです。特定のフィールドだけを読み込むには、
projectionFields
プロパティを設定します。既存のテーブルを上書きする場合は、
writeDisposition
プロパティをWRITE_TRUNCATE
に設定して、書き込み処理を指定します。
Python
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Python の設定手順を完了してください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
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 |