Mengkueri format tabel terbuka dengan manifes

Dokumen ini menjelaskan cara menggunakan file manifes untuk mengkueri data yang tersimpan dalam format tabel terbuka seperti Apache Hudi dan Delta Lake.

Beberapa format tabel terbuka seperti Hudi dan Delta Lake mengekspor statusnya saat ini dalam satu atau beberapa file manifes. File manifes berisi daftar file data yang ada di tabel. Dengan dukungan manifes di BigQuery, Anda dapat mengkueri dan memuat data yang disimpan dalam format tabel terbuka.

Sebelum memulai

Aktifkan API Koneksi BigQuery, Reservasi BigQuery, dan BigLake .
Mengaktifkan API
Untuk membuat tabel BigLake, Anda dapat menjalankan perintah Spark dengan salah satu metode berikut:
- Buat cluster Dataproc Untuk mengkueri tabel Hudi, tetapkan kolom --optional-components ke HUDI. Untuk mengkueri tabel Delta, tetapkan --optional-components ke Presto.
- Gunakan prosedur tersimpan untuk Spark di BigQuery. Untuk melakukannya, ikuti langkah-langkah berikut:
  1. Buat koneksi Spark.
  2. Siapkan kontrol akses untuk koneksi tersebut.
Untuk menyimpan file manifes di Cloud Storage, buat bucket Cloud Storage. Anda harus terhubung ke bucket Cloud Storage Anda untuk mengakses file manifes. Untuk melakukannya, ikuti langkah-langkah berikut:
1. Buat koneksi resource Cloud.
2. Siapkan akses untuk koneksi tersebut.

Peran yang diperlukan

Untuk mengkueri tabel BigLake berdasarkan data Hudi dan Delta Lake, pastikan Anda memiliki peran berikut:

BigQuery Connection User (roles/bigquery.connectionUser)
BigQuery Data Viewer (roles/bigquery.dataViewer)
BigQuery User (roles/bigquery.user)

Anda juga dapat mengkueri tabel eksternal Hudi. Namun, sebaiknya Anda mengupgrade tabel eksternal ke BigLake. Untuk mengkueri tabel eksternal Hudi, pastikan Anda memiliki peran berikut:

BigQuery Data Viewer (roles/bigquery.dataViewer)
BigQuery User (roles/bigquery.user)
Storage Object Viewer (roles/storage.objectViewer)

Bergantung pada izin yang Anda miliki, Anda dapat memberikan peran ini pada diri sendiri atau meminta administrator untuk memberikannya. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Melihat peran yang dapat diberikan atas resource.

Untuk melihat izin spesifik yang diperlukan untuk mengkueri tabel BigLake, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

bigquery.connections.use
bigquery.jobs.create
bigquery.readsessions.create (Hanya diperlukan jika Anda membaca data dengan BigQuery Storage Read API)
bigquery.tables.get
bigquery.tables.getData

Anda juga mungkin mendapatkan izin ini dengan peran khusus atau peran yang telah ditetapkan sebelumnya.

Membuat kueri workload Hudi

Untuk mengkueri data Hudi, ikuti langkah-langkah berikut:

Buat tabel eksternal berdasarkan data Hudi.
Upgrade tabel eksternal ke BigLake.

Membuat tabel eksternal Hudi

Saat Anda menyinkronkan tabel dengan alat sinkronisasi untuk Hudi dan BigQuery, aktifkan flag use-bq-manifest-file untuk bertransisi ke pendekatan file manifes. Flag ini juga mengekspor file manifes dalam format yang didukung BigQuery dan menggunakannya untuk membuat tabel eksternal dengan nama yang ditentukan dalam parameter --table.

Untuk membuat tabel eksternal Hudi, ikuti langkah-langkah berikut:

Untuk membuat tabel eksternal Hudi, kirimkan tugas ke cluster Dataproc yang sudah ada. Saat Anda membuat konektor Hudi-BigQuery, aktifkan flag use-bq-manifest-file untuk bertransisi ke pendekatan file manifes. Flag ini mengekspor file manifes dalam format yang didukung BigQuery dan menggunakannya untuk membuat tabel eksternal dengan nama yang disebutkan dalam parameter --table.
```
spark-submit \
   --master yarn \
   --packages com.google.cloud:google-cloud-bigquery:2.10.4 \
   --class org.apache.hudi.gcp.bigquery.BigQuerySyncTool  \
   JAR \
   --project-id PROJECT_ID \
   --dataset-name DATASET \
   --dataset-location LOCATION \
   --table TABLE \
   --source-uri URI  \
   --source-uri-prefix URI_PREFIX \
   --base-path BASE_PATH  \
   --partitioned-by PARTITION_BY \
   --use-bq-manifest-file
```
Ganti kode berikut:
- JAR: Jika Anda menggunakan konektor Hudi-BigQuery, tentukan hudi-gcp-bundle-0.14.0.jar. Jika Anda menggunakan komponen Hudi di Dataproc 2.1, tentukan /usr/lib/hudi/tools/bq-sync-tool/hudi-gcp-bundle-0.12.3.1.jar
- PROJECT_ID: project ID tempat Anda ingin membuat tabel Hudi BigLake
- DATASET: set data tempat Anda ingin membuat tabel Hudi BigLake
- LOCATION: lokasi tempat Anda ingin membuat tabel Hudi BigLake
- TABLE: nama tabel yang ingin Anda buat
  
  Jika Anda melakukan transisi dari konektor Hudi-BigQuery versi sebelumnya (0.13.0 dan yang lebih lama) yang membuat tabel virtual pada file manifes, pastikan Anda menggunakan nama tabel yang sama agar Anda bisa mempertahankan kode pipeline downstream yang ada.
- URI: Cloud Storage URI yang Anda buat untuk menyimpan file manifes Hudi
  
  URI ini mengarah ke partisi level pertama; pastikan untuk menyertakan kunci partisinya. Contoh, gs://mybucket/hudi/mydataset/EventDate=*
- URI_PREFIX: imbuhan untuk jalur URI Cloud Storage, biasanya ini adalah jalur ke tabel Hudi
- BASE_PATH: jalur dasar untuk tabel Hudi
  
  Contoh, gs://mybucket/hudi/mydataset/
- PARTITION_BY: nilai partisi
  
  Contoh, EventDate
Untuk mengetahui informasi selengkapnya tentang konfigurasi konektor, lihat konektor Hudi-BigQuery.
Untuk menyetel kontrol terperinci yang sesuai atau mempercepat performa dengan mengaktifkan penyimpanan metadata ke dalam cache, lihat Mengupgrade tabel BigLake.

Mengkueri workload Delta

Untuk mengkueri workload Delta, ikuti langkah-langkah berikut:

Buat file manifes.
Buat tabel BigLake berdasarkan file manifes.
Setel kontrol terperinci yang sesuai atau percepat performa dengan mengaktifkan penyimpanan metadata ke dalam cache. Untuk melakukan ini, lihat Mengupgrade tabel BigLake.

Membuat file manifes

BigQuery mendukung file manifes dalam format SymLinkTextInputFormat, yang merupakan daftar URI yang dibatasi baris baru. Untuk mengetahui informasi selengkapnya tentang pembuatan file manifes, lihat Menyiapkan integrasi Presto ke Delta Lake dan mengkueri tabel Delta.

Untuk membuat file manifes, kirimkan tugas ke cluster Dataproc yang sudah ada:

SQL

Dengan menggunakan Spark, jalankan perintah berikut pada tabel Delta di lokasi path-to-delta-table:

GENERATE symlink_format_manifest FOR TABLE delta.`<path-to-delta-table>`

Scala

Dengan menggunakan Spark, jalankan perintah berikut pada tabel Delta di lokasi path-to-delta-table:

val deltaTable = DeltaTable.forPath(<path-to-delta-table>)
deltaTable.generate("symlink_format_manifest")

Java

Dengan menggunakan Spark, jalankan perintah berikut pada tabel Delta di lokasi path-to-delta-table:

DeltaTable deltaTable = DeltaTable.forPath(<path-to-delta-table>);
deltaTable.generate("symlink_format_manifest");

Python

Dengan menggunakan Spark, jalankan perintah berikut pada tabel Delta di lokasi path-to-delta-table:

deltaTable = DeltaTable.forPath(<path-to-delta-table>)
deltaTable.generate("symlink_format_manifest")

Membuat tabel Delta BigLake

Untuk membuat tabel Delta BigLake, gunakan pernyataan CREATE EXTERNAL TABLE dengan kolom file_set_spec_type ditetapkan ke NEW_LINE_DELIMITED_MANIFEST:

Buka halaman BigQuery.

Buka BigQuery
Di editor kueri, jalankan pernyataan CREATE EXTERNAL TABLE:
```
CREATE EXTERNAL TABLE PROJECT_ID.DATASET_NAME.TABLE_NAME
WITH PARTITION COLUMNS(
`PARTITION_COLUMN PARTITION_COLUMN_TYPE`,)
WITH CONNECTION `PROJECT_IDREGION.CONNECTION_NAME`
OPTIONS (
   format = "DATA_FORMAT",
   uris = ["URI"],
   file_set_spec_type = 'NEW_LINE_DELIMITED_MANIFEST',
   hive_partition_uri_prefix = "PATH_TO_DELTA_TABLE"
   max_staleness = STALENESS_INTERVAL,
   metadata_cache_mode = 'CACHE_MODE');
```
Ganti kode berikut:
- DATASET_NAME: nama set data yang Anda buat
- TABLE_NAME: nama yang ingin Anda berikan untuk tabel ini
- REGION: lokasi koneksi (misalnya, us-east1)
- CONNECTION_NAME: nama koneksi yang Anda buat
- DATA_FORMAT: semua format yang didukung (seperti PARQUET)
- URI: jalur ke file manifes (misalnya, gs://mybucket/path)
- PATH_TO_DELTA_TABLE: imbuhan umum untuk semua URI sumber sebelum encoding kunci partisi dimulai
- STALENESS_INTERVAL: menentukan apakah metadata yang di-cache digunakan oleh operasi terhadap tabel BigLake, dan seberapa baru metadata yang di-cache untuk dapat digunakan oleh operasi. Untuk mengetahui informasi selengkapnya tentang pertimbangan caching metadata, lihat Caching metadata untuk peningkatan performa.
  Untuk menonaktifkan caching metadata, tentukan 0. Ini adalah setelan defaultnya.
  
  Untuk mengaktifkan caching metadata, tentukan nilai literal interval antara 30 menit dan 7 hari. Misalnya, tentukan INTERVAL 4 HOUR untuk interval periode tidak berlaku 4 jam. Dengan nilai ini, operasi terhadap tabel akan menggunakan metadata yang di-cache jika metadata yang di-cache telah diperbarui dalam 4 jam terakhir. Jika metadata yang di-cache lebih tua, operasi akan mengambil metadata dari Delta Lake.
- CACHE_MODE: menentukan apakah cache metadata diperbarui secara otomatis atau manual. Untuk mengetahui informasi selengkapnya tentang pertimbangan caching metadata, lihat Caching metadata untuk performa.
  Tetapkan ke AUTOMATIC agar cache metadata di-refresh pada interval yang ditentukan sistem, biasanya antara 30 dan 60 menit.
  
  Tetapkan ke MANUAL jika Anda ingin me-refresh cache metadata pada jadwal yang Anda tentukan. Dalam hal ini, Anda dapat memanggil prosedur sistem BQ.REFRESH_EXTERNAL_METADATA_CACHE untuk me-refresh cache.
  
  Anda harus menetapkan CACHE_MODE jika STALENESS_INTERVAL ditetapkan ke nilai yang lebih besar dari 0.
Contoh:
```
CREATE EXTERNAL TABLE mydataset.mytable
WITH CONNECTION `us-east1.myconnection`
OPTIONS (
    format="PARQUET",
    uris=["gs://mybucket/path/partitionpath=*"],
    file_set_spec_type = 'NEW_LINE_DELIMITED_MANIFEST'
    hive_partition_uri_prefix = "gs://mybucket/path/"
    max_staleness = INTERVAL 1 DAY,
    metadata_cache_mode = 'AUTOMATIC'
);
```

Mengupgrade tabel BigLake

Anda juga dapat mempercepat performa workload dengan memanfaatkan penyimpanan metadata ke dalam cache dan tampilan terwujud. Jika ingin menyimpan metadata ke dalam cache, Anda dapat mengatur setelannya secara bersamaan. Untuk mendapatkan detail tabel, seperti format sumber dan URI sumber, lihat Mendapatkan informasi tabel.

Untuk memperbarui tabel eksternal menjadi tabel BigLake atau memperbarui BigLake yang sudah ada, pilih salah satu opsi berikut:

SQL

Gunakan pernyataan DDL CREATE OR REPLACE EXTERNAL TABLE untuk mengupdate tabel:

Di Konsol Google Cloud, buka halaman BigQuery.

Buka BigQuery
Di editor kueri, masukkan pernyataan berikut:
```
CREATE OR REPLACE EXTERNAL TABLE
  `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
  WITH CONNECTION `REGION.CONNECTION_ID`
  OPTIONS(
    format ="TABLE_FORMAT",
    uris = ['BUCKET_PATH'],
    max_staleness = STALENESS_INTERVAL,
    metadata_cache_mode = 'CACHE_MODE'
    );
```
Ganti kode berikut:
- PROJECT_ID: nama project yang berisi tabel
- DATASET: nama set data yang berisi tabel
- EXTERNAL_TABLE_NAME: nama tabel
- REGION: region yang berisi koneksi
- CONNECTION_ID: nama koneksi yang akan digunakan
- TABLE_FORMAT: format yang digunakan oleh tabel
  
  Anda tidak dapat mengubahnya saat mengupdate tabel.
- BUCKET_PATH: jalur ke bucket Cloud Storage yang berisi data untuk tabel eksternal, dalam format ['gs://bucket_name/[folder_name/]file_name'].
  Anda dapat memilih beberapa file dari bucket dengan menentukan satu karakter pengganti tanda bintang (*) di jalur. Contoh, ['gs://mybucket/file_name*']. Untuk informasi selengkapnya, lihat Dukungan karakter pengganti untuk URI Cloud Storage.
  
  Anda dapat menyertakan beberapa bucket untuk opsi uris dengan memberikan beberapa jalur.
  
  Contoh berikut menunjukkan nilai uris yang valid:
  - ['gs://bucket/path1/myfile.csv']
  - ['gs://bucket/path1/*.csv']
  - ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']
  Saat Anda menentukan nilai uris yang menargetkan beberapa file, semua file tersebut harus berbagi skema yang kompatibel.
  
  Untuk informasi selengkapnya tentang penggunaan URI Cloud Storage di BigQuery, lihat Jalur resource Cloud Storage.
- STALENESS_INTERVAL: menentukan apakah metadata yang di-cache digunakan oleh operasi terhadap tabel, dan seberapa baru metadata yang di-cache agar operasi dapat menggunakannya
  
  Untuk informasi selengkapnya tentang pertimbangan caching metadata, lihat Caching metadata untuk performa.
  Untuk menonaktifkan caching metadata, tentukan 0. Ini adalah setelan defaultnya.
  
  Untuk mengaktifkan caching metadata, tentukan nilai literal interval antara 30 menit dan 7 hari. Misalnya, tentukan INTERVAL 4 HOUR untuk interval periode tidak berlaku 4 jam. Dengan nilai ini, operasi terhadap tabel akan menggunakan metadata yang di-cache jika telah di-refresh dalam 4 jam terakhir. Jika metadata yang di-cache lebih tua, operasi akan mengambil metadata dari Cloud Storage.
- CACHE_MODE: menentukan apakah cache metadata di-refresh secara otomatis atau manual
  
  Untuk informasi selengkapnya terkait pertimbangan caching metadata, lihat Caching metadata untuk performa.
  Ubah ke AUTOMATIC agar cache metadata diperbarui sesuai dengan interval yang ditentukan sistem, biasanya antara 30 hingga 60 menit.
  
  Ubah ke MANUAL jika Anda ingin memperbarui cache metadata sesuai dengan jadwal yang Anda tentukan. Dalam hal ini, Anda dapat memanggil prosedur sistem BQ.REFRESH_EXTERNAL_METADATA_CACHE untuk me-refresh cache.
  
  Anda harus menetapkan CACHE_MODE jika STALENESS_INTERVAL ditetapkan ke nilai yang lebih besar dari 0.
Klik Run.

Untuk informasi selengkapnya tentang cara menjalankan kueri, lihat Menjalankan kueri interaktif.

bq

Gunakan perintah bq mkdef dan bq update untuk mengupdate tabel:

Buat definisi tabel eksternal, yang menjelaskan aspek tabel yang akan diubah:
```
bq mkdef --connection_id=PROJECT_ID.REGION.CONNECTION_ID \
--source_format=TABLE_FORMAT \
--metadata_cache_mode=CACHE_MODE \
"BUCKET_PATH" > /tmp/DEFINITION_FILE
```
Ganti kode berikut:
- PROJECT_ID: nama project yang berisi koneksi
- REGION: region yang berisi koneksi
- CONNECTION_ID: nama koneksi yang akan digunakan
- TABLE_FORMAT: format yang digunakan oleh tabel. Anda tidak dapat mengubahnya saat mengupdate tabel.
- CACHE_MODE: menentukan apakah cache metadata dimuat ulang secara otomatis atau manual. Untuk informasi selengkapnya seputar pertimbangan caching metadata, lihat Caching metadata untuk performa.
  
  Tetapkan ke AUTOMATIC agar cache metadata di-refresh pada interval yang ditentukan sistem, biasanya antara 30 dan 60 menit.
  
  Tetapkan ke MANUAL jika Anda ingin me-refresh cache metadata sesuai jadwal yang Anda tentukan. Dalam hal ini, Anda dapat memanggil prosedur sistem BQ.REFRESH_EXTERNAL_METADATA_CACHE untuk me-refresh cache.
  
  Anda harus menetapkan CACHE_MODE jika STALENESS_INTERVAL ditetapkan ke nilai yang lebih besar dari 0.
- BUCKET_PATH: jalur ke bucket Cloud Storage yang berisi data untuk tabel eksternal, dalam format gs://bucket_name/[folder_name/]file_name.
  
  Anda dapat membatasi file yang dipilih dari bucket dengan menentukan satu karakter pengganti tanda bintang (*) di jalur. Contoh, gs://mybucket/file_name*. Untuk informasi selengkapnya, lihat Dukungan karakter pengganti untuk URI Cloud Storage.
  
  Anda dapat menentukan beberapa bucket untuk opsi uris dengan menyediakan beberapa jalur.
  
  Contoh berikut menunjukkan nilai uris yang valid:
  - gs://bucket/path1/myfile.csv
  - gs://bucket/path1/*.csv
  - gs://bucket/path1/*,gs://bucket/path2/file00*
  Saat Anda menentukan nilai uris yang menargetkan beberapa file, semua file tersebut harus berbagi skema yang kompatibel.
  
  Untuk informasi selengkapnya tentang penggunaan URI Cloud Storage di BigQuery, lihat Jalur resource Cloud Storage.
- DEFINITION_FILE: nama file definisi tabel yang Anda buat.
Update tabel menggunakan definisi tabel eksternal baru:
```
bq update --max_staleness=STALENESS_INTERVAL \
--external_table_definition=/tmp/DEFINITION_FILE \
PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME
```
Ganti kode berikut:
- STALENESS_INTERVAL: menentukan apakah metadata yang di-cache digunakan oleh operasi terhadap tabel, dan seberapa baru metadata yang di-cache agar operasi dapat menggunakannya. Untuk informasi selengkapnya tentang pertimbangan caching metadata, lihat Caching metadata untuk performa.
  
  Untuk menonaktifkan caching metadata, tentukan 0. Ini adalah setelan defaultnya.
  
  Untuk mengaktifkan caching metadata, tentukan nilai interval antara 30 menit hingga 7 hari, menggunakan Y-M D H:M:S yang dijelaskan dalam dokumentasi jenis data INTERVAL. Misalnya, tentukan 0-0 0 4:0:0 untuk interval periode tidak berlaku 4 jam. Dengan nilai ini, operasi terhadap tabel akan menggunakan metadata yang di-cache jika telah di-refresh dalam 4 jam terakhir. Jika metadata yang di-cache lebih tua, operasi akan mengambil metadata dari Cloud Storage.
- DEFINITION_FILE: nama file definisi tabel yang Anda buat atau update.
- PROJECT_ID: nama project yang berisi tabel
- DATASET: nama set data yang berisi tabel
- EXTERNAL_TABLE_NAME: nama tabel

Mengkueri tabel BigLake dan eksternal

Setelah membuat tabel BigLake, Anda dapat membuat kuerinya dengan sintaksis GoogleSQL, sama seperti tabel BigQuery standar. Contoh, SELECT field1, field2 FROM mydataset.my_cloud_storage_table;.

Batasan

BigQuery hanya mendukung kueri tabel pembaca Delta Lake v1.
Integrasi Hudi dan BigQuery hanya berfungsi untuk tabel copy-on-write yang dipartisi dengan gaya hive.
Menggunakan manifes untuk mengkueri data yang disimpan di penyimpanan pihak ketiga tidak didukung.

Langkah selanjutnya

Pelajari cara menggunakan SQL di BigQuery.
Pelajari tabel BigLake.
Pelajari kuota BigQuery.