Membuat tabel Amazon S3 BigLake

Dokumen ini menjelaskan cara membuat tabel BigLake Amazon Simple Storage Service (Amazon S3). Dengan tabel BigLake, Anda dapat menggunakan delegasi akses untuk membuat kueri data di Amazon S3. Delegasi akses memisahkan akses ke tabel BigLake dari akses ke penyimpanan data pokok.

Untuk mengetahui informasi tentang aliran data antara BigQuery dan Amazon S3, lihat Aliran data saat membuat kueri data.

Sebelum memulai

Pastikan Anda memiliki koneksi untuk mengakses data Amazon S3.

Peran yang diperlukan

Agar mendapatkan izin yang diperlukan untuk membuat tabel eksternal, minta administrator untuk memberi Anda peran IAM BigQuery Admin (roles/bigquery.admin) di set data Anda. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses.

Peran yang telah ditentukan ini berisi izin yang diperlukan untuk membuat tabel eksternal. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk membuat tabel eksternal:

bigquery.tables.create
bigquery.connections.delegate

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Membuat set data

Sebelum membuat tabel eksternal, Anda perlu membuat set data di region yang didukung. Pilih salah satu opsi berikut:

Konsol

Buka halaman BigQuery.

Buka BigQuery
Di panel Explorer, pilih project tempat Anda ingin membuat set data.
Perluas opsi Tampilkan tindakan, lalu klik Buat set data.
Di halaman Buat set data, tentukan detail berikut:

Untuk ID Set Data, masukkan nama set data yang unik.
Untuk Lokasi data, pilih region yang didukung.
Opsional: Untuk menghapus tabel secara otomatis, pilih kotak centang Aktifkan masa berakhir tabel dan tetapkan Usia tabel maksimum default dalam hari. Data di Amazon S3 tidak dihapus saat masa berlaku tabel habis.
Jika Anda ingin menggunakan kolasi default, perluas bagian Opsi lanjutan, lalu pilih opsi Aktifkan kolasi default.
Klik Buat set data.

SQL

Gunakan pernyataan DDL CREATE SCHEMA. Contoh berikut membuat set data di region aws-us-east-1 :

Di konsol Google Cloud, buka halaman BigQuery.

Buka BigQuery

Di editor kueri, masukkan pernyataan berikut:

CREATE SCHEMA mydataset
OPTIONS (
  location = 'aws-us-east-1');

Klik Run.

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

bq

Di lingkungan command line, buat set data menggunakan perintah bq mk:

bq --location=LOCATION mk \
    --dataset \
PROJECT_ID:DATASET_NAME

Parameter --project_id akan mengganti project default.

Ganti kode berikut:

LOCATION: lokasi set data Anda

Untuk mengetahui informasi tentang region yang didukung, lihat Lokasi. Setelah membuat set data, Anda tidak dapat mengubah lokasinya. Anda dapat menetapkan nilai default untuk lokasi menggunakan file .bigqueryrc.
PROJECT_ID: project ID Anda
DATASET_NAME: nama set data yang ingin Anda buat

Untuk membuat set data dalam project selain project default Anda, tambahkan project ID ke nama set data dalam format berikut: PROJECT_ID:DATASET_NAME.

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.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import com.google.cloud.bigquery.DatasetInfo;

// Sample to create a aws dataset
public class CreateDatasetAws {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    // Note: As of now location only supports aws-us-east-1
    String location = "aws-us-east-1";
    createDatasetAws(projectId, datasetName, location);
  }

  public static void createDatasetAws(String projectId, String datasetName, String location) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      DatasetInfo datasetInfo =
          DatasetInfo.newBuilder(projectId, datasetName).setLocation(location).build();

      Dataset dataset = bigquery.create(datasetInfo);
      System.out.println(
          "Aws dataset created successfully :" + dataset.getDatasetId().getDataset());
    } catch (BigQueryException e) {
      System.out.println("Aws dataset was not created. \n" + e.toString());
    }
  }
}

Membuat tabel BigLake pada data yang tidak dipartisi

Pilih salah satu opsi berikut:

Konsol

Buka halaman BigQuery.

Buka BigQuery
Di panel Explorer, luaskan project Anda, lalu pilih set data.
Di bagian Info set data, klik Buat tabel.
Di halaman Buat tabel, di bagian Sumber, lakukan hal berikut:
1. Untuk Buat tabel dari, pilih Amazon S3.
2. Untuk Pilih jalur S3 pah, masukkan URI yang mengarah ke data Amazon S3 dalam format s3://BUCKET_NAME/PATH. Ganti BUCKET_NAME dengan nama bucket Amazon S3; region bucket harus sama dengan region set data. Ganti PATH dengan jalur yang ingin Anda jadikan tujuan penulisan file yang diekspor; kartu ini dapat berisi satu karakter pengganti *.
3. Untuk Format file, pilih format data di Amazon S3. Format yang didukung adalah AVRO, PARQUET, ORC, CSV, dan JSONL (JSON yang dibatasi newline).
Di bagian Tujuan, tentukan detail berikut:
1. Untuk Set data, pilih set data yang sesuai.
2. Di kolom Tabel, masukkan nama tabel.
3. Pastikan Jenis tabel ditetapkan ke Tabel eksternal.
4. Untuk ID Koneksi, pilih ID koneksi yang sesuai dari menu drop-down. Untuk mengetahui informasi tentang koneksi, lihat Menghubungkan ke Amazon S3.
Di bagian Schema, Anda dapat mengaktifkan deteksi otomatis skema atau menentukan skema secara manual jika Anda memiliki file sumber. Jika tidak memiliki file sumber, Anda harus menentukan skema secara manual.
- Untuk mengaktifkan deteksi otomatis skema, pilih opsi Auto-detect.
- Untuk menentukan skema secara manual, biarkan opsi Deteksi otomatis tidak dicentang. Aktifkan Edit sebagai teks dan masukkan skema tabel sebagai array JSON.
Klik Buat tabel.

SQL

Untuk membuat tabel BigLake, gunakan pernyataan CREATE EXTERNAL TABLE dengan klausa WITH CONNECTION:

Di konsol Google Cloud, buka halaman BigQuery.

Buka BigQuery
Di editor kueri, masukkan pernyataan berikut:
```
CREATE EXTERNAL TABLE DATASET_NAME.TABLE_NAME
  WITH CONNECTION `AWS_LOCATION.CONNECTION_NAME`
  OPTIONS (
    format = "DATA_FORMAT",
    uris = ["S3_URI"],
    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
- AWS_LOCATION: lokasi AWS di Google Cloud (misalnya, `aws-us-east-1`)
- CONNECTION_NAME: nama koneksi yang Anda buat
- DATA_FORMAT: salah satu format gabungan BigQuery yang didukung (seperti AVRO, CSV, atau DELTA_LAKE (pratinjau))
- S3_URI: URI yang mengarah ke data Amazon S3 (misalnya, s3://bucket/path)
- 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 penghentian 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 lama dari itu, operasi akan mengambil metadata dari Amazon S3.
- CACHE_MODE: menentukan apakah cache metadata di-refresh 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.
Klik Run.

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

Contoh:

CREATE EXTERNAL TABLE awsdataset.awstable
  WITH CONNECTION `aws-us-east-1.s3-read-connection`
  OPTIONS (
    format="CSV",
    uris=["s3://s3-bucket/path/file.csv"],
    max_staleness = INTERVAL 1 DAY,
    metadata_cache_mode = 'AUTOMATIC'
);

bq

Buat file definisi tabel:

bq mkdef  \
--source_format=DATA_FORMAT \
--connection_id=AWS_LOCATION.CONNECTION_NAME \
--metadata_cache_mode=CACHE_MODE \
S3_URI > table_def

Ganti kode berikut:

DATA_FORMAT: salah satu format gabungan BigQuery yang didukung (seperti AVRO atau CSV).
S3_URI: URI yang mengarah ke data Amazon S3 (misalnya, s3://bucket/path).
AWS_LOCATION: lokasi AWS di Google Cloud (misalnya, aws-us-east-1).
CONNECTION_NAME: nama koneksi yang Anda buat.
CACHE_MODE: menentukan apakah cache metadata dimuat ulang secara otomatis atau manual. Anda hanya perlu menyertakan flag ini jika Anda juga berencana menggunakan flag --max_staleness dalam perintah bq mk berikutnya untuk mengaktifkan caching metadata. Untuk mengetahui informasi selengkapnya tentang pertimbangan caching metadata, lihat Pembuatan cache 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.

Selanjutnya, buat tabel BigLake:

bq mk --max_staleness=STALENESS_INTERVAL --external_table_definition=table_def DATASET_NAME.TABLE_NAME

Ganti kode berikut:

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 informasi selengkapnya tentang pertimbangan caching metadata, lihat Caching metadata untuk performa.

Untuk menonaktifkan caching metadata, tentukan 0. Ini adalah setelan defaultnya.

Untuk mengaktifkan cache metadata, tentukan nilai literal interval antara 30 menit hingga 7 hari. Misalnya, tentukan INTERVAL 4 HOUR untuk interval data yang tidak berlaku selama 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 lama dari itu, operasi akan mengambil metadata dari Amazon S3.
DATASET_NAME: nama set data yang Anda buat.
TABLE_NAME: nama yang ingin Anda berikan ke tabel ini.

Misalnya, perintah berikut akan membuat tabel BigLake baru, awsdataset.awstable, yang dapat mengkueri data Amazon S3 yang disimpan di jalur s3://s3-bucket/path/file.csv dan memiliki koneksi baca di lokasi aws-us-east-1:

bq mkdef  \
--autodetect \
--source_format=CSV \
--connection_id=aws-us-east-1.s3-read-connection \
--metadata_cache_mode=AUTOMATIC \
s3://s3-bucket/path/file.csv > table_def

bq mk --max_staleness=INTERVAL "1" HOUR \
--external_table_definition=table_def awsdataset.awstable

API

Panggil metode API metode tables.insert, lalu buat ExternalDataConfiguration di resource Table yang Anda teruskan.

Tentukan properti schema atau tetapkan properti autodetect ke true untuk mengaktifkan deteksi otomatis skema untuk sumber data yang didukung.

Tentukan properti connectionId guna mengidentifikasi koneksi yang akan digunakan untuk menghubungkan ke Amazon S3.

Java

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.CsvOptions;
import com.google.cloud.bigquery.ExternalTableDefinition;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

// Sample to create an external aws table
public class CreateExternalTableAws {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String connectionId = "MY_CONNECTION_ID";
    String sourceUri = "s3://your-bucket-name/";
    CsvOptions options = CsvOptions.newBuilder().setSkipLeadingRows(1).build();
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    ExternalTableDefinition externalTableDefinition =
        ExternalTableDefinition.newBuilder(sourceUri, options)
            .setConnectionId(connectionId)
            .setSchema(schema)
            .build();
    createExternalTableAws(projectId, datasetName, tableName, externalTableDefinition);
  }

  public static void createExternalTableAws(
      String projectId,
      String datasetName,
      String tableName,
      ExternalTableDefinition externalTableDefinition) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(projectId, datasetName, tableName);
      TableInfo tableInfo = TableInfo.newBuilder(tableId, externalTableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Aws external table created successfully");

      // Clean up
      bigquery.delete(TableId.of(projectId, datasetName, tableName));
    } catch (BigQueryException e) {
      System.out.println("Aws external was not created." + e.toString());
    }
  }
}

Membuat tabel BigLake pada data berpartisi

Anda dapat membuat tabel BigLake untuk data berpartisi Hive di Amazon S3. Setelah membuat tabel berpartisi secara eksternal, Anda tidak dapat mengubah kunci partisi. Anda harus membuat ulang tabel untuk mengubah kunci partisi.

Untuk membuat tabel BigLake berdasarkan data berpartisi Hive, pilih salah satu opsi berikut:

Konsol

Buka halaman BigQuery.

Buka BigQuery
Di panel Penjelajah, luaskan project Anda dan pilih set data.
Klik Tampilkan tindakan, lalu klik Buat tabel. Tindakan ini akan membuka panel Buat tabel.
Di bagian Sumber, tentukan detail berikut:
1. Untuk Buat tabel dari, pilih Amazon S3.
2. Berikan jalur ke folder tersebut, menggunakan karakter pengganti. Contoh, s3://mybucket/*.
  
  Folder tersebut harus berada di lokasi yang sama dengan set data yang berisi tabel yang ingin Anda buat, tambahkan, atau timpa.
3. Dari daftar Format file, pilih jenis file.
4. Pilih kotak centang Partisi data sumber, lalu tentukan detail berikut:
  1. Untuk Pilih Awalan URI Sumber, masukkan awalan URI. Contoh, s3://mybucket/my_files.
  2. Opsional: Untuk mewajibkan filter partisi pada semua kueri untuk tabel ini, centang kotak Memerlukan filter partisi. Mewajibkan filter partisi dapat mengurangi biaya dan meningkatkan performa. Untuk mengetahui informasi selengkapnya, lihat Mewajibkan filter predikat di kunci partisi dalam kueri.
  3. Di bagian Mode inferensi partisi, pilih salah satu opsi berikut:
    - Otomatis menyimpulkan jenis: tetapkan mode deteksi skema partisi ke AUTO.
    - Semua kolom adalah string: tetapkan mode deteksi skema partisi ke STRINGS.
    - Sediakan sendiri: tetapkan mode deteksi skema partisi ke CUSTOM dan masukkan informasi skema secara manual untuk kunci partisi. Untuk mengetahui informasi selengkapnya, lihat Menyediakan skema kunci partisi kustom.
Di bagian Tujuan, tentukan detail berikut:
1. Untuk Project, pilih project tempat Anda ingin membuat tabel.
2. Untuk Set data, pilih set data tempat Anda ingin membuat tabel.
3. Untuk Tabel, masukkan nama tabel yang ingin Anda buat.
4. Untuk jenis Tabel, pastikan memilih Tabel eksternal.
5. Untuk Connection ID, pilih koneksi yang Anda buat sebelumnya.
Di bagian Schema, Anda dapat mengaktifkan deteksi otomatis skema atau menentukan skema secara manual jika Anda memiliki file sumber. Jika tidak memiliki file sumber, Anda harus menentukan skema secara manual.
- Untuk mengaktifkan deteksi otomatis skema, pilih opsi Auto-detect.
- Untuk menentukan skema secara manual, biarkan opsi Deteksi otomatis tidak dicentang. Aktifkan Edit sebagai teks dan masukkan skema tabel sebagai array JSON.
Untuk mengabaikan baris dengan nilai kolom tambahan yang tidak cocok dengan skema, luaskan bagian Opsi lanjutan dan pilih Nilai tidak dikenal.
Klik Buat tabel.

SQL

Gunakan pernyataan DDL CREATE EXTERNAL TABLE:

Di konsol Google Cloud, buka halaman BigQuery.

Buka BigQuery
Di editor kueri, masukkan pernyataan berikut:
```
CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
WITH PARTITION COLUMNS
(
  PARTITION_COLUMN PARTITION_COLUMN_TYPE,
)
WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
OPTIONS (
  hive_partition_uri_prefix = "HIVE_PARTITION_URI_PREFIX",
  uris=['FILE_PATH'],
  format ="TABLE_FORMAT"
  max_staleness = STALENESS_INTERVAL,
  metadata_cache_mode = 'CACHE_MODE'
);
```
Ganti kode berikut:
- PROJECT_ID: nama project tempat Anda ingin membuat tabel—misalnya, myproject
- DATASET: nama set data BigQuery tempat Anda ingin membuat tabel —misalnya, mydataset
- EXTERNAL_TABLE_NAME: nama tabel yang ingin Anda buat—misalnya, mytable
- PARTITION_COLUMN: nama kolom partisi
- PARTITION_COLUMN_TYPE: jenis kolom partisi
- REGION: region yang berisi koneksi—misalnya, us
- CONNECTION_ID: nama koneksi—misalnya, myconnection
- HIVE_PARTITION_URI_PREFIX: awalan uri partisi hive–misalnya: s3://mybucket/
- FILE_PATH: jalur ke sumber data untuk tabel eksternal yang ingin Anda buat—misalnya: s3://mybucket/*.parquet
- TABLE_FORMAT: format tabel yang ingin Anda buat—misalnya, PARQUET
- 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 penghentian 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 lama dari itu, operasi akan mengambil metadata dari Amazon S3.
- CACHE_MODE: menentukan apakah cache metadata di-refresh 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.
Klik Run.

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

Contoh

Contoh berikut membuat tabel BigLake berdasarkan data yang dipartisi di Amazon S3. Skema terdeteksi secara otomatis.

CREATE EXTERNAL TABLE `my_dataset.my_table`
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "s3://mybucket/products",
  uris = ['s3://mybucket/products/*']
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

bq

Pertama, gunakan perintah bq mkdef untuk membuat file definisi tabel:

bq mkdef \
--source_format=SOURCE_FORMAT \
--connection_id=REGION.CONNECTION_ID \
--hive_partitioning_mode=PARTITIONING_MODE \
--hive_partitioning_source_uri_prefix=URI_SHARED_PREFIX \
--require_hive_partition_filter=BOOLEAN \
--metadata_cache_mode=CACHE_MODE \
 URIS > DEFINITION_FILE

Ganti kode berikut:

SOURCE_FORMAT: format sumber data eksternal. Contoh, CSV.
REGION: region yang berisi koneksi—misalnya, us.
CONNECTION_ID: nama koneksi—misalnya, myconnection.
PARTITIONING_MODE: mode partisi Hive. Gunakan salah satu nilai berikut:
- AUTO: Mendeteksi nama dan jenis kunci secara otomatis.
- STRINGS: Mengonversi nama kunci menjadi string secara otomatis.
- CUSTOM: Mengenkode skema kunci di awalan URI sumber.
URI_SHARED_PREFIX: awalan URI sumber.
BOOLEAN: Menentukan apakah akan memerlukan filter predikat pada waktu kueri. Flag ini bersifat opsional. Nilai defaultnya adalah false.
CACHE_MODE: menentukan apakah cache metadata dimuat ulang secara otomatis atau manual. Anda hanya perlu menyertakan flag ini jika Anda juga berencana menggunakan flag --max_staleness dalam perintah bq mk berikutnya untuk mengaktifkan caching metadata. Untuk mengetahui informasi selengkapnya tentang pertimbangan caching metadata, lihat Pembuatan cache 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.
URIS: jalur ke folder Amazon S3, menggunakan format karakter pengganti.
DEFINITION_FILE: jalur ke file definisi tabel di komputer lokal Anda.

Jika PARTITIONING_MODE adalah CUSTOM, sertakan skema kunci partisi dalam awalan URI sumber, menggunakan format berikut:

--hive_partitioning_source_uri_prefix=URI_SHARED_PREFIX/{KEY1:TYPE1}/{KEY2:TYPE2}/...

Setelah membuat file definisi tabel, gunakan perintah bq mk untuk membuat tabel BigLake:

bq mk --max_staleness=STALENESS_INTERVAL \
--external_table_definition=DEFINITION_FILE \
DATASET_NAME.TABLE_NAME \
SCHEMA

Ganti kode berikut:

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 informasi selengkapnya tentang pertimbangan caching metadata, lihat Caching metadata untuk performa.

Untuk menonaktifkan caching metadata, tentukan 0. Ini adalah setelan defaultnya.

Untuk mengaktifkan cache metadata, tentukan nilai literal interval antara 30 menit hingga 7 hari. Misalnya, tentukan INTERVAL 4 HOUR untuk interval data yang tidak berlaku selama 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 lama dari itu, operasi akan mengambil metadata dari Amazon S3.
DEFINITION_FILE: jalur ke file definisi tabel.
DATASET_NAME: nama set data yang berisi tabel.
TABLE_NAME: nama tabel yang Anda buat.
SCHEMA: menentukan jalur ke file skema JSON, atau menentukan skema dalam formulir field:data_type,field:data_type,.... Untuk menggunakan deteksi otomatis skema, hilangkan argumen ini.

Contoh

Contoh berikut menggunakan mode partisi Hive AUTO untuk data Amazon S3:

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=AUTO \
  --hive_partitioning_source_uri_prefix=s3://mybucket/myTable \
  --metadata_cache_mode=AUTOMATIC \
  s3://mybucket/* > mytable_def

bq mk --max_staleness=INTERVAL "1" HOUR \
  --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

Contoh berikut menggunakan mode partisi Hive STRING untuk data Amazon S3:

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=STRING \
  --hive_partitioning_source_uri_prefix=s3://mybucket/myTable \
  --metadata_cache_mode=AUTOMATIC \
  s3://mybucket/myTable/* > mytable_def

bq mk --max_staleness=INTERVAL "1" HOUR \
  --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

API

Untuk menetapkan partisi Hive menggunakan BigQuery API, sertakan objek hivePartitioningOptions dalam objek ExternalDataConfiguration saat Anda membuat file definisi tabel. Untuk membuat tabel BigLake, Anda juga harus menentukan nilai untuk kolom connectionId.

Jika menetapkan kolom hivePartitioningOptions.mode ke CUSTOM, Anda harus mengenkode skema kunci partisi di kolom hivePartitioningOptions.sourceUriPrefix sebagai berikut: s3://BUCKET/PATH_TO_TABLE/{KEY1:TYPE1}/{KEY2:TYPE2}/...

Untuk menerapkan penggunaan filter predikat pada waktu kueri, tetapkan kolom hivePartitioningOptions.requirePartitionFilter ke true.

Meja di Delta Lake

Untuk mendaftar ke pratinjau ini, lengkapi formulir berikut.

Untuk meminta masukan atau dukungan terkait fitur ini, kirim email ke bq-federated-formats@google.com.

Delta Lake adalah format tabel open source yang mendukung tabel data berskala petabyte. Tabel Delta Lake dapat dikueri sebagai tabel sementara dan permanen, serta didukung sebagai tabel BigLake.

Sinkronisasi skema

Delta Lake mempertahankan skema kanonik sebagai bagian dari metadatanya. Anda tidak dapat memperbarui skema menggunakan file metadata JSON. Untuk memperbarui skema:

Gunakan perintah bq update dengan flag --autodetect_schema:
```
bq update --autodetect_schema
PROJECT_ID:DATASET.TABLE
```
Ganti kode berikut:
- PROJECT_ID: project ID yang berisi tabel yang ingin Anda update
- DATASET: set data yang berisi tabel yang ingin Anda update
- TABLE: tabel yang ingin Anda update

Konversi jenis

BigQuery mengonversi jenis data Delta Lake menjadi jenis data BigQuery berikut:

Jenis Delta Lake	Jenis BigQuery
`boolean`	`BOOL`
`byte`	`INT64`
`int`	`INT64`
`long`	`INT64`
`float`	`FLOAT64`
`double`	`FLOAT64`
`Decimal(P/S)`	`NUMERIC` atau `BIG_NUMERIC` bergantung pada presisi
`date`	`DATE`
`time`	`TIME`
`timestamp (not partition column)`	`TIMESTAMP`
`timestamp (partition column)`	`DATETIME`
`string`	`STRING`
`binary`	`BYTES`
`array<Type>`	`ARRAY<Type>`
`struct`	`STRUCT`
`map<KeyType, ValueType>`	`ARRAY<Struct<key KeyType, value ValueType>>`

Batasan

Batasan berikut berlaku untuk tabel Delta Lake:

Batasan tabel eksternal berlaku untuk tabel Delta Lake.
Tabel Delta Lake hanya didukung di BigQuery Omni dan memiliki batasan terkait.
Anda tidak dapat memperbarui tabel dengan file metadata JSON baru. Anda harus menggunakan operasi update tabel skema deteksi otomatis. Lihat Sinkronisasi skema untuk mengetahui informasi selengkapnya.
Fitur keamanan BigLake hanya melindungi tabel Delta Lake saat diakses melalui layanan BigQuery.

Membuat tabel Delta Lake

Contoh berikut akan membuat tabel eksternal menggunakan pernyataan CREATE EXTERNAL TABLE dengan format Delta Lake:

CREATE [OR REPLACE] EXTERNAL TABLE table_name
WITH CONNECTION connection_name
OPTIONS (
         format = 'DELTA_LAKE',
         uris = ["parent_directory"]
       );

Ganti kode berikut:

table_name: Nama tabel.
connection_name: Nama koneksi. Koneksi tersebut harus mengidentifikasi sumber Amazon S3 atau Blob Storage.
parent_directory: URI direktori induk.

Transfer lintas-cloud dengan Delta Lake

Contoh berikut menggunakan pernyataan LOAD DATA untuk memuat data ke tabel yang sesuai:

LOAD DATA [INTO | OVERWRITE] table_name
FROM FILES (
        format = 'DELTA_LAKE',
        uris = ["parent_directory"]
)
WITH CONNECTION connection_name;

Untuk mengetahui contoh transfer data lintas-cloud lainnya, lihat Memuat data dengan operasi lintas cloud.

Membuat kueri tabel BigLake

Untuk mengetahui informasi selengkapnya, lihat Membuat kueri data Amazon S3.

Melihat metadata resource

Anda dapat melihat metadata resource dengan penayangan INFORMATION_SCHEMA . Saat Anda membuat kueri penayangan JOBS_BY_*, JOBS_TIMELINE_BY_*, dan RESERVATION*, Anda harus menentukan lokasi pemrosesan kueri yang digabungkan dengan region tabel. Untuk mengetahui informasi tentang lokasi BigQuery Omni, lihat Lokasi. Untuk semua tabel sistem lainnya, penetapan lokasi tugas kueri bersifat opsional.

Untuk mengetahui informasi tentang tabel sistem yang didukung BigQuery Omni, lihat Batasan.

Untuk membuat kueri tabel sistem JOBS_* dan RESERVATION*, pilih salah satu metode berikut untuk menentukan lokasi pemrosesan:

Konsol

Buka halaman BigQuery.

Buka BigQuery
Jika tab Editor tidak terlihat, klik Buat kueri baru.
Klik Lainnya > setelan Kueri. Dialog Query settings akan terbuka.
Dalam dialog Setelan kueri, untuk Setelan tambahan > Lokasi data, pilih BigQuery region yang terhubung dengan region BigQuery Omni. Misalnya, jika region BigQuery Omni Anda adalah aws-us-east-1, tentukan us-east4.
Pilih kolom lainnya, lalu klik Simpan.

bq

Gunakan flag --location untuk menetapkan lokasi pemrosesan tugas ke region BigQuery yang sama dengan region BigQuery Omni. Misalnya, jika region BigQuery Omni Anda adalah aws-us-east-1, tentukan us-east4.

Contoh

bq query --use_legacy_sql=false --location=us-east4 \
"SELECT * FROM region-aws-us-east-1.INFORMATION_SCHEMA.JOBS limit 10;"

bq query --use_legacy_sql=false --location=asia-northeast3 \
"SELECT * FROM region-aws-ap-northeast-2.INFORMATION_SCHEMA.JOBS limit 10;"

API

Jika Anda menjalankan tugas secara terprogram, tetapkan argumen lokasi ke region BigQuery yang sama dengan region BigQuery Omni. Misalnya, jika region BigQuery Omni Anda adalah aws-us-east-1, tentukan us-east4.

Contoh berikut mencantumkan tugas pembaruan metadata:

SELECT
 *
FROM
 `region-aws-us-east-1.INFORMATION_SCHEMA.JOBS_BY_PROJECT`
WHERE
 job_id LIKE '%metadata_cache_refresh%'
 AND creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 6 HOUR)
ORDER BY start_time desc
LIMIT 10;

Kontrol Layanan VPC

Anda dapat menggunakan perimeter Kontrol Layanan VPC untuk membatasi akses dari BigQuery Omni ke layanan cloud eksternal sebagai lapisan pertahanan tambahan. Misalnya, perimeter Kontrol Layanan VPC dapat membatasi ekspor dari tabel BigQuery Omni Anda ke bucket Amazon S3 atau container Blob Storage tertentu.

Untuk mempelajari lebih lanjut tentang Kontrol Layanan VPC, baca Ringkasan Kontrol Layanan VPC.

Izin yang diperlukan

Pastikan Anda memiliki izin yang diperlukan untuk mengonfigurasi perimeter layanan. Untuk melihat daftar peran IAM yang diperlukan untuk mengonfigurasi Kontrol Layanan VPC, lihat Kontrol akses dengan IAM dalam dokumentasi Kontrol Layanan VPC.

Menyiapkan Kontrol Layanan VPC menggunakan konsol Google Cloud

Di menu navigasi konsol Google Cloud, klik Keamanan, lalu klik Kontrol Layanan VPC.

Buka Kontrol Layanan VPC
Guna menyiapkan Kontrol Layanan VPC untuk BigQuery Omni, ikuti langkah-langkah dalam panduan Membuat perimeter layanan, dan ketika Anda membuka panel Aturan traffic keluar, ikuti langkah-langkah berikut:
1. Di panel Aturan traffic keluar, klik Tambahkan aturan.
2. Di bagian Dari atribut klien API, pilih salah satu opsi dari daftar Identitas.
3. Pilih Ke atribut resource eksternal.
4. Untuk menambahkan resource eksternal, klik Tambahkan resource eksternal.
5. Dalam dialog Tambahkan resource eksternal, untuk Nama resource eksternal, masukkan nama resource yang valid. Contoh:
  - Untuk Amazon Simple Storage Service (Amazon S3): s3://BUCKET_NAME
    
    Ganti BUCKET_NAME dengan nama bucket Amazon S3 Anda.
  - Untuk Azure Blob Storage: azure://myaccount.blob.core.windows.net/CONTAINER_NAME
    
    Ganti CONTAINER NAME dengan nama container Blob Storage Anda.
  Untuk mengetahui daftar atribut aturan traffic keluar, lihat Referensi aturan traffic keluar.
6. Pilih metode yang ingin Anda izinkan di resource eksternal:
  1. Jika Anda ingin mengizinkan semua metode, pilih Semua metode dalam daftar Metode.
  2. Jika ingin mengizinkan metode tertentu, pilih Metode yang dipilih, klik Pilih metode, lalu pilih metode yang ingin Anda izinkan di resource eksternal.
7. Klik Buat perimeter.

Menyiapkan Kontrol Layanan VPC menggunakan gcloud CLI

Untuk menyiapkan Kontrol Layanan VPC menggunakan gcloud CLI, ikuti langkah-langkah berikut:

Tetapkan kebijakan akses default.
Buat file input kebijakan traffic keluar.
Tambahkan kebijakan traffic keluar.

Menetapkan kebijakan akses default

Kebijakan akses adalah container berskala organisasi untuk tingkat akses dan perimeter layanan. Untuk informasi tentang cara menetapkan kebijakan akses default atau mendapatkan nama kebijakan akses, lihat Mengelola kebijakan akses.

Membuat file input kebijakan traffic keluar

Blok aturan traffic keluar menentukan akses yang diizinkan dari dalam perimeter ke resource di luar perimeter tersebut. Untuk resource eksternal, properti externalResources menentukan jalur resource eksternal yang diizinkan untuk akses dari dalam perimeter Kontrol Layanan VPC Anda.

Aturan traffic keluar dapat dikonfigurasi menggunakan file JSON atau file YAML. Contoh berikut menggunakan format .yaml:

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
      *OR*
      - permission: "externalResource.read"
    externalResources:
      - EXTERNAL_RESOURCE_PATH
  egressFrom:
    identityType: IDENTITY_TYPE
    *OR*
    identities:
    - serviceAccount:SERVICE_ACCOUNT

egressTo: mencantumkan operasi layanan yang diizinkan di resource Google Cloud dalam project tertentu di luar perimeter.
operations: mencantumkan layanan yang dapat diakses, tindakan atau metode yang diizinkan untuk diakses oleh klien yang memenuhi kondisi pemblokiran from.
serviceName: menetapkan bigquery.googleapis.com untuk BigQuery Omni.
methodSelectors: mencantumkan metode yang dapat diakses oleh klien yang memenuhi kondisi from. Guna mengetahui metode dan izin yang dapat dibatasi untuk layanan, lihat Pembatasan metode layanan yang didukung.
method : metode layanan yang valid, atau \"*\" untuk mengizinkan semua metode serviceName.
permission: izin layanan yang valid, seperti \"*\", externalResource.read, atau externalResource.write. Akses ke resource di luar perimeter diperbolehkan untuk operasi yang memerlukan izin ini.
externalResources: mencantumkan resource eksternal yang dapat diakses oleh klien di dalam perimeter. Ganti EXTERNAL_RESOURCE_PATH dengan bucket Amazon S3 yang valid, seperti s3://bucket_name, atau jalur container Blob Storage, seperti azure://myaccount.blob.core.windows.net/container_name.
egressFrom: mencantumkan operasi layanan yang diizinkan di resource Google Cloud dalam project tertentu di dalam perimeter.
identityType atau identities: menentukan jenis identitas yang dapat mengakses resource yang ditentukan di luar perimeter. Ganti IDENTITY_TYPE dengan salah satu nilai valid berikut:
- ANY_IDENTITY: untuk mengizinkan semua identitas.
- ANY_USER_ACCOUNT: untuk mengizinkan semua pengguna.
- ANY_SERVICE_ACCOUNT: untuk mengizinkan semua akun layanan
identities: mencantumkan akun layanan yang dapat mengakses resource yang ditentukan di luar perimeter.
serviceAccount (opsional): ganti SERVICE_ACCOUNT dengan akun layanan yang dapat mengakses resource tertentu di luar perimeter.

Contoh

Contoh berikut adalah kebijakan yang mengizinkan operasi traffic keluar dari dalam perimeter ke lokasi Amazon S3 s3://mybucket di AWS.

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
    externalResources:
      - s3://mybucket
      - s3://mybucket2
  egressFrom:
    identityType: ANY_IDENTITY

Contoh berikut mengizinkan operasi traffic keluar ke container Blob Storage:

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
    externalResources:
      - azure://myaccount.blob.core.windows.net/mycontainer
  egressFrom:
    identityType: ANY_IDENTITY

Untuk informasi selengkapnya tentang kebijakan traffic keluar, lihat Referensi aturan traffic keluar.

Menambahkan kebijakan traffic keluar

Untuk menambahkan kebijakan traffic keluar saat Anda membuat perimeter layanan baru, gunakan perintah gcloud access-context-manager perimeters create. Misalnya, perintah berikut membuat perimeter baru bernama omniPerimeter yang menyertakan project dengan nomor project 12345, membatasi BigQuery API, dan menambahkan kebijakan traffic keluar yang ditentukan dalam file egress.yaml:

gcloud access-context-manager perimeters create omniPerimeter \
    --title="Omni Perimeter" \
    --resources=projects/12345 \
    --restricted-services=bigquery.googleapis.com \
    --egress-policies=egress.yaml

Untuk menambahkan kebijakan traffic keluar ke perimeter layanan yang ada, gunakan perintah gcloud access-context-manager perimeters update. Misalnya, perintah berikut menambahkan kebijakan traffic keluar yang ditentukan dalam file egress.yaml ke perimeter layanan yang ada bernama omniPerimeter:

gcloud access-context-manager perimeters update omniPerimeter
    --set-egress-policies=egress.yaml

Memverifikasi perimeter Anda

Untuk memverifikasi perimeter, gunakan perintah gcloud access-context-manager perimeters describe:

gcloud access-context-manager perimeters describe PERIMETER_NAME

Ganti PERIMETER_NAME dengan nama perimeter.

Misalnya, perintah berikut menjelaskan perimeter omniPerimeter:

gcloud access-context-manager perimeters describe omniPerimeter

Untuk mengetahui informasi selengkapnya, lihat Mengelola perimeter layanan.

Batasan

Untuk mengetahui daftar lengkap batasan yang berlaku untuk tabel BigLake berdasarkan Amazon S3 dan Blob Storage, lihat Batasan.

Langkah selanjutnya

Pelajari BigQuery Omni.
Gunakan lab BigQuery Omni dengan AWS.
Pelajari tabel BigLake.
Pelajari cara mengekspor hasil kueri ke Amazon S3.
Pelajari cara membuat tampilan terwujud pada tabel Amazon Simple Storage Service (Amazon S3) yang mendukung cache.
Pelajari cara membuat data Amazon S3 dalam tampilan terwujud tersedia secara lokal untuk penggabungan dengan membuat replika tampilan terwujud.