Menggunakan penomoran halaman dengan BigQuery API
Dokumen ini menjelaskan cara membaca data tabel dan hasil kueri dalam set data besar menggunakan penomoran halaman dengan BigQuery API.
Dengan penomoran halaman, BigQuery memecah set data besar menjadi potongan yang lebih kecil yang disebut halaman. Untuk sebagian besar pengguna, Library Klien Cloud menangani proses ini secara otomatis, tetapi Anda juga dapat mengontrol penomoran halaman secara manual untuk kasus penggunaan tertentu seperti aplikasi web.
Menggunakan penomoran halaman otomatis
Library Klien Cloud menangani detail level rendah penomoran halaman API dan memberikan pengalaman yang mirip iterator. Saat Anda melakukan iterasi hasil, library akan otomatis mengambil halaman data berikutnya saat diperlukan.
Contoh berikut menunjukkan cara melakukan iterasi data tabel BigQuery secara otomatis.
C#
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C# di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery C# API.
Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
Go
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Go API.
Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
Java
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Java API.
Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
Node.js
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Node.js API.
Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
PHP
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan PHP di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery PHP API.
Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
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 mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
Ruby
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Ruby di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Ruby API.
Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
Mengontrol ukuran halaman
Anda dapat menentukan jumlah maksimum baris yang ditampilkan di setiap permintaan jaringan dengan menetapkan ukuran halaman. Menetapkan ukuran halaman berguna untuk mengoptimalkan penggunaan jaringan atau menyesuaikan data ke dalam memori.
Di sebagian besar library klien, Anda dapat menggunakan parameter max_results atau page_size
saat memanggil metode seperti list_rows atau query.
Menggunakan penomoran halaman manual dengan token halaman
Penomoran halaman manual berguna untuk aplikasi tanpa status, seperti layanan web tempat pengguna mengklik Berikutnya untuk melihat kumpulan hasil berikutnya. Dalam skenario ini, server tidak mempertahankan iterator aktif di antara permintaan.
Sebagai gantinya, Anda menggunakan token halaman sebagai berikut:
- Minta halaman. Panggil API dan terima parameter
pageTokenbersama dengan baris. - Lanjutkan. Pada permintaan berikutnya, teruskan kembali parameter
pageTokenyang sama ke BigQuery untuk mengambil potongan data berikutnya.
Contoh berikut menunjukkan cara mengambil token halaman dan menggunakannya untuk mengambil halaman hasil kueri berikutnya.
API
Baca kolom
jobs.config.query.destinationTable
untuk menentukan tabel tempat hasil kueri ditulis.
Panggil tabledata.list
untuk membaca hasil kueri.
Java
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Java API.
Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
Untuk menetapkan jumlah baris yang ditampilkan di setiap halaman, gunakan
tugas GetQueryResults dan tetapkan
opsi pageSize
dari objek QueryResultsOption yang Anda teruskan, seperti yang ditunjukkan dalam
contoh berikut:
TableResult result = job.getQueryResults();
QueryResultsOption queryResultsOption = QueryResultsOption.pageSize(20);
TableResult result = job.getQueryResults(queryResultsOption);
Node.js
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Node.js API.
Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
Python
Metode
QueryJob.result
menampilkan iterable hasil kueri. Sebagai alternatif,
- Baca
properti
QueryJob.destination. Jika tidak dikonfigurasi, properti ini akan ditetapkan oleh API ke referensi ke tabel anonim sementara. - Dapatkan skema tabel dengan
metode
Client.get_table. - Buat iterable di semua baris dalam tabel tujuan dengan
metode
Client.list_rows.
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 mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.
Mengoptimalkan dengan ETag
Jika Anda memundurkan halaman atau melompat ke halaman arbitrer menggunakan nilai pageToken yang di-cache, data di halaman Anda mungkin telah berubah sejak terakhir dilihat. Untuk mengurangi hasil ini, Anda dapat menggunakan properti etag.
Setiap metode collection.list (kecuali untuk Tabledata) menampilkan properti etag dalam hasil. Properti ini adalah hash hasil halaman yang dapat digunakan untuk memverifikasi apakah halaman telah berubah sejak permintaan terakhir. Ketika Anda membuat permintaan ke BigQuery berisi nilai ETag, BigQuery akan membandingkan nilai ETag dengan nilai ETag yang ditampilkan oleh API dan merespons berdasarkan apakah nilai ETag-nya cocok atau tidak. Anda dapat menggunakan ETag untuk menghindari panggilan daftar yang berlebihan seperti berikut ini:
- Untuk menampilkan nilai hanya jika nilainya telah berubah, buat panggilan daftar dengan
ETag yang sebelumnya disimpan menggunakan
header HTTP
If-None-Match. Jika ETag cocok, BigQuery akan menampilkan kode statusHTTP 304 Not Modifieddan tidak ada data, sehingga menghemat bandwidth. - Untuk menampilkan nilai hanya jika tidak berubah, gunakan
header HTTP
If-Match. BigQuery akan menampilkan412 Precondition Failedjika halaman telah berubah.
Referensi: Batas dan kriteria API
Semua metode *collection*.list menampilkan hasil yang diberi nomor halaman dalam keadaan tertentu. Properti maxResults membatasi jumlah hasil per halaman.
| Metode | Kriteria penomoran halaman | Batas maxResults default |
Batas maxResults maksimum |
Batas maxFieldValues maksimum |
|---|---|---|---|---|
tabledata.list |
Menampilkan hasil yang diberi nomor halaman jika ukuran respons melebihi
10 MB1 data atau lebih dari maxResults
baris. |
Tidak terbatas | Tidak terbatas | Tak terbatas |
Semua metode *collection*.list lainnya |
Menampilkan hasil yang diberi nomor halaman jika respons memiliki lebih dari
maxResults baris dan juga kurang dari batas maksimum. |
10.000 | Tak terbatas | 300.000 |
Jika hasilnya lebih besar dari batas byte atau kolom, hasilnya
akan dipangkas agar sesuai dengan batas. Jika satu baris lebih besar dari batas byte atau kolom,
metode tabledata.list dapat menampilkan hingga 100 MB data1,
yang sesuai dengan batas ukuran baris maksimum untuk hasil kueri.
Tidak ada ukuran minimum per halaman, dan beberapa halaman mungkin menampilkan lebih banyak baris daripada yang lain.
Metode REST API jobs.getQueryResults dapat menampilkan 20 MB data kecuali jika Anda secara eksplisit meminta lebih banyak melalui dukungan.
1Ukuran baris merupakan perkiraan, karena ukurannya didasarkan pada representasi internal dari data baris. Batas ukuran baris maksimum diterapkan selama tahap tertentu dari eksekusi tugas kueri.