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 のエクスポート サービスデータの読み込み
データは、Google Cloud コンソール、bq
コマンドライン ツール、または API を使用して Firestore のエクスポート メタデータ ファイルから読み込めます。
Google Cloud コンソールと bq
コマンドライン ツールで Datastore の用語が使用されることがありますが、次の手順は Firestore のエクスポート ファイルに対応しています。Firestore と Datastore のエクスポート形式は同じです。
コンソール
Google Cloud コンソールで [BigQuery] ページに移動します。
- [エクスプローラ] ペインでプロジェクトを展開し、データセットを選択します。
- [データセット情報] セクションで、 [テーブルを作成] をクリックします。
- [テーブルの作成] パネルで、次の詳細を指定します。
- [ソース] セクションの [テーブルの作成元] リストで [Google Cloud Storage] を選択します。次に、以下の操作を行います。
- Cloud Storage バケットからファイルを選択するか、Cloud Storage URI を入力します。Google Cloud Console で複数の 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
で終わっていない場合、次のエラー メッセージが表示されます。 not a valid backup metadata. (error code: invalid) - [ファイル形式] で [Cloud Datastore バックアップ] を選択します。Firestore と Datastore のエクスポート形式は同じです。
- Cloud Storage バケットからファイルを選択するか、Cloud Storage URI を入力します。Google Cloud Console で複数の 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 |