Membuat tabel objek

Dokumen ini menjelaskan cara mengakses data tidak terstruktur di BigQuery dengan membuat tabel objek.

Untuk membuat tabel objek, Anda harus menyelesaikan tugas-tugas berikut:

1. Buat koneksi untuk membaca informasi objek dari Cloud Storage.
2. Berikan izin untuk membaca informasi Cloud Storage ke akun layanan yang terkait dengan koneksi.
3. Buat tabel objek dan kaitkan dengan koneksi menggunakan pernyataan CREATE EXTERNAL TABLE.

Sebelum memulai

1. Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

2. Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.

   Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

   Buka pemilih project

3. Pastikan penagihan telah diaktifkan untuk project Google Cloud Anda.

4. Aktifkan API BigQuery and BigQuery Connection API.

   Mengaktifkan API

5. Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.

   Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

   Buka pemilih project

6. Pastikan penagihan telah diaktifkan untuk project Google Cloud Anda.

7. Aktifkan API BigQuery and BigQuery Connection API.

   Mengaktifkan API

8. Pastikan administrator BigQuery Anda telah membuat koneksi dan menyiapkan akses ke Cloud Storage.

Peran yang diperlukan

Untuk menggunakan tabel objek, pengguna memerlukan izin IAM berikut berdasarkan perannya dalam organisasi Anda. Untuk mengetahui informasi lebih lanjut tentang peran pengguna, lihat Model keamanan. Untuk mengetahui informasi selengkapnya tentang cara memberikan izin, lihat Melihat peran yang dapat diberikan pada resource.

• Administrator data lake

  Untuk mendapatkan izin yang Anda perlukan untuk terhubung ke Cloud Storage, minta administrator untuk memberi Anda peran BigQuery Connection Admin (roles/bigquery.connectionAdmin) pada project tersebut.

  Untuk mendapatkan izin yang diperlukan untuk membuat dan mengelola bucket Cloud Storage, minta administrator Anda untuk memberi Anda peran Storage Admin (roles/storage.admin) di project tersebut.

  Peran yang telah ditentukan ini berisi izin yang diperlukan untuk terhubung ke Cloud Storage serta membuat dan mengelola bucket Cloud Storage. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

  Izin yang diperlukan

  • bigquery.connections.create
  • bigquery.connections.get
  • bigquery.connections.list
  • bigquery.connections.update
  • bigquery.connections.use
  • bigquery.connections.delete
  • storage.bucket.*
  • storage.object.*

• Administrator data warehouse

  Untuk mendapatkan izin yang Anda perlukan untuk membuat tabel objek, minta administrator untuk memberi Anda peran berikut pada project:

  • Peran BigQuery Data Editor (roles/bigquery.dataEditor).
  • Peran BigQuery Connection Admin (roles/bigquery.connectionAdmin).

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

  Izin yang diperlukan

  • bigquery.tables.create
  • bigquery.tables.update
  • bigquery.connections.delegate

• Analis Data

  Untuk mendapatkan izin yang Anda perlukan untuk membuat kueri tabel objek, minta administrator memberi Anda peran berikut pada project:

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

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

  Izin yang diperlukan

  • bigquery.jobs.create
  • bigquery.tables.get
  • bigquery.tables.getData
  • bigquery.readsessions.create

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

Perhatian: Analis data tidak boleh memiliki hal berikut:

• Kemampuan untuk membaca objek secara langsung dari Cloud Storage (lihat peran IAM Storage Object Viewer), yang memungkinkan analis data mengakali kontrol akses yang ditempatkan oleh administrator data warehouse.

• Kemampuan untuk mengikat tabel ke koneksi (seperti BigQuery Connection Administrator).

  Sebaliknya, analis data dapat membuat tabel objek baru yang tidak memiliki kontrol akses, sehingga akan mendayakan kontrol yang ditempatkan oleh administrator data warehouse.

Membuat tabel objek

Sebelum membuat tabel objek, Anda harus sudah memiliki set data untuk memuatnya. Untuk mengetahui informasi selengkapnya, lihat Membuat set data.

Untuk membuat tabel objek:

SQL

Gunakan pernyataan CREATE EXTERNAL TABLE.

1. Di konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di editor kueri, masukkan pernyataan berikut:

   CREATE EXTERNAL TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME`
   WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
   OPTIONS(
     object_metadata = 'SIMPLE',
     uris = ['BUCKET_PATH'[,...]],
     max_staleness = STALENESS_INTERVAL,
     metadata_cache_mode = 'CACHE_MODE');

   Ganti kode berikut:

   • PROJECT_ID: project ID Anda.
   • DATASET_ID: ID set data untuk memuat tabel objek.
   • TABLE_NAME: nama tabel objek.
   • REGION: region atau multi-region yang berisi koneksi.
   • CONNECTION_ID: ID koneksi resource cloud yang akan digunakan dengan tabel objek ini. Koneksi menentukan akun layanan mana yang digunakan untuk membaca data dari Cloud Storage.

     Saat Anda melihat detail koneksi di Konsol Google Cloud, ID koneksi adalah nilai di bagian terakhir dari ID koneksi yang sepenuhnya memenuhi syarat, yang ditampilkan dalam Connection ID—misalnya projects/myproject/locations/connection_location/connections/myconnection.

   • BUCKET_PATH: jalur ke bucket Cloud Storage yang berisi objek yang direpresentasikan oleh tabel objek, dalam format ['gs://bucket_name/[folder_name/]*'].

     Anda dapat menggunakan satu karakter pengganti tanda bintang (*) di setiap jalur untuk membatasi objek yang disertakan dalam tabel objek. Misalnya, jika bucket berisi beberapa jenis data tidak terstruktur, Anda dapat membuat tabel objek hanya pada objek PDF dengan menentukan ['gs://bucket_name/*.pdf']. Untuk informasi selengkapnya, lihat Dukungan karakter pengganti untuk URI Cloud Storage.

     Anda dapat menentukan beberapa bucket untuk opsi uris dengan memberikan beberapa jalur, misalnya ['gs://mybucket1/*', 'gs://mybucket2/folder5/*'].

     Untuk mengetahui 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 objek, dan seberapa baru metadata yang di-cache agar operasi dapat menggunakannya. Untuk informasi selengkapnya tentang pertimbangan penyimpanan metadata ke dalam cache, lihat Cache metadata untuk performa.

     Untuk menonaktifkan cache 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 usang, operasi akan mengambil metadata dari Cloud Storage.

   • CACHE_MODE: menentukan apakah cache metadata diperbarui 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.

     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.

3. Klik Run.

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

Contoh

Contoh berikut membuat tabel objek dengan interval keusangan cache metadata selama 1 hari:

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://mybucket/*'],
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

Contoh berikut akan membuat tabel objek di atas objek dalam tiga bucket Cloud Storage:

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://bucket1/*','gs://bucket2/folder1/*','gs://bucket3/*']
);

Contoh berikut membuat tabel objek hanya pada objek PDF dalam bucket Cloud Storage:

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://bucket1/*.pdf']
);

bq

Gunakan perintah bq mk.

bq mk --table \
--external_table_definition=[e-mail]_ID \
--object_metadata=SIMPLE \
--max_staleness=STALENESS_INTERVAL \
--metadata_cache_mode=CACHE_MODE \
PROJECT_ID:DATASET_ID.TABLE_NAME

Ganti kode berikut:

• PROJECT_ID: project ID Anda.
• DATASET_ID: ID set data untuk memuat tabel objek.
• TABLE_NAME: nama tabel objek.
• REGION: region atau multi-region yang berisi koneksi.
• CONNECTION_ID: ID koneksi resource cloud yang akan digunakan dengan tabel eksternal ini. Koneksi menentukan akun layanan yang digunakan untuk membaca data dari Cloud Storage.

  Saat Anda melihat detail koneksi di Konsol Google Cloud, ID koneksi adalah nilai di bagian terakhir ID koneksi yang sepenuhnya memenuhi syarat, yang ditampilkan di Connection ID—misalnya projects/myproject/locations/connection_location/connections/myconnection.

• BUCKET_PATH: jalur ke bucket Cloud Storage yang berisi objek yang direpresentasikan oleh tabel objek, dalam format gs://bucket_name/[folder_name/]*.

  Anda dapat menggunakan satu karakter pengganti tanda bintang (*) di setiap jalur untuk membatasi objek yang disertakan dalam tabel objek. Misalnya, jika bucket berisi beberapa jenis data tidak terstruktur, Anda dapat membuat tabel objek hanya pada objek PDF dengan menentukan gs://bucket_name/*.pdf. Untuk informasi selengkapnya, lihat Dukungan karakter pengganti untuk URI Cloud Storage.

  Anda dapat menentukan beberapa bucket untuk opsi uris dengan memberikan beberapa jalur, misalnya gs://mybucket1/*,gs://mybucket2/folder5/*.

  Untuk mengetahui 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 objek, dan seberapa baru metadata yang di-cache agar operasi dapat menggunakannya. Untuk informasi selengkapnya tentang pertimbangan penyimpanan metadata ke dalam cache, lihat Cache metadata untuk performa.

  Untuk menonaktifkan cache 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 usang, 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.

  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

Contoh berikut membuat tabel objek dengan interval keusangan cache metadata selama 1 hari:

bq mk --table \
--external_table_definition=gs://mybucket/*@us.my-connection \
--object_metadata=SIMPLE \
--max_staleness=0-0 1 0:0:0 \
--metadata_cache_mode=AUTOMATIC \
my_dataset.object_table

Contoh berikut akan membuat tabel objek di atas objek dalam tiga bucket Cloud Storage:

bq mk --table \
--external_table_definition=gs://bucket1/*,gs://bucket2/folder1/*,gs://bucket3/*@us.my-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

Contoh berikut membuat tabel objek hanya pada objek PDF dalam bucket Cloud Storage:

bq mk --table \
--external_table_definition=gs://bucket1/*[e-mail]-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

API

Panggil metode tables.insert. Sertakan objek ExternalDataConfiguration dengan kolom objectMetadata yang ditetapkan ke SIMPLE di resource Table yang Anda teruskan.

Contoh berikut menunjukkan cara memanggil metode ini menggunakan curl:

ACCESS_TOKEN=$(gcloud auth print-access-token) curl \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST \
-d '{"tableReference": {"projectId": "my_project", "datasetId": "my_dataset", "tableId": "object_table_name"}, "externalDataConfiguration": {"objectMetadata": "SIMPLE", "sourceUris": ["gs://mybucket/*"]}}' \
https://www.googleapis.com/bigquery/v2/projects/my_project/datasets/my_dataset/tables

Terraform

Contoh ini membuat tabel objek dengan penyimpanan metadata yang diaktifkan dan refresh manual.

Kolom utama yang perlu ditentukan untuk tabel objek adalah google_bigquery_table.external_data_configuration.object_metadata, google_bigquery_table.external_data_configuration.metadata_cache_mode, dan google_bigquery_table.max_staleness. Untuk mengetahui informasi selengkapnya tentang setiap resource, baca dokumentasi BigQuery Terraform.

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a connection in the US region named "my-connection-id".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection-id"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.default.project_id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This defines a Google BigQuery dataset.
resource "google_bigquery_dataset" "default" {
  dataset_id = "my_dataset_id"
}

# This creates a bucket in the US region named "my-bucket" with a pseudorandom suffix.
resource "random_id" "bucket_name_suffix" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.bucket_name_suffix.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

# This defines a BigQuery object table with manual metadata caching.
resource "google_bigquery_table" "default" {
  deletion_protection = false
  table_id            = "my-table-id"
  dataset_id          = google_bigquery_dataset.default.dataset_id
  external_data_configuration {
    connection_id = google_bigquery_connection.default.name
    autodetect    = false
    # `object_metadata is` required for object tables. For more information, see
    # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/bigquery_table#object_metadata
    object_metadata = "SIMPLE"
    # This defines the source for the prior object table.
    source_uris = [
      "gs://${google_storage_bucket.default.name}/*",
    ]

    metadata_cache_mode = "MANUAL"
  }

  # This ensures that the connection can access the bucket
  # before Terraform creates a table.
  depends_on = [
    google_project_iam_member.default
  ]
}

Untuk menerapkan konfigurasi Terraform di project Google Cloud, selesaikan langkah-langkah di bagian berikut.

Menyiapkan Cloud Shell

1. Luncurkan Cloud Shell.

2. Tetapkan project Google Cloud default tempat Anda ingin menerapkan konfigurasi Terraform.

   Anda hanya perlu menjalankan perintah ini sekali per project, dan dapat dijalankan di direktori mana pun.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Variabel lingkungan akan diganti jika Anda menetapkan nilai eksplisit dalam file konfigurasi Terraform.

Menyiapkan direktori

Setiap file konfigurasi Terraform harus memiliki direktorinya sendiri (juga disebut modul root).

1. Di Cloud Shell, buat direktori dan file baru di dalam direktori tersebut. Nama file harus memiliki ekstensi .tf—misalnya main.tf. Dalam tutorial ini, file ini disebut sebagai main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Jika mengikuti tutorial, Anda dapat menyalin kode contoh di setiap bagian atau langkah.

   Salin kode contoh ke dalam main.tf yang baru dibuat.

   Atau, salin kode dari GitHub. Tindakan ini direkomendasikan jika cuplikan Terraform adalah bagian dari solusi menyeluruh.

3. Tinjau dan ubah contoh parameter untuk diterapkan pada lingkungan Anda.
4. Simpan perubahan Anda.
5. Lakukan inisialisasi Terraform. Anda hanya perlu melakukan ini sekali per direktori.

   terraform init

   Secara opsional, untuk menggunakan versi penyedia Google terbaru, sertakan opsi -upgrade:

   terraform init -upgrade

Menerapkan perubahan

1. Tinjau konfigurasi dan pastikan resource yang akan dibuat atau diupdate oleh Terraform sesuai yang Anda inginkan:

   terraform plan

   Koreksi konfigurasi jika diperlukan.

2. Terapkan konfigurasi Terraform dengan menjalankan perintah berikut dan memasukkan yes pada prompt:

   terraform apply

   Tunggu hingga Terraform menampilkan pesan "Apply complete!".

3. Buka project Google Cloud Anda untuk melihat hasilnya. Di Konsol Google Cloud, buka resource Anda di UI untuk memastikan bahwa Terraform telah membuat atau mengupdatenya.

Catatan: Contoh Terraform biasanya mengasumsikan bahwa API yang diperlukan sudah aktif di project Google Cloud Anda.

Membuat kueri tabel objek

Anda dapat membuat kueri tabel objek seperti BigQuery lainnya, misalnya:

SELECT *
FROM mydataset.myobjecttable;

Membuat kueri tabel objek akan menampilkan metadata untuk objek yang mendasarinya. Untuk mengetahui informasi selengkapnya, lihat Skema tabel objek.

Langkah selanjutnya

• Pelajari cara menjalankan inferensi pada tabel objek gambar.
• Pelajari cara menganalisis tabel objek menggunakan fungsi jarak jauh.