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 を超えるフィールドはすべて切り捨てられます。

必要な権限

BigQuery にデータを読み込むには、読み込みジョブを実行する権限が必要です。また、新規または既存の BigQuery テーブルやパーティションへのデータの読み込みが可能な権限も必要です。Cloud Storage からデータを読み込む場合は、データを含むバケットに対するアクセス権限も必要です。

BigQuery の権限

BigQuery にデータを読み込むには、少なくとも以下の権限が必要です。これらの権限は、データを新しいテーブルまたはパーティションに読み込む場合や、テーブルまたはパーティションに対してデータの追加や上書きを行う場合に必要になります。

  • bigquery.tables.create
  • bigquery.tables.updateData
  • bigquery.jobs.create

bigquery.tables.create 権限および bigquery.tables.updateData 権限はいずれも、事前定義された以下の IAM ロールに含まれています。

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

次の事前定義済みの IAM ロールには bigquery.jobs.create 権限が含まれています。

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

また、bigquery.datasets.create 権限を持つユーザーがデータセットを作成すると、そのデータセットに対する bigquery.dataOwner アクセス権がユーザーに付与されます。bigquery.dataOwner アクセス権により、読み込みジョブを使用してデータセット内のテーブルを作成または更新できます。

BigQuery での IAM のロールと権限の詳細については、アクセス制御をご覧ください。

Cloud Storage の権限

Cloud Storage バケットからデータを読み込むには、storage.objects.get 権限が付与されている必要があります。URI のワイルドカードを使用する場合は storage.objects.list 権限も必要です。

事前定義の IAM ロール storage.objectViewer が付与されると、storage.objects.get 権限と storage.objects.list 権限が両方とも与えられます。

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

Datastore エクスポート メタデータ ファイルからデータを読み込むには、次のようにします。

コンソール

  1. Cloud Console で [BigQuery] ページを開きます。

    BigQuery ページに移動

  2. ナビゲーション パネルの [リソース] セクションで、Google Cloud プロジェクトを展開し、データセットを選択します。[テーブルを作成] をクリックします。データを読み込むプロセスは、空のテーブルを作成するプロセスと同じです。

    テーブルの作成

  3. [テーブルの作成] ページの [ソース] セクションで、次の操作を行います。

    • [テーブルの作成元] で [Cloud Storage] を選択します。
    • ソース フィールドに、Cloud Storage の URI を入力します。Cloud Storage バケットは、作成するテーブルを含むデータセットと同じロケーションに存在している必要があります。Datastore エクスポート ファイルの URI の末尾は [KIND_NAME].export_metadataexport[NUM].export_metadata にします。例: default_namespace_kind_Book.export_metadata。この例では、Book は種類名、default_namespace_kind_Book は Datastore によって生成されたファイル名です。
    • [ファイル形式] で [Datastore Backup] を選択します。
  4. [テーブルの作成] ページの [送信先] セクションで、次の操作を行います。

    • [データセット名] で、該当するデータセットを選択します。

      データセットの選択。

    • [テーブル名] フィールドに、BigQuery で作成するテーブルの名前を入力します。

    • [テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。

  5. [Schema] セクションでは、何もする必要はありません。スキーマは Datastore エクスポートから推定されます。

  6. [詳細オプション] セクションで該当する項目を選択し、[テーブルを作成] をクリックします。使用可能なオプションについては、Datastore のオプションをご覧ください。

従来の UI

  1. 従来の BigQuery ウェブ UI に移動します。
    BigQuery ウェブ UI に移動
  2. ナビゲーション パネルで、データセットにカーソルを合わせて下矢印アイコン 下矢印アイコン。 をクリックし、[Create new table] をクリックします。データを読み込むプロセスは、空のテーブルを作成するプロセスと同じです。
  3. [Create Table] ページの [Source Data] セクションで、次の操作を行います。
    • [Create from source] をオンのままにします。
    • [Location] で [Cloud Storage] を選択し、ソース フィールドに Cloud Storage URI を入力します。Cloud Storage バケットは、作成するテーブルを含むデータセットと同じロケーションに存在している必要があります。Datastore エクスポート ファイルの URI の末尾は [KIND_NAME].export_metadata にします。例: default_namespace_kind_Book.export_metadata。この例では、Book は種類名、default_namespace_kind_Book は Datastore によって生成されたファイル名です。

      [KIND_NAME] が Cloud Storage URI で指定されていることを確認します。[KIND_NAME] を含めずに URI を指定すると、does not contain valid backup metadata. (error code: invalid) というエラー メッセージが表示されます。

    • [File format] で [Datastore Backup] を選択します。
  4. [Create Table] ページの [Destination Table] セクションで、次の操作を行います。
    • [Table name] で適切なデータセットを選択し、BigQuery で作成するテーブルの名前をテーブル名のフィールドに入力します。
    • [Table type] が [Native table] に設定されていることを確認します。
  5. [Schema] セクションでは、何もする必要はありません。スキーマは Datastore エクスポートから推定されます。
  6. [Options] セクションで該当する項目を選択し、[Create Table] をクリックします。使用可能なオプションについては、Datastore のオプションをご覧ください。

bq

source_formatDATASTORE_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 という名前のテーブルに読み込みます。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 を使用して Datastore のエクスポート データを読み込むには、次のプロパティを設定します。

  1. Cloud Storage のソースデータを指し示す読み込みジョブを作成します。

  2. ジョブリソースjobReference セクションにある location プロパティでロケーションを指定します。

  3. ソース URI は、gs://[BUCKET]/[OBJECT] の形式で完全修飾する必要があります。ファイル(オブジェクト)名の末尾は、[KIND_NAME].export_metadata でなければなりません。Datastore エクスポートに使用できる URI は 1 つのみで、ワイルドカードは使用できません。

  4. configuration.load.sourceFormat プロパティを DATASTORE_BACKUP に設定して、データ形式を指定します。

Datastore 管理バックアップ

Datastore 管理バックアップ機能を使用して Datastore データをエクスポートする場合、ファイル拡張子は .export_metadata ではなく .backup_info になります。BigQuery にデータをインポートする場合は、Datastore 管理バックアップ サービスが使用できなくなるまで、.backup_info ファイルまたは .export_metadata ファイルを使用できます。

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 エクスポート データで上書きするには:

Console

  1. Cloud Console で [BigQuery] ページを開きます。 BigQuery ページに移動
  2. ナビゲーション パネルの [リソース] セクションで、Cloud プロジェクトを展開し、データセットを選択します。[テーブルを作成] をクリックします。データを読み込むプロセスは、空のテーブルを作成するプロセスと同じです。 テーブルの作成
  3. [テーブルの作成] ページの [ソース] セクションで、次の操作を行います。

    • [テーブルの作成元] で [Cloud Storage] を選択します。

    • ソース フィールドに、Cloud Storage の URI を入力します。Cloud Storage バケットは、作成するテーブルを含むデータセットと同じロケーションに存在している必要があります。Datastore エクスポート ファイルの URI の末尾は [KIND_NAME].export_metadata にします。例: default_namespace_kind_Book.export_metadata。この例では、Book は種類名、default_namespace_kind_Book は Datastore によって生成されたファイル名です。

      [KIND_NAME] が Cloud Storage URI で指定されていることを確認します。[KIND_NAME] を含めずに URI を指定すると、[does not contain valid backup metadata. (error code: invalid)] というエラー メッセージが表示されます。

    • [ファイル形式] で [Datastore Backup] を選択します。

  4. [テーブルの作成] ページの [送信先] セクションで、次の操作を行います。

    • [データセット名] で、該当するデータセットを選択します。

      データセットの選択。

    • [テーブル名] に、BigQuery で作成するテーブルの名前を入力します。

    • [テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。

  5. [Schema] セクションでは、何もする必要はありません。スキーマは Datastore エクスポートから推定されます。

  6. [詳細オプション] セクションの [書き込み設定] で [テーブルを上書きする] を選択します。

  7. [テーブルを作成] をクリックします。

従来の UI

  1. 従来の BigQuery ウェブ UI に移動します。
    BigQuery ウェブ UI に移動
  2. ナビゲーション パネルで、データセットにカーソルを合わせて下矢印アイコン 下矢印アイコン。 をクリックし、[Create new table] をクリックします。データを読み込むプロセスは、空のテーブルを作成するプロセスと同じです。
  3. [Create Table] ページの [Source Data] セクションで、次の操作を行います。
    • [Create from source] をオンのままにします。
    • [Location] で [Cloud Storage] を選択し、ソース フィールドに Cloud Storage URI を入力します。Cloud Storage バケットは、作成するテーブルを含むデータセットと同じロケーションに存在している必要があります。Datastore エクスポート ファイルの URI の末尾は [KIND_NAME].export_metadata にします。例: default_namespace_kind_Book.export_metadata。この例では、Book は種類名、default_namespace_kind_Book は Datastore によって生成されたファイル名です。

      [KIND_NAME] が Cloud Storage URI で指定されていることを確認します。[KIND_NAME] を含めずに URI を指定すると、[does not contain valid backup metadata. (error code: invalid)] というエラー メッセージが表示されます。

    • [File format] で [Datastore Backup] を選択します。
  4. [Create Table] ページの [Destination Table] セクションで、次の操作を行います。
    • [Table name] で適切なデータセットを選択し、テーブル名のフィールドでは、上書きするテーブルの名前を入力します。
    • [Table type] が [Native table] に設定されていることを確認します。
  5. [Schema] セクションでは、何もする必要はありません。スキーマは Datastore エクスポートから推定されます。
  6. [Options] セクションの [Write preference] で、[Overwrite table] を選択します。
  7. [Create Table] をクリックします。

bq

--replace フラグを指定して bq load コマンドを使用します。source_formatDATASTORE_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 からデータを読み込むには、次のプロパティを設定します。

  1. Cloud Storage のソースデータを指し示す読み込みジョブを作成します。

  2. ジョブリソースjobReference セクションにある location プロパティでロケーションを指定します。

  3. ソース URI は、gs://[BUCKET]/[OBJECT] の形式で完全修飾する必要があります。ファイル(オブジェクト)名の末尾は、[KIND_NAME].export_metadata でなければなりません。Datastore エクスポートに使用できる URI は 1 つのみで、ワイルドカードは使用できません。

  4. configuration.load.sourceFormat プロパティを DATASTORE_BACKUP に設定して、データ形式を指定します。

  5. configuration.load.writeDisposition プロパティを WRITE_TRUNCATE に設定して、書き込み処理を指定します。

Datastore のオプション

BigQuery による Datastore エクスポート データの解析方法を変更するには、従来のウェブ UI、bq コマンドライン ツール、または API で追加のオプションを指定します。

CSV のオプション 従来の UI のオプション 「bq」フラグ BigQuery API のプロパティ 説明
Projection フィールド なし --projection_fields projectionFields Datastore エクスポートから BigQuery に読み込むエンティティ プロパティを示すカンマ区切りリスト。プロパティ名では大文字と小文字が区別されます。最上位のプロパティでなければなりません。プロパティが指定されない場合、BigQuery はすべてのプロパティを読み込みます。指定されたプロパティが Datastore エクスポートに見つからない場合、ジョブ結果で無効なエラーが返されます。デフォルト値は '' です。
許可されている不良レコード数 許可されているエラー数 --max_bad_records maxBadRecords (オプション)BigQuery でジョブの実行時に無視できる不良レコードの最大数。不良レコードの数がこの値を超えると、ジョブ結果で「無効」エラーが返されます。デフォルト値は 0、つまりすべてのレコードが有効である必要があります。

データ型の変換

BigQuery は、Datastore エクスポート ファイル内の各エンティティのデータを BigQuery のデータ型に変換します。次の表に、変換前と変換後のデータ型を示します。

Datastore のデータ型 BigQuery のデータ型
Blob BYTES
Blobstore のキー STRING
ブール値 BOOLEAN
カテゴリ STRING
データストアのキー RECORD
日時 TIMESTAMP
メールアドレス STRING
埋め込みエンティティ RECORD
浮動小数点数 FLOAT
地理的座標

RECORD


[{"lat","DOUBLE"},
 {"long","DOUBLE"}]
        
IM ハンドル STRING
整数 INTEGER
リンク STRING
電話番号 STRING
住所 STRING
評価 INTEGER
短い blob BYTES
STRING STRING(64 KB で切り捨て)
ユーザー

RECORD


[{"email","STRING"}
 {"userid","STRING"}]
        

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