Halaman ini diterjemahkan oleh Cloud Translation API.

Mengekspor data ke Spanner (ETL terbalik)

Dokumen ini menjelaskan cara menyiapkan alur kerja ekstraksi, transformasi, dan pemuatan terbalik (ETL terbalik) dari BigQuery ke Spanner. Anda dapat melakukannya dengan menggunakan pernyataan EXPORT DATA untuk mengekspor data dari sumber data BigQuery, termasuk tabel Iceberg, ke tabel Spanner.

Alur kerja reverse ETL ini menggabungkan kemampuan analisis di BigQuery dengan latensi rendah dan throughput tinggi di Spanner. Alur kerja ini memungkinkan Anda menyajikan data kepada pengguna aplikasi tanpa menghabiskan kuota dan batas di BigQuery.

Sebelum memulai

Buat database Spanner termasuk tabel untuk menerima data yang diekspor.
Berikan peran Identity and Access Management (IAM) yang memberi pengguna izin yang diperlukan untuk melakukan setiap tugas dalam dokumen ini.
Buat pemesanan tingkat Enterprise atau yang lebih tinggi. Anda dapat mengurangi biaya komputasi BigQuery saat menjalankan ekspor satu kali ke Spanner dengan menetapkan kapasitas slot dasar nol dan mengaktifkan penskalaan otomatis.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan guna mengekspor data BigQuery ke Spanner, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda:

Mengekspor data dari tabel BigQuery: BigQuery Data Viewer (roles/bigquery.dataViewer)
Menjalankan tugas ekstraksi: BigQuery User (roles/bigquery.user)
Periksa parameter instance Spanner: Cloud Spanner Viewer (roles/spanner.viewer)
Menulis data ke tabel Spanner: Cloud Spanner Database User (roles/spanner.databaseUser)

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Batasan

Fitur ini tidak didukung di Assured Workloads.
Jenis data BigQuery berikut tidak memiliki padanan di Spanner dan tidak didukung:

Dialek database Spanner	Jenis BigQuery yang tidak didukung
Semua dialek	`STRUCT` `GEOGRAPHY` `DATETIME` `RANGE` `TIME`
GoogleSQL	`BIGNUMERIC`: Jenis `NUMERIC` yang didukung tidak cukup luas. Pertimbangkan untuk menambahkan transmisi eksplisit ke jenis `NUMERIC` dalam kueri.

Ukuran maksimum baris yang diekspor tidak boleh melebihi 1 MiB.
Spanner menerapkan integritas referensial selama ekspor. Jika tabel target adalah turunan dari tabel lain (INTERLEAVE IN PARENT), atau jika tabel target memiliki batasan kunci asing, kunci asing dan kunci induk akan divalidasi selama ekspor. Jika baris yang diekspor ditulis ke tabel dengan INTERLEAVE IN PARENT dan baris induk tidak ada, ekspor akan gagal dengan pesan "Baris induk tidak ada. Error "Baris tidak dapat ditulis". Jika baris yang diekspor ditulis ke tabel dengan batasan kunci asing dan mereferensikan kunci yang tidak ada, ekspor akan gagal dengan error "Foreign key constraint is violated". Saat mengekspor ke beberapa tabel, sebaiknya urutkan ekspor untuk memastikan integritas referensial akan dipertahankan selama ekspor. Hal ini biasanya berarti mengekspor tabel induk dan tabel yang direferensikan oleh kunci asing sebelum tabel yang mereferensikan tabel tersebut.

Jika tabel yang menjadi target ekspor memiliki batasan kunci asing, atau merupakan turunan dari tabel lain (INTERLEAVE IN PARENT), tabel induk harus diisi sebelum ekspor tabel turunan, dan harus berisi semua kunci yang sesuai. Upaya untuk mengekspor tabel turunan saat tabel induk tidak memiliki kumpulan lengkap kunci yang relevan akan gagal.
Tugas BigQuery, seperti tugas ekstrak ke Spanner, memiliki durasi maksimum 6 jam. Untuk mengetahui informasi tentang cara mengoptimalkan tugas ekstraksi besar, lihat Pengoptimalan ekspor. Sebagai alternatif, pertimbangkan untuk membagi input menjadi blok data individual, yang dapat diekspor sebagai tugas ekstraksi individual.
Ekspor ke Spanner hanya didukung untuk edisi BigQuery Enterprise atau Enterprise Plus. Edisi Standar BigQuery dan komputasi on-demand tidak didukung.
Anda tidak dapat menggunakan kueri berkelanjutan untuk mengekspor ke tabel Spanner dengan kunci utama yang dibuat otomatis.
Anda tidak dapat menggunakan kueri berkelanjutan untuk mengekspor ke tabel Spanner dalam database dialek PostgreSQL.
Saat menggunakan kueri berkelanjutan untuk mengekspor ke tabel Spanner, pastikan Anda memilih kunci utama yang tidak sesuai dengan bilangan bulat yang meningkat secara monoton di tabel BigQuery Anda. Melakukannya dapat menyebabkan masalah performa dalam ekspor Anda. Untuk mengetahui informasi tentang kunci utama di Spanner, dan cara memitigasi masalah performa ini, lihat Memilih kunci utama.

Mengonfigurasi ekspor dengan opsi `spanner_options`

Anda dapat menggunakan opsi spanner_options untuk menentukan tujuan database dan tabel Spanner. Konfigurasi dinyatakan dalam bentuk string JSON, seperti yang ditunjukkan contoh berikut:

EXPORT DATA OPTIONS(
   uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
  format='CLOUD_SPANNER',
   spanner_options = """{
      "table": "TABLE_NAME",
      "change_timestamp_column": "CHANGE_TIMESTAMP",
      "priority": "PRIORITY",
      "tag": "TAG",
   }"""
)

Ganti kode berikut:

PROJECT_ID: nama project Google Cloud Anda.
INSTANCE_ID: nama instance database Anda.
DATABASE_ID: nama database Anda.
TABLE_NAME: nama tabel tujuan yang ada.
CHANGE_TIMESTAMP: nama kolom jenis TIMESTAMP di tabel Spanner tujuan. Opsi ini digunakan selama ekspor untuk melacak stempel waktu pembaruan baris terbaru. Jika opsi ini ditentukan, ekspor akan terlebih dahulu membaca baris dalam tabel Spanner, untuk memastikan hanya update baris terbaru yang ditulis. Sebaiknya tentukan kolom jenis TIMESTAMP saat Anda menjalankan ekspor berkelanjutan, yang mengurutkan perubahan pada baris dengan kunci utama yang sama.
PRIORITY (opsional): prioritas permintaan penulisan. Nilai yang diizinkan: LOW, MEDIUM, HIGH. Nilai default: MEDIUM.
TAG (opsional): tag permintaan untuk membantu mengidentifikasi traffic pengekspor dalam pemantauan Spanner. Nilai default: bq_export.

Persyaratan kueri ekspor

Untuk mengekspor hasil kueri ke Spanner, hasilnya harus memenuhi persyaratan berikut:

Semua kolom dalam kumpulan hasil harus ada di tabel tujuan, dan jenisnya harus cocok atau dapat dikonversi.
Kumpulan hasil harus berisi semua kolom NOT NULL untuk tabel tujuan.
Nilai kolom tidak boleh melebihi batas ukuran data dalam tabel Spanner.
Jenis kolom apa pun yang tidak didukung harus dikonversi ke salah satu jenis yang didukung sebelum diekspor ke Spanner.

Konversi jenis

Agar mudah digunakan, pengekspor Spanner otomatis menerapkan konversi jenis berikut:

Jenis BigQuery	Jenis spanner
BIGNUMERIC	NUMERIC (khusus dialek PostgreSQL)
FLOAT64	FLOAT32
BYTES	PROTO
INT64	ENUM

Mengekspor data

Anda dapat menggunakan pernyataan EXPORT DATA untuk mengekspor data dari tabel BigQuery ke tabel Spanner.

Contoh berikut mengekspor kolom yang dipilih dari tabel bernama mydataset.table1:

EXPORT DATA OPTIONS (
  uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
  format='CLOUD_SPANNER',
  spanner_options="""{ "table": "TABLE_NAME" }"""
)
AS SELECT * FROM mydataset.table1;

Ganti kode berikut:

PROJECT_ID: nama Google Cloud project Anda
INSTANCE_ID: nama instance database Anda
DATABASE_ID: nama database Anda
TABLE_NAME: nama tabel tujuan yang ada

Ekspor beberapa hasil dengan nilai `rowkey` yang sama

Saat Anda mengekspor hasil yang berisi beberapa baris dengan nilai rowkey yang sama, nilai yang ditulis ke Spanner akan berada di baris Spanner yang sama. Hanya satu baris BigQuery yang cocok (tidak ada jaminan baris mana) yang akan ada di set baris Spanner yang dihasilkan oleh ekspor.

Mengekspor secara berkelanjutan

Untuk memproses kueri ekspor secara berkelanjutan, lihat Membuat kueri berkelanjutan untuk mengetahui petunjuk dan contoh kode.

Pengoptimalan ekspor

Untuk mengoptimalkan ekspor rekaman dari BigQuery ke Spanner, Anda dapat mencoba hal berikut:

Tingkatkan jumlah node di instance tujuan Spanner. Selama tahap awal pengeksporan, meningkatkan jumlah node dalam instance mungkin tidak langsung meningkatkan throughput ekspor. Mungkin ada sedikit penundaan saat Spanner melakukan pemisahan berbasis beban. Dengan pemisahan berbasis beban, throughput ekspor akan meningkat dan stabil. Menggunakan batch data pernyataan EXPORT DATA untuk mengoptimalkan penulisan ke Spanner. Untuk mengetahui informasi selengkapnya, lihat Ringkasan performa.
Tentukan prioritas HIGH dalam spanner_options. Jika instance Spanner Anda mengaktifkan penskalaan otomatis, menetapkan prioritas HIGH akan membantu memastikan pemanfaatan CPU mencapai nilai minimum yang diperlukan untuk memicu penskalaan. Hal ini memungkinkan penskala otomatis menambahkan resource komputasi sebagai respons terhadap beban ekspor, yang dapat meningkatkan throughput ekspor secara keseluruhan.

Perhatian: menggunakan prioritas HIGH dapat menyebabkan penurunan performa yang signifikan untuk workload lain yang ditayangkan oleh instance Spanner yang sama. Pertimbangkan untuk menggunakan prioritas HIGH hanya jika instance Spanner dikhususkan untuk ekspor ini, atau jika beban kerja lain tidak sensitif terhadap dampak performa.

Contoh berikut menunjukkan perintah ekspor Spanner yang ditetapkan ke prioritas HIGH:
```
EXPORT DATA OPTIONS (
  uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
  format='CLOUD_SPANNER',
  spanner_options="""{ "table": "TABLE_NAME", "priority": "HIGH" }"""
)
```
Hindari pengurutan hasil kueri. Jika set hasil berisi semua kolom kunci utama, pengekspor akan otomatis mengurutkan kunci utama tabel tujuan untuk menyederhanakan penulisan dan meminimalkan pertentangan.

Jika kunci utama tabel tujuan mencakup kolom yang dibuat, tambahkan ekspresi kolom yang dibuat ke kueri untuk memastikan data yang diekspor diurutkan dan dikelompokkan dengan benar.

Misalnya, dalam skema Spanner berikut, SaleYear dan SaleMonth adalah kolom yang dihasilkan yang membentuk awal kunci primer Spanner:
```
CREATE TABLE Sales (
  SaleId STRING(36) NOT NULL,
  ProductId INT64 NOT NULL,
  SaleTimestamp TIMESTAMP NOT NULL,
  Amount FLOAT64,
  -- Generated columns
  SaleYear INT64 AS (EXTRACT(YEAR FROM SaleTimestamp)) STORED,
  SaleMonth INT64 AS (EXTRACT(MONTH FROM SaleTimestamp)) STORED,
) PRIMARY KEY (SaleYear, SaleMonth, SaleId);
```
Saat Anda mengekspor data dari BigQuery ke tabel Spanner dengan kolom yang dihasilkan yang digunakan dalam kunci utama, sebaiknya, tetapi tidak wajib, untuk menyertakan ekspresi untuk kolom yang dihasilkan ini dalam kueri EXPORT DATA Anda. Hal ini memungkinkan BigQuery mengurutkan data dengan benar sebelumnya, yang sangat penting untuk pengelompokan dan penulisan yang efisien ke Spanner. Nilai untuk kolom yang dihasilkan dalam pernyataan EXPORT DATA tidak di-commit di Spanner, karena nilai tersebut dibuat secara otomatis oleh Spanner, tetapi digunakan untuk mengoptimalkan ekspor.

Contoh berikut mengekspor data ke tabel Sales Spanner yang kunci utamanya menggunakan kolom yang dihasilkan. Untuk mengoptimalkan performa penulisan, kueri menyertakan ekspresi EXTRACT yang cocok dengan kolom SaleYear dan SaleMonth yang dihasilkan, sehingga BigQuery dapat mengurutkan data terlebih dahulu sebelum diekspor:
```
EXPORT DATA OPTIONS (
  uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
  format='CLOUD_SPANNER',
  spanner_options="""{ "table": "Sales" }"""
)
AS SELECT
  s.SaleId,
  s.ProductId,
  s.SaleTimestamp,
  s.Amount,
  -- Add expressions that match the generated columns in the Spanner PK
  EXTRACT(YEAR FROM s.SaleTimestamp) AS SaleYear,
  EXTRACT(MONTH FROM s.SaleTimestamp) AS SaleMonth
FROM my_dataset.sales_export AS s;
```

Untuk mencegah tugas yang berjalan lama, ekspor data menurut partisi. Memecah data BigQuery menggunakan kunci partisi, seperti stempel waktu dalam kueri Anda:

EXPORT DATA OPTIONS (
  uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
  format='CLOUD_SPANNER',
  spanner_options="""{ "table": "TABLE_NAME", "priority": "MEDIUM" }"""
)
AS SELECT *
FROM 'mydataset.table1' d
WHERE
d.timestamp >= TIMESTAMP '2025-08-28T00:00:00Z' AND
d.timestamp < TIMESTAMP '2025-08-29T00:00:00Z';

Hal ini memungkinkan kueri selesai dalam runtime tugas 6 jam. Untuk mengetahui informasi selengkapnya tentang batas ini, lihat batas tugas kueri.

Untuk meningkatkan performa pemuatan data, hapus indeks di tabel Spanner tempat data diimpor. Kemudian, buat ulang setelah impor selesai.
Sebaiknya mulai dengan satu node Spanner (1.000 unit pemrosesan) dan reservasi slot BigQuery minimal. Misalnya, 100 slot, atau 0 slot dasar pengukuran dengan penskalaan otomatis. Untuk ekspor di bawah 100 GB, konfigurasi ini biasanya selesai dalam batas tugas 6 jam. Untuk ekspor yang lebih besar dari 100 GB, tingkatkan throughput dengan menskalakan node Spanner dan reservasi slot BigQuery sesuai kebutuhan. Throughput diskalakan sekitar 5 MiB/dtk per node.

Harga

Saat mengekspor data ke Spanner menggunakan pernyataan EXPORT DATA, Anda akan ditagih menggunakan harga komputasi kapasitas BigQuery.

Untuk mengekspor secara berkelanjutan ke Spanner menggunakan kueri berkelanjutan, Anda harus memiliki reservasi slot edisi BigQuery Enterprise atau Enterprise Plus dan penetapan reservasi yang menggunakan jenis tugas CONTINUOUS.

Ekspor BigQuery ke Spanner yang melintasi batas regional dikenai biaya menggunakan tarif ekstraksi data. Untuk informasi lebih lanjut, lihat Harga BigQuery. Untuk menghindari biaya transfer data, pastikan ekspor BigQuery Anda berjalan di region yang sama dengan pemimpin default Spanner. Ekspor kueri berkelanjutan tidak mendukung ekspor yang melintasi batas regional.

Setelah data diekspor, Anda dikenai biaya penyimpanan data di Spanner. Untuk mengetahui informasi selengkapnya, lihat Harga Spanner.