Memuat data dari ekspor Firestore

BigQuery mendukung pemuatan data dari ekspor Firestore yang dibuat menggunakan layanan impor dan ekspor terkelola Firestore. Layanan impor dan ekspor terkelola mengekspor dokumen Firestore ke bucket Cloud Storage. Selanjutnya, Anda dapat memuat data yang diekspor ke tabel BigQuery.

Catatan: Tidak semua ekspor Firestore dapat dimuat. Lihat batasan BigQuery untuk membuat ekspor Firestore yang dapat dimuat ke dalam tabel BigQuery.

Batasan

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

• Set data Anda harus berada di lokasi yang sama dengan bucket Cloud Storage yang berisi file ekspor.
• Anda hanya dapat menentukan satu URI Cloud Storage dan tidak dapat menggunakan karakter pengganti URI.
• Agar ekspor Firestore dapat dimuat dengan benar, dokumen dalam data ekspor harus memiliki skema yang konsisten dengan kurang dari 10.000 nama kolom yang unik.
• Anda dapat membuat tabel baru untuk menyimpan data, atau menimpa tabel yang sudah ada. Anda tidak dapat menambahkan data ekspor Firestore ke tabel yang sudah ada.
• Perintah ekspor Anda harus menentukan filter collection-ids. Data yang diekspor tanpa menentukan filter ID koleksi tidak dapat dimuat ke BigQuery.

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 Firestore

Anda dapat memuat data dari file metadata ekspor Firestore menggunakan Google Cloud Console, alat command line bq, atau API.

Terkadang terminologi Datastore digunakan di Google Cloud Console dan alat command line bq, tetapi prosedur berikut kompatibel dengan file ekspor Firestore. Firestore dan Datastore berbagi format ekspor.

Catatan: Anda dapat memuat kolom tertentu menggunakan --projection_fields flag pada alat command line bq atau dengan menyetel properti projectionFields di load konfigurasi tugas.

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 Firestore Anda harus diakhiri dengan KIND_COLLECTION_ID.export_metadata. Misalnya, dalam default_namespace_kind_Book.export_metadata, Book adalah ID koleksi, dan default_namespace_kind_Book adalah nama file yang dihasilkan oleh Firestore. Jika URI tidak diakhiri dengan KIND_COLLECTION_ID.export_metadata, Anda akan menerima pesan error berikut: tidak berisi metadata cadangan yang valid. (kode error: tidak valid).
      Catatan: Jangan gunakan file yang diakhiri dengan overall_export_metadata. File ini tidak dapat digunakan oleh BigQuery.
      
   2. Untuk File format, pilih Cloud Datastore Backup. Firestore dan Datastore menggunakan format ekspor yang sama.
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 Firestore.
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.
6. Klik Buat tabel.

bq

Gunakan perintah bq load dengan source_format yang disetel ke DATASTORE_BACKUP. Berikan flag --location dan tetapkan nilai ke lokasi Anda. Jika Anda mengganti tabel yang sudah ada, tambahkan flag --replace.

Untuk memuat kolom tertentu saja, gunakan flag --projection_fields.

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

Ganti kode berikut:

• LOCATION: lokasi Anda. Flag --location bersifat opsional.
• FORMAT: DATASTORE_BACKUP. Pencadangan Datastore adalah opsi yang tepat untuk Firestore. Firestore dan Datastore menggunakan format ekspor yang sama.
• 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 Firestore 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 Firestore menggunakan API.

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

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

3. sourceUris harus sepenuhnya memenuhi syarat, dalam format gs://BUCKET/OBJECT di konfigurasi tugas pemuatan. Nama file (objek) harus diakhiri dengan KIND_NAME.export_metadata. Hanya satu URI yang diizinkan untuk ekspor Firestore, dan Anda tidak dapat menggunakan karakter pengganti.

4. Tentukan format data dengan menetapkan properti sourceFormat ke DATASTORE_BACKUP dalam konfigurasi tugas pemuatan. Pencadangan Datastore adalah opsi yang tepat untuk Firestore. Firestore dan Datastore menggunakan format ekspor yang sama.

5. Untuk memuat kolom tertentu saja, tetapkan properti projectionFields.

6. Jika Anda menimpa tabel yang sudah ada, tentukan disposisi tulis dengan menetapkan properti writeDisposition ke WRITE_TRUNCATE.

Python

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Python API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

# TODO(developer): Set table_id to the ID of the table to create.
table_id = "your-project.your_dataset.your_table_name"

# TODO(developer): Set uri to the path of the kind export metadata
uri = (
    "gs://cloud-samples-data/bigquery/us-states"
    "/2021-07-02T16:04:48_70344/all_namespaces/kind_us-states"
    "/all_namespaces_kind_us-states.export_metadata"
)

# TODO(developer): Set projection_fields to a list of document properties
#                  to import. Leave unset or set to `None` for all fields.
projection_fields = ["name", "post_abbr"]

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

job_config = bigquery.LoadJobConfig(
    source_format=bigquery.SourceFormat.DATASTORE_BACKUP,
    projection_fields=projection_fields,
)

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

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

Opsi Firestore

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

Opsi Konsol Google Cloud	Flag `bq`	Properti BigQuery API	Deskripsi
Tidak tersedia	--projection_fields	projectionFields (Java, Python)	(Opsional) Daftar yang dipisahkan koma yang menunjukkan kolom dokumen yang akan dimuat dari ekspor Firestore. Secara default, BigQuery memuat semua kolom. Nama kolom peka huruf besar/kecil dan harus ada dalam ekspor. Anda tidak dapat menentukan jalur kolom dalam kolom peta seperti map.foo.

Konversi jenis data

BigQuery mengonversi data dari setiap dokumen di file ekspor Firestore menjadi jenis data BigQuery. Tabel berikut menjelaskan konversi di antara jenis data yang didukung.

Jenis data Firestore	Jenis data BigQuery
Array	RECORD
Boolean	BOOLEAN
Referensi	RECORD
Tanggal dan waktu	TIMESTAMP
Peta	RECORD
Angka floating-point	FLOAT
Titik geografis	RECORD [{"lat","FLOAT"}, {"long","FLOAT"}]
Bilangan Bulat	INTEGER
String	STRING (dipotong menjadi 64 KB)

Properti kunci Firestore

Setiap dokumen di Firestore memiliki kunci unik yang berisi informasi seperti ID dokumen dan jalur dokumen. BigQuery membuat jenis data RECORD (disebut juga STRUCT ) untuk kunci, dengan kolom bertingkat untuk setiap bagian informasi, seperti yang dijelaskan dalam tabel berikut.

Properti kunci	Deskripsi	Jenis data BigQuery
__key__.app	Nama aplikasi Firestore.	STRING
__key__.id	ID dokumen, atau null jika __key__.name ditetapkan.	INTEGER
__key__.kind	ID koleksi dokumen.	STRING
__key__.name	Nama dokumen, atau null jika __key__.id ditetapkan.	STRING
__key__.namespace	Firestore tidak mendukung namespace kustom. Namespace default direpresentasikan oleh string kosong.	STRING
__key__.path	Jalur dokumen: urutan dokumen dan pasangan koleksi dari koleksi root. Misalnya: "Country", "USA", "PostalCode", 10011, "Route", 1234.	STRING