Memuat data dari ekspor Datastore

BigQuery mendukung pemuatan data dari ekspor Datastore yang dibuat menggunakan layanan impor dan ekspor yang dikelola Datastore. Anda dapat menggunakan layanan impor dan ekspor terkelola untuk mengekspor entity Datastore ke bucket Cloud Storage. Anda kemudian dapat memuat ekspor ke BigQuery sebagai tabel.

Untuk mempelajari cara membuat file ekspor Datastore, lihat Mengekspor dan mengimpor entity dalam dokumentasi Datastore. Untuk informasi tentang penjadwalan ekspor, lihat Menjadwalkan ekspor.

Anda dapat mengontrol properti mana yang harus dimuat BigQuery dengan menetapkan properti projectionFields di API atau dengan menggunakan flag --projection_fields di alat command line bq.

Jika memilih untuk melewati proses pemuatan, Anda dapat membuat kueri ekspor secara langsung dengan menyiapkannya sebagai sumber data eksternal. Untuk informasi selengkapnya, lihat Sumber data eksternal.

Saat Anda memuat data dari Cloud Storage ke tabel BigQuery, set data yang berisi tabel harus berada di region atau multi-region yang sama dengan bucket Cloud Storage.

Batasan

Saat memuat data ke BigQuery dari ekspor Datastore, perhatikan batasan berikut:

  • Anda tidak dapat menggunakan karakter pengganti di Cloud Storage URI saat menentukan file ekspor Datastore.
  • Anda hanya dapat menentukan satu Cloud Storage URI saat memuat data dari ekspor Datastore.
  • Anda tidak dapat menambahkan data ekspor Datastore ke tabel yang ada dengan skema yang ditentukan.
  • Agar ekspor Datastore dapat dimuat dengan benar, entity dalam data ekspor harus memiliki skema yang konsisten dengan kurang dari 10.000 nama properti yang unik.
  • Data yang diekspor tanpa menentukan filter entity tidak dapat dimuat ke BigQuery. Permintaan ekspor harus menyertakan satu atau beberapa nama jenis dalam filter entity.
  • Ukuran kolom maksimum untuk ekspor Datastore adalah 64 KB. Saat Anda memuat ekspor Datastore, kolom yang berukuran lebih dari 64 KB akan terpotong.

Sebelum memulai

Berikan peran Identity and Access Management (IAM) yang memberi pengguna izin yang diperlukan untuk melakukan setiap tugas dalam dokumen ini.

Izin yang diperlukan

Untuk memuat data ke BigQuery, Anda memerlukan izin IAM untuk menjalankan tugas pemuatan dan memuat data ke dalam tabel dan partisi BigQuery. Jika memuat data dari Cloud Storage, Anda juga memerlukan izin IAM untuk mengakses bucket yang berisi data Anda.

Izin untuk memuat data ke BigQuery

Untuk memuat data ke dalam tabel atau partisi BigQuery baru, atau menambahkan atau menimpa tabel atau partisi yang sudah ada, Anda memerlukan izin IAM berikut:

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

Setiap peran IAM yang telah ditetapkan berikut mencakup izin yang diperlukan untuk memuat data ke dalam tabel atau partisi BigQuery:

  • roles/bigquery.dataEditor
  • roles/bigquery.dataOwner
  • roles/bigquery.admin (termasuk izin bigquery.jobs.create)
  • bigquery.user (termasuk izin bigquery.jobs.create)
  • bigquery.jobUser (termasuk izin bigquery.jobs.create)

Selain itu, jika memiliki izin bigquery.datasets.create, Anda dapat membuat dan memperbarui tabel menggunakan tugas pemuatan dalam set data yang Anda buat.

Untuk mengetahui informasi selengkapnya tentang peran dan izin IAM di BigQuery, lihat Peran dan izin yang telah ditetapkan.

Izin untuk memuat data dari Cloud Storage

Untuk mendapatkan izin yang Anda perlukan untuk memuat data dari bucket Cloud Storage, minta administrator untuk memberi Anda peran IAM Storage Admin (roles/storage.admin) di bucket. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran yang telah ditentukan ini berisi izin yang diperlukan untuk memuat data dari bucket Cloud Storage. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk memuat data dari bucket Cloud Storage:

  • storage.buckets.get
  • storage.objects.get
  • storage.objects.list (required if you are using a URI wildcard)

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Memuat data layanan ekspor Datastore

Untuk memuat data dari file metadata ekspor Datastore:

Konsol

  1. Di konsol Google Cloud, buka halaman BigQuery.

    Buka BigQuery

  2. Di panel Explorer, luaskan project Anda, lalu pilih set data.
  3. Di bagian Dataset info, klik Create table.
  4. Di panel Create table, tentukan detail berikut:
    1. Di bagian Source, pilih Google Cloud Storage dalam daftar Create table from. Kemudian, lakukan hal berikut:
      1. Pilih file dari bucket Cloud Storage, atau masukkan Cloud Storage URI. Anda tidak dapat menyertakan beberapa URI di Konsol Google Cloud, tetapi karakter pengganti bisa didukung. Bucket Cloud Storage harus berada di lokasi yang sama dengan set data yang berisi tabel yang ingin Anda buat, tambahkan, atau timpa.
        URI untuk file ekspor Datastore Anda harus diakhiri dengan KIND_NAME.export_metadata atau export[NUM].export_metadata. Misalnya, dalam default_namespace_kind_Book.export_metadata, Book adalah nama jenis, dan default_namespace_kind_Book adalah nama file yang dihasilkan oleh Datastore. pilih file sumber untuk membuat tabel BigQuery
      2. Untuk File format, pilih Cloud Datastore Backup.
    2. Di bagian Destination, tentukan detail berikut:
      1. Untuk Dataset, pilih set data tempat Anda ingin membuat tabel.
      2. Di kolom Table, masukkan nama tabel yang ingin Anda buat.
      3. Pastikan kolom Table type disetel ke Native table.
    3. Di bagian Schema, Anda tidak perlu melakukan tindakan apa pun. Skema diinferensikan untuk ekspor Datastore.
    4. Opsional: Tentukan Partition and cluster settings. Untuk mengetahui informasi selengkapnya, lihat Membuat tabel berpartisi serta Membuat dan menggunakan tabel yang dikelompokkan.
    5. Klik Advanced options, lalu lakukan tindakan berikut:
      • Untuk Write preference, biarkan Write if empty dipilih. Opsi ini akan membuat tabel baru dan memuat data Anda ke dalamnya.
      • Jika Anda ingin mengabaikan nilai dalam baris yang tidak ada dalam skema tabel, pilih Unknown values.
      • Untuk Encryption, klik Customer-managed key untuk menggunakan kunci Cloud Key Management Service. Jika Anda membiarkan setelan Google-managed key, BigQuery akan mengenkripsi data dalam penyimpanan.
        • Untuk mengetahui informasi tentang opsi yang tersedia, lihat Opsi Datastore.
    6. Klik Buat tabel.

bq

Gunakan perintah bq load dengan source_format ditetapkan ke DATASTORE_BACKUP. Berikan flag --location dan tetapkan nilai ke location Anda.

bq --location=LOCATION load \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

Ganti kode berikut:

  • LOCATION: lokasi Anda. Flag --location bersifat opsional. Misalnya, jika menggunakan BigQuery di wilayah Tokyo, Anda dapat menetapkan nilai flag ke asia-northeast1. Anda dapat menetapkan nilai default untuk lokasi menggunakan file.bigqueryrc.
  • FORMAT: DATASTORE_BACKUP.
  • DATASET: set data yang berisi tabel tempat Anda memuat data.
  • TABLE: tabel tempat Anda memuat data. Jika tidak ada, tabel akan dibuat.
  • PATH_TO_SOURCE: Cloud Storage URI.

Misalnya, perintah berikut memuat file ekspor Datastore gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata ke tabel bernama book_data. mybucket dan mydataset dibuat di lokasi multi-region 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

Tetapkan properti berikut untuk memuat data ekspor Datastore menggunakan API.

  1. Buat tugas pemuatan yang mengarah ke data sumber di Cloud Storage.

  2. Tentukan lokasi Anda di properti location di bagian jobReference pada resource tugas.

  3. URI sumber harus sepenuhnya memenuhi syarat, dalam format gs://[BUCKET]/[OBJECT]. Nama file (objek) harus diakhiri dengan [KIND_NAME].export_metadata. Hanya satu URI yang diizinkan untuk ekspor Datastore, dan Anda tidak dapat menggunakan karakter pengganti.

  4. Tentukan format data dengan menetapkan properti JobConfigurationLoad.sourceFormat ke DATASTORE_BACKUP.

Menambah atau menimpa tabel dengan data Datastore

Saat memuat data ekspor Datastore ke BigQuery, Anda Anda dapat membuat tabel baru untuk menyimpan data, atau menimpa tabel yang sudah ada. Anda tidak dapat menambahkan data ekspor Datastore ke tabel yang ada.

Jika Anda mencoba menambahkan data ekspor Datastore ke tabel yang ada, error berikut akan muncul: 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.

Untuk menimpa tabel yang ada dengan data ekspor Datastore:

Konsol

  1. Di konsol Google Cloud, buka halaman BigQuery.

    Buka BigQuery

  2. Di panel Explorer, luaskan project Anda, lalu pilih set data.
  3. Di bagian Dataset info, klik Create table.
  4. Di panel Create table, tentukan detail berikut:
    1. Di bagian Source, pilih Google Cloud Storage dalam daftar Create table from. Kemudian, lakukan hal berikut:
      1. Pilih file dari bucket Cloud Storage, atau masukkan Cloud Storage URI. Anda tidak dapat menyertakan beberapa URI di Konsol Google Cloud, tetapi karakter pengganti bisa didukung. Bucket Cloud Storage harus berada di lokasi yang sama dengan set data yang berisi tabel yang ingin Anda buat, tambahkan, atau timpa.
        URI untuk file ekspor Datastore Anda harus diakhiri dengan KIND_NAME.export_metadata atau export[NUM].export_metadata. Misalnya, dalam default_namespace_kind_Book.export_metadata, Book adalah nama jenis, dan default_namespace_kind_Book adalah nama file yang dihasilkan oleh Datastore. pilih file sumber untuk membuat tabel BigQuery
      2. Untuk File format, pilih Cloud Datastore Backup.
    2. Di bagian Destination, tentukan detail berikut:
      1. Untuk Dataset, pilih set data tempat Anda ingin membuat tabel.
      2. Di kolom Table, masukkan nama tabel yang ingin Anda buat.
      3. Pastikan kolom Table type disetel ke Native table.
    3. Di bagian Schema, Anda tidak perlu melakukan tindakan apa pun. Skema diinferensikan untuk ekspor Datastore.
    4. Opsional: Tentukan Partition and cluster settings. Untuk mengetahui informasi selengkapnya, lihat Membuat tabel berpartisi serta Membuat dan menggunakan tabel yang dikelompokkan. Anda tidak dapat mengonversi tabel menjadi tabel berpartisi atau tabel yang dikelompokkan dengan menambahkan atau menimpanya. Konsol Google Cloud tidak mendukung penambahan ke atau penimpaan tabel berpartisi atau tabel yang dikelompokkan dalam tugas pemuatan.
    5. Klik Advanced options, lalu lakukan tindakan berikut:
      • Untuk Write preference, pilih Append to table atau Overwrite table.
      • Jika Anda ingin mengabaikan nilai dalam baris yang tidak ada dalam skema tabel, pilih Unknown values.
      • Untuk Encryption, klik Customer-managed key untuk menggunakan kunci Cloud Key Management Service. Jika Anda membiarkan setelan Google-managed key, BigQuery akan mengenkripsi data dalam penyimpanan.
        • Untuk mengetahui informasi tentang opsi yang tersedia, lihat Opsi Datastore.
    6. Klik Buat tabel.

bq

Gunakan perintah bq load dengan flag --replace dan dengan source_format ditetapkan ke DATASTORE_BACKUP. Berikan flag --location dan tetapkan nilainya menjadi lokasi Anda.

bq --location=LOCATION load \
--source_format=FORMAT \
--replace \
DATASET.TABLE \
PATH_TO_SOURCE

Ganti kode berikut:

  • LOCATION: lokasi Anda. Flag --location bersifat opsional. Misalnya, jika menggunakan BigQuery di wilayah Tokyo, Anda dapat menetapkan nilai flag ke asia-northeast1. Anda dapat menetapkan nilai default untuk lokasi menggunakan file.bigqueryrc.
  • FORMAT: DATASTORE_BACKUP.
  • DATASET: set data yang berisi tabel tempat Anda memuat data.
  • TABLE: tabel yang Anda timpa.
  • PATH_TO_SOURCE: Cloud Storage URI.

Misalnya, perintah berikut memuat file ekspor Datastore gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata dan menimpa tabel bernama 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

Tetapkan properti berikut untuk memuat data dari API.

  1. Buat tugas pemuatan yang mengarah ke data sumber di Cloud Storage.

  2. Tentukan lokasi Anda di properti location di bagian jobReference pada resource tugas.

  3. URI sumber harus sepenuhnya memenuhi syarat, dalam format gs://[BUCKET]/[OBJECT]. Nama file (objek) harus diakhiri dengan [KIND_NAME].export_metadata. Hanya satu URI yang diizinkan untuk ekspor Datastore, dan Anda tidak dapat menggunakan karakter pengganti.

  4. Tentukan format data dengan menetapkan properti JobConfigurationLoad.sourceFormat ke DATASTORE_BACKUP.

  5. Tentukan disposisi tulis dengan menetapkan properti JobConfigurationLoad.writeDisposition ke WRITE_TRUNCATE.

Opsi Datastore

Untuk mengubah cara BigQuery mengurai data ekspor Datastore, tentukan opsi berikut:

Opsi konsol flag alat bq Properti BigQuery API Deskripsi
Tidak tersedia --projection_fields projectionFields Daftar yang dipisahkan koma yang menunjukkan properti entity yang akan dimuat ke BigQuery dari ekspor Datastore. Nama properti peka huruf besar/kecil dan harus berupa properti tingkat teratas. Jika tidak ada properti yang ditentukan, BigQuery akan memuat semua properti. Jika properti bernama tidak ditemukan dalam ekspor Datastore, error tidak valid akan ditampilkan dalam hasil tugas. Nilai defaultnya adalah ''.

Konversi jenis data

BigQuery mengonversi data dari setiap entity di file ekspor Datastore menjadi jenis data BigQuery. Tabel berikut menjelaskan konversi di antara jenis data.

Jenis data Datastore Jenis data BigQuery
Array ARRAY
Blob BYTES
Boolean BOOLEAN
Tanggal dan waktu TIMESTAMP
Entity tersemat RECORD
Angka floating-point FLOAT
Titik geografis

RECORD

[{"lat","DOUBLE"},
 {"long","DOUBLE"}]
Bilangan Bulat INTEGER
Kunci RECORD
Null STRING
String teks STRING (dipotong menjadi 64 KB)

Properti kunci Datastore

Setiap entity dalam Datastore memiliki kunci unik yang berisi informasi seperti namespace dan jalur. BigQuery membuat jenis data RECORD untuk kunci tersebut, dengan kolom bertingkat untuk setiap bagian informasi, seperti yang dijelaskan dalam tabel berikut.

Properti kunci Deskripsi Jenis data BigQuery
__key__.app Nama aplikasi Datastore. STRING
__key__.id ID entity, atau null jika __key__.name ditetapkan. INTEGER
__key__.kind Jenis entity. STRING
__key__.name Nama entity, atau null jika __key__.id ditetapkan. STRING
__key__.namespace Jika aplikasi Datastore menggunakan namespace kustom, namespace entity tersebut. Selain itu, namespace default direpresentasikan oleh string kosong. STRING
__key__.path Jalur ancestral entity, yang diratakan, yang terdiri dari urutan pasangan jenis-ID dari root entity ke entity itu sendiri. Contoh: "Country", "USA", "PostalCode", 10011, "Route", 1234. STRING