Praktik terbaik Storage Write API BigQuery

Dokumen ini memberikan praktik terbaik untuk menggunakan Storage Write API BigQuery. Sebelum membaca dokumen ini, baca Ringkasan BigQuery Storage Write API.

Membatasi kecepatan pembuatan streaming

Sebelum membuat streaming, pertimbangkan apakah Anda dapat menggunakan streaming default. Untuk skenario streaming, streaming default memiliki lebih sedikit batasan kuota dan dapat diskalakan dengan lebih baik daripada menggunakan streaming yang dibuat aplikasi. Jika Anda menggunakan streaming yang dibuat oleh aplikasi, pastikan untuk memanfaatkan throughput maksimum di setiap streaming sebelum membuat streaming tambahan. Misalnya, gunakan penulisan asinkron.

Untuk stream yang dibuat aplikasi, hindari memanggil CreateWriteStream dengan frekuensi tinggi. Umumnya, jika Anda melebihi 40-50 panggilan per detik, latensi panggilan API akan meningkat secara signifikan (>25 dtk). Pastikan aplikasi Anda dapat menerima cold start dan meningkatkan jumlah aliran secara bertahap, serta batasi frekuensi panggilan CreateWriteStream. Anda juga dapat menetapkan batas waktu yang lebih besar untuk menunggu panggilan selesai agar tidak gagal dengan error DeadlineExceeded. Ada juga kuota jangka panjang yang lebih panjang pada tarif maksimum panggilan CreateWriteStream. Membuat streaming adalah proses yang memerlukan resource. Jadi, mengurangi frekuensi pembuatan streaming dan memanfaatkan streaming yang sudah ada adalah cara terbaik agar tidak melampaui batas ini.

Pengelolaan kumpulan koneksi

Metode AppendRows membuat koneksi dua arah ke aliran data. Anda dapat membuka beberapa koneksi pada aliran data default, tetapi hanya satu koneksi aktif pada aliran data yang dibuat oleh aplikasi.

Saat menggunakan aliran data default, Anda dapat menggunakan multiplexing Storage Write API untuk menulis ke beberapa tabel tujuan dengan koneksi bersama. Koneksi kumpulan multiplexing untuk throughput dan pemanfaatan resource yang lebih baik. Jika alur kerja Anda memiliki lebih dari 20 koneksi serentak, sebaiknya gunakan multiplexing. Multiplexing tersedia di Java dan Go. Untuk mengetahui detail penerapan Java, lihat Menggunakan multiplexing. Untuk mengetahui detail penerapan Go, lihat Berbagi Koneksi (Multiplexing).

Untuk mendapatkan performa terbaik, gunakan satu koneksi untuk sebanyak mungkin penulisan data. Jangan gunakan satu koneksi hanya untuk satu penulisan, atau buka dan tutup aliran data untuk banyak operasi tulis kecil.

Ada kuota pada jumlah koneksi serentak yang dapat dibuka pada waktu yang sama per project. Di atas batas, panggilan ke AppendRows akan gagal. Namun, kuota untuk koneksi serentak dapat ditingkatkan dan seharusnya tidak menjadi faktor pembatas untuk penskalaan.

Setiap panggilan ke AppendRows membuat objek penulis data baru. Jadi, saat menggunakan aliran data yang dibuat aplikasi, jumlah koneksi sesua dengan jumlah aliran yang telah dibuat. Umumnya, satu koneksi mendukung throughput setidaknya 1 MBps. Batas atas bergantung pada beberapa faktor, seperti bandwidth jaringan, skema data, dan beban server, tetapi dapat melebihi 10 MBps.

Kuota juga berlaku pada total throughput per project. Informasi ini menyatakan byte per detik di semua koneksi yang mengalir melalui layanan Storage Write API. Jika project melebihi kuota ini, Anda dapat meminta batas kuota yang lebih tinggi. Biasanya ini melibatkan penambahan kuota yang menyertainya, seperti kuota koneksi serentak, dalam rasio yang sama.

Mengelola offset streaming untuk mencapai semantik tepat satu kali

Storage Write API hanya mengizinkan penulisan ke akhir aliran data saat ini, yang bergerak saat data ditambahkan. Posisi saat ini dalam aliran data ditentukan sebagai offset dari awal aliran data.

Saat menulis ke aliran data yang dibuat aplikasi, Anda dapat menentukan offset streaming untuk mencapai semantik penulisan tepat satu kali.

Saat Anda menentukan offset, operasi tulis bersifat idempoten, sehingga aman untuk mencoba lagi karena error jaringan atau server tidak responsif. Tangani error berikut yang terkait dengan offset:

  • ALREADY_EXISTS (StorageErrorCode.OFFSET_ALREADY_EXISTS): Baris sudah ditulis. Anda dapat mengabaikan error ini dengan aman.
  • OUT_OF_RANGE (StorageErrorCode.OFFSET_OUT_OF_RANGE): Operasi tulis sebelumnya gagal. Coba lagi dari penulisan terakhir yang berhasil.

Perlu diperhatikan bahwa error ini juga dapat terjadi jika Anda menetapkan nilai offset yang salah, sehingga Anda harus mengelola offset dengan hati-hati.

Sebelum menggunakan offset aliran, pertimbangkan apakah Anda memerlukan semantik tepat satu kali atau tidak. Misalnya, jika pipeline data upstream Anda hanya menjamin penulisan setidaknya satu kali, atau jika Anda dapat mendeteksi duplikat dengan mudah setelah penyerapan data, Anda mungkin tidak memerlukan penulisan yang tepat satu kali. Dalam hal ini, sebaiknya gunakan aliran data default, yang tidak perlu melacak offset baris.

Jangan blokir pada panggilan AppendRows.

Metode AppendRows bersifat asinkron. Anda dapat mengirim serangkaian operasi tulis tanpa memblokir respons untuk setiap penulisan satu per satu. Pesan respons pada koneksi dua arah akan diterima dengan urutan yang sama saat permintaan diantrekan. Untuk throughput tertinggi, panggil AppendRows tanpa pemblokiran untuk menunggu respons.

Menangani pembaruan skema

Untuk skenario streaming data, skema tabel biasanya dikelola di luar pipeline streaming. Skema biasanya terus berubah dari waktu ke waktu, misalnya dengan menambahkan kolom nullable baru. Pipeline yang andal harus menangani pembaruan skema out-of-band.

Storage Write API mendukung skema tabel sebagai berikut:

  • Permintaan tulis pertama menyertakan skema.
  • Anda mengirim setiap baris data sebagai buffering protokol biner. BigQuery maps data ke skema.
  • Anda dapat menghapus kolom nullable, tetapi tidak dapat menyertakan kolom apa pun yang tidak ada dalam skema saat ini. Jika Anda mengirim baris dengan kolom tambahan, Storage Write API akan menampilkan StorageError dengan StorageErrorCode.SCHEMA_MISMATCH_EXTRA_FIELD.

Jika ingin mengirim kolom baru dalam payload, Anda harus terlebih dahulu memperbarui skema tabel di BigQuery. Storage Write API mendeteksi perubahan skema setelah beberapa saat, pada urutan menit. Saat Storage Write API mendeteksi perubahan skema, pesan respons AppendRowsResponse akan berisi objek TableSchema yang mendeskripsikan skema baru.

Untuk mengirim data menggunakan skema yang diperbarui, Anda harus menutup koneksi yang ada dan membuka koneksi baru dengan skema baru.

Klien Java. Library klien Java menyediakan beberapa fitur tambahan untuk update skema, melalui class JsonStreamWriter. Setelah update skema, JsonStreamWriter secara otomatis terhubung kembali dengan skema yang diperbarui. Anda tidak perlu secara eksplisit menutup dan membuka kembali koneksi. Untuk memeriksa perubahan skema secara terprogram, panggil AppendRowsResponse.hasUpdatedSchema setelah metode append selesai.

Anda juga dapat mengonfigurasi JsonStreamWriter untuk mengabaikan kolom yang tidak dikenal dalam data input. Untuk menetapkan perilaku ini, panggil setIgnoreUnknownFields. Perilaku ini mirip dengan opsi ignoreUnknownValues saat menggunakan tabledata.insertAll API lama. Namun, hal ini dapat menyebabkan kehilangan data yang tidak disengaja karena kolom yang tidak dikenal dihapus secara otomatis.