Datastore エクスポートからのデータの読み込み
BigQuery では、Datastore マネージド インポートおよびエクスポート サービスを使って作成された Datastore エクスポートからのデータを読み込むことができます。マネージド インポートおよびエクスポート サービスを使用すると、Datastore エンティティを Cloud Storage バケットにエクスポートできます。その後、エクスポートをテーブルとして BigQuery に読み込むことができます。
Datastore エクスポート ファイルの作成方法については、Datastore ドキュメントのエンティティのエクスポートとインポートをご覧ください。エクスポートのスケジューリングについては、エクスポートのスケジューリングをご覧ください。
API で projectionFields
プロパティを設定するか、bq コマンドライン ツールで --projection_fields
フラグを使用して、BigQuery が読み込むプロパティを制御できます。
読み込みプロセスをスキップしたい場合は、エクスポートを外部データソースとして設定することで、直接エクスポートに対してクエリを実行できます。詳細については、外部データソースをご覧ください。
Cloud Storage から BigQuery のテーブルにデータを読み込む場合について、テーブルを含むデータセットは Cloud Storage バケットと同じリージョンまたはマルチリージョンに存在している必要があります。
制限事項
Datastore エクスポートから BigQuery にデータを読み込む場合は、次の制限事項に注意してください。
- Datastore エクスポート ファイルを指定するときに、Cloud Storage URI でワイルドカードを使用することはできません。
- Datastore エクスポートからデータを読み込むときには、1 つの Cloud Storage URI のみを指定できます。
- 定義済みのスキーマを含む既存のテーブルに Datastore エクスポート データを追加することはできません。
- Datastore のエクスポートを正しく読み込むには、エクスポート データ内のエンティティが一貫したスキーマを共有し、固有のプロパティ名が 10,000 個未満でなければなりません。
- エンティティ フィルタを指定せずにエクスポートされたデータは、BigQuery に読み込むことができません。エクスポート リクエストでは、エンティティ フィルタに 1 種類以上の名前を含める必要があります。
- Datastore エクスポートの最大フィールド サイズは 64 KB です。Datastore エクスポートを読み込むときに、64 KB を超えるフィールドはすべて切り捨てられます。
始める前に
このドキュメントの各タスクを実行するために必要な権限をユーザーに与える 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)
カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。
Datastore のエクスポート サービスデータの読み込み
Datastore エクスポート メタデータ ファイルからデータを読み込むには、次のようにします。
コンソール
Google Cloud コンソールで [BigQuery] ページに移動します。
- [エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。
- [データセット情報] セクションで、[ テーブルを作成] をクリックします。
- [テーブルを作成] パネルで、次の詳細を指定します。
- [ソース] セクションの [テーブルの作成元] リストで [Google Cloud Storage] を選択します。次に、以下の操作を行います。
- Cloud Storage バケットからファイルを選択するか、Cloud Storage URI を入力します。Google Cloud コンソールで複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
Datastore エクスポート ファイルの URI の末尾はKIND_NAME.export_metadata
またはexport[NUM].export_metadata
であることが必要です。たとえば、default_namespace_kind_Book.export_metadata
では、Book
が種類名、default_namespace_kind_Book
が Datastore によって生成されたファイル名です。 - [ファイル形式] で [Cloud Datastore バックアップ] を選択します。
- Cloud Storage バケットからファイルを選択するか、Cloud Storage URI を入力します。Google Cloud コンソールで複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
- [送信先] セクションで、次の詳細を指定します。
- [データセット] で、テーブルを作成するデータセットを選択します。
- [テーブル] フィールドに、作成するテーブルの名前を入力します。
- [テーブルタイプ] フィールドが [ネイティブ テーブル] に設定されていることを確認します。
- [Schema] セクションでは、何もする必要はありません。スキーマは Datastore のエクスポートから推論されます。
- 省略可: [パーティションとクラスタの設定] を指定します。詳細については、パーティション分割テーブルの作成とクラスタ化テーブルの作成と使用をご覧ください。
- [詳細オプション] をクリックして、次の操作を行います。
- [書き込み設定] で、[空の場合に書き込む] を選択したままにします。これにより、新しいテーブルが作成され、データが読み込まれます。
- テーブルのスキーマに存在しない行の値を無視する場合は、[不明な値] を選択します。
- Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] クリックします。[Google が管理する暗号鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。 使用可能なオプションについては、Datastore のオプションをご覧ください。
- [テーブルを作成] をクリックします。
bq
source_format
を DATASTORE_BACKUP
に設定して、bq load
コマンドを使用します。--location
フラグを指定して、その値をロケーションに設定します。
bq --location=LOCATION load \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE
次のように置き換えます。
LOCATION
: ロケーション。--location
フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値をasia-northeast1
に設定します。.bigqueryrc ファイルを使用すると、ロケーションのデフォルト値を設定できます。FORMAT
:DATASTORE_BACKUP
DATASET
: データの読み込み先のテーブルを含むデータセット。TABLE
: データの読み込み先のテーブル。テーブルが存在しない場合は、新規に作成されます。PATH_TO_SOURCE
: Cloud Storage URI。
たとえば、次のコマンドは、gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata
Datastore エクスポート ファイルを 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 を使用して Datastore のエクスポート データを読み込むには、次のプロパティを設定します。
Cloud Storage のソースデータを指す読み込みジョブを作成します。
ソース URI は、gs://[BUCKET]/[OBJECT] の形式で完全修飾する必要があります。ファイル(オブジェクト)名の末尾は、
[KIND_NAME].export_metadata
でなければなりません。Datastore エクスポートに使用できる URI は 1 つのみで、ワイルドカードは使用できません。JobConfigurationLoad.sourceFormat
プロパティ をDATASTORE_BACKUP
に設定して、データ形式を指定します。
Datastore データをテーブルに追加または上書きする
Datastore エクスポート データを BigQuery に読み込むとき、新しいテーブルを作成してデータを保存することも、既存のテーブルを上書きすることもできます。既存のテーブルに Datastore エクスポート データを追加することはできません。
既存のテーブルに Datastore エクスポート データを追加しようとすると、次のエラーが発生します。Cannot append a datastore backup to a table
that already has a schema. Try using the WRITE_TRUNCATE write disposition to
replace the existing table
既存のテーブルを Datastore エクスポート データで上書きするには:
コンソール
Google Cloud コンソールで [BigQuery] ページに移動します。
- [エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。
- [データセット情報] セクションで、[ テーブルを作成] をクリックします。
- [テーブルを作成] パネルで、次の詳細を指定します。
- [ソース] セクションの [テーブルの作成元] リストで [Google Cloud Storage] を選択します。次に、以下の操作を行います。
- Cloud Storage バケットからファイルを選択するか、Cloud Storage URI を入力します。Google Cloud コンソールで複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
Datastore エクスポート ファイルの URI の末尾はKIND_NAME.export_metadata
またはexport[NUM].export_metadata
であることが必要です。たとえば、default_namespace_kind_Book.export_metadata
では、Book
が種類名、default_namespace_kind_Book
が Datastore によって生成されたファイル名です。 - [ファイル形式] で [Cloud Datastore バックアップ] を選択します。
- Cloud Storage バケットからファイルを選択するか、Cloud Storage URI を入力します。Google Cloud コンソールで複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
- [宛先] セクションで、次の詳細を指定します。
- [データセット] で、テーブルを作成するデータセットを選択します。
- [テーブル] フィールドに、作成するテーブルの名前を入力します。
- [テーブルタイプ] フィールドが [ネイティブ テーブル] に設定されていることを確認します。
- [Schema] セクションでは、何もする必要はありません。スキーマは Datastore のエクスポートから推論されます。
- 省略可: [パーティションとクラスタの設定] を指定します。詳細については、パーティション分割テーブルの作成とクラスタ化テーブルの作成と使用をご覧ください。追加や上書きではテーブルをパーティション分割テーブルまたはクラスタ化テーブルに変換できません。Google Cloud コンソールでは、読み込みジョブでパーティション分割テーブルやクラスタ化テーブルの追加または上書きを行うことはできません。
- [詳細オプション] をクリックして、次の操作を行います。
- [書き込み設定] で、[テーブルに追加する] または [テーブルを上書きする] を選択します。
- テーブルのスキーマに存在しない行の値を無視する場合は、[不明な値] を選択します。
- Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] クリックします。[Google が管理する暗号鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。 使用可能なオプションについては、Datastore のオプションをご覧ください。
- [テーブルを作成] をクリックします。
bq
--replace
フラグを指定して bq load
コマンドを使用します。source_format
は DATASTORE_BACKUP
に設定します。--location
フラグを指定して、その値をロケーションに設定します。
bq --location=LOCATION load \
--source_format=FORMAT \
--replace \
DATASET.TABLE \
PATH_TO_SOURCE
次のように置き換えます。
LOCATION
: ロケーション。--location
フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値をasia-northeast1
に設定します。.bigqueryrc ファイルを使用すると、ロケーションのデフォルト値を設定できます。FORMAT
:DATASTORE_BACKUP
DATASET
: データの読み込み先のテーブルを含むデータセット。TABLE
: 上書きするテーブル。PATH_TO_SOURCE
: Cloud Storage URI。
たとえば、次のコマンドは、gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata
Datastore エクスポート ファイルを読み込み、book_data
というテーブルを上書きします。
bq load --source_format=DATASTORE_BACKUP \
--replace \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata
API
API からデータを読み込むには、次のプロパティを設定します。
Cloud Storage のソースデータを指す読み込みジョブを作成します。
ソース URI は、gs://[BUCKET]/[OBJECT] の形式で完全修飾する必要があります。ファイル(オブジェクト)名の末尾は、
[KIND_NAME].export_metadata
でなければなりません。Datastore エクスポートに使用できる URI は 1 つのみで、ワイルドカードは使用できません。JobConfigurationLoad.sourceFormat
プロパティ をDATASTORE_BACKUP
に設定して、データ形式を指定します。JobConfigurationLoad.writeDisposition
プロパティをWRITE_TRUNCATE
に設定して、書き込み処理を指定します。
Datastore のオプション
BigQuery が Datastore のエクスポート データを解析する方法を変更するには、次のオプションを指定します。
コンソールのオプション | bq ツールフラグ | BigQuery API のプロパティ | 説明 |
---|---|---|---|
利用できません | --projection_fields |
projectionFields | Datastore エクスポートから BigQuery に読み込むエンティティ プロパティを示すカンマ区切りリスト。プロパティ名では大文字と小文字が区別されます。最上位のプロパティでなければなりません。プロパティが指定されない場合、BigQuery はすべてのプロパティを読み込みます。指定されたプロパティが Datastore エクスポートに見つからない場合、ジョブ結果で無効なエラーが返されます。デフォルト値は '' です。 |
データ型の変換
BigQuery は、Datastore エクスポート ファイル内の各エンティティのデータを BigQuery のデータ型に変換します。次の表に、変換前と変換後のデータ型を示します。
Datastore のデータ型 | BigQuery のデータ型 |
---|---|
配列 | ARRAY |
Blob | BYTES |
ブール値 | BOOLEAN |
日付と時刻 | TIMESTAMP |
埋め込みエンティティ | RECORD |
浮動小数点数 | FLOAT |
地理的座標 |
[{"lat","DOUBLE"}, {"long","DOUBLE"}] |
整数 | INTEGER |
キー | RECORD |
Null | STRING |
テキスト文字列 | STRING (64 KB で切り捨て) |
Datastore キーのプロパティ
Datastore の各エンティティには、名前空間やパスなどの情報を含む一意のキーが設定されています。次の表に示すように、BigQuery はキー用に RECORD
データ型を作成し、それぞれの情報をネストされたフィールドに入れます。
キーのプロパティ | 説明 | BigQuery のデータ型 |
---|---|---|
__key__.app |
Datastore アプリの名前。 | STRING |
__key__.id |
エンティティの ID、または null (__key__.name が設定されている場合)。 |
INTEGER |
__key__.kind |
エンティティの種類。 | STRING |
__key__.name |
エンティティの名前、または null (__key__.id が設定されている場合)。 |
STRING |
__key__.namespace |
Datastore アプリがカスタム名前空間を使用している場合は、エンティティの名前空間。それ以外の場合は、空白の文字列で表されるデフォルトの名前空間。 | STRING |
__key__.path |
種類と ID の連続したペアからなる、ルート エンティティからそのエンティティ自体へのフラット化されたエンティティの祖先パス例: "Country", "USA", "PostalCode",
10011, "Route", 1234 |
STRING |