Ringkasan koneksi default

Untuk menyederhanakan alur kerja, Anda dapat mengonfigurasi koneksi resource Cloud default di BigQuery untuk membuat tabel eksternal dan model jarak jauh BigQuery ML. Administrator mengonfigurasi koneksi default, lalu pengguna dapat mereferensikannya selama pembuatan resource, bukan harus menentukan detail koneksi.

BigQuery mendukung koneksi default di resource berikut:

• Tabel BigLake Cloud Storage
• Tabel objek
• Tabel BigLake untuk Apache Iceberg di BigQuery
• Model jarak jauh

Untuk menggunakan koneksi default, tentukan kata kunci DEFAULT dalam klausa SQL berikut:

• Klausul WITH CONNECTION dari pernyataan CREATE EXTERNAL TABLE
• Klausa REMOTE WITH CONNECTION dari pernyataan CREATE MODEL untuk model jarak jauh

Sebelum memulai

Enable the BigQuery Connection API.

Enable the API

Peran dan izin yang diperlukan

Untuk menggunakan koneksi default, gunakan peran Identity and Access Management (IAM) berikut:

• Gunakan koneksi default: Pengguna Koneksi BigQuery (roles/bigquery.connectionUser) di project Anda
• Tetapkan koneksi default: BigQuery Admin (roles/bigquery.admin) di project Anda

• Jika perlu memberikan izin ke akun layanan koneksi default:

  • Jika koneksi default digunakan untuk membuat tabel eksternal: Storage Admin (roles/storage.admin) di bucket Cloud Storage apa pun yang digunakan oleh tabel eksternal.

  • Jika koneksi default digunakan untuk membuat model jarak jauh: Project IAM Admin (roles/resourcemanager.projectIamAdmin) di project yang berisi endpoint Vertex AI. Untuk jenis model jarak jauh berikut, ini adalah project saat ini:

    • Model jarak jauh melalui layanan Cloud AI.
    • Model jarak jauh melalui model Google atau partner yang Anda buat dengan menentukan nama model sebagai endpoint.

    Untuk semua model jarak jauh lainnya, ini adalah project yang berisi endpoint Vertex AI tempat model target di-deploy.

    Jika Anda menggunakan model jarak jauh untuk menganalisis data tidak terstruktur dari tabel objek, dan bucket Cloud Storage yang Anda gunakan dalam tabel objek berada dalam project yang berbeda dengan endpoint Vertex AI, Anda juga harus memiliki Storage Admin (roles/storage.admin) di bucket Cloud Storage yang digunakan oleh tabel objek.

  Anda hanya memerlukan peran ini jika Anda adalah administrator yang mengonfigurasi koneksi untuk digunakan sebagai koneksi default, atau pengguna yang menggunakan koneksi default yang belum memiliki peran yang sesuai yang diberikan ke akun layanannya. Untuk informasi selengkapnya, lihat Mengonfigurasi koneksi default.

Peran yang telah ditetapkan ini berisi izin yang diperlukan untuk melakukan tugas dalam dokumen ini. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

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

Mengonfigurasi koneksi default

Untuk mengonfigurasi koneksi default untuk pertama kalinya, gunakan salah satu metode berikut:

• Buat koneksi, berikan peran yang sesuai ke akun layanan koneksi, lalu tetapkan koneksi sebagai koneksi default.

  Pengguna yang membuat dan mengonfigurasi koneksi default memerlukan peran BigQuery Admin dan peran Storage Admin atau Project IAM Admin, sesuai kebutuhan. Pengguna koneksi default memerlukan peran BigQuery Connection User.

• Buat koneksi, lalu tetapkan sebagai koneksi default. Layanan ini memberikan peran yang sesuai ke akun layanan koneksi default saat koneksi default digunakan.

  Pengguna yang membuat dan menetapkan koneksi default memerlukan peran Admin BigQuery. Pengguna koneksi default memerlukan peran BigQuery Connection User dan peran Storage Admin atau Project IAM Admin, sebagaimana mestinya.

• Tentukan kata kunci DEFAULT dalam pernyataan yang didukung. Layanan ini membuat koneksi, memberikan peran yang sesuai ke akun layanan koneksi, lalu menetapkan koneksi sebagai koneksi default.

  Pengguna koneksi default memerlukan peran BigQuery Admin dan peran Storage Admin atau Project IAM Admin, sebagaimana mestinya.

Menetapkan koneksi default untuk project

Tetapkan koneksi resource Cloud default untuk project menggunakan pernyataan DDL ALTER PROJECT SET OPTIONS.

Contoh berikut menetapkan koneksi default untuk project:

  ALTER PROJECT PROJECT_ID
  SET OPTIONS (
    `region-REGION.default_cloud_resource_connection_id` = CONNECTION_ID);
  

Ganti kode berikut:

• PROJECT_ID: ID project tempat Anda menetapkan koneksi default.
• REGION: region koneksi.
• CONNECTION_ID: ID atau nama koneksi yang akan digunakan sebagai default untuk tabel dan model. Hanya tentukan ID atau nama koneksi, dan kecualikan project ID dan awalan region yang dilampirkan ke nama atau ID.

Untuk informasi selengkapnya tentang cara mengonfigurasi koneksi default untuk project, lihat Mengelola konfigurasi default.

Penyediaan izin untuk koneksi default

Saat Anda menggunakan koneksi default untuk membuat tabel eksternal atau model jarak jauh, Google Cloud akan memberikan peran yang sesuai kepada akun layanan koneksi default jika akun layanan belum memilikinya. Tindakan ini gagal jika Anda tidak memiliki hak istimewa administratif pada resource Cloud Storage atau Vertex AI yang digunakan oleh tabel eksternal atau model jarak jauh.

Peran berikut diberikan ke akun layanan koneksi default:

Membuat tabel eksternal menggunakan CONNECTION DEFAULT

Contoh berikut menunjukkan cara membuat tabel eksternal dengan menentukan WITH CONNECTION DEFAULT di BigQuery.

Contoh: Membuat tabel BigLake Cloud Storage

Ekspresi SQL berikut membuat tabel BigLake Cloud Storage dengan koneksi default:

CREATE EXTERNAL TABLE PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME
WITH CONNECTION DEFAULT
OPTIONS (
  format = 'TABLE_FORMAT',
  uris = ['BUCKET_PATH']);

Contoh: Membuat tabel objek dengan koneksi default

Ekspresi SQL berikut membuat tabel objek dengan koneksi default:

CREATE EXTERNAL TABLE PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME
WITH CONNECTION DEFAULT
OPTIONS (
  object_metadata = 'SIMPLE'
  uris = ['BUCKET_PATH']);

Contoh: Membuat tabel BigLake Iceberg di BigQuery dengan koneksi default

Ekspresi SQL berikut membuat tabel BigLake Iceberg di BigQuery dengan koneksi default:

CREATE TABLE `myproject.tpch_clustered.nation` (
  n_nationkey integer,
  n_name string,
  n_regionkey integer,
  n_comment string)
CLUSTER BY n_nationkey
WITH CONNECTION DEFAULT
OPTIONS (
  file_format = 'PARQUET',
  table_format = 'ICEBERG',
  storage_uri = 'gs://mybucket/warehouse/nation');

Membuat model jarak jauh menggunakan REMOTE WITH CONNECTION DEFAULT

Contoh berikut menunjukkan cara membuat model jarak jauh dengan menentukan REMOTE WITH CONNECTION DEFAULT di BigQuery.

Contoh: Membuat model jarak jauh melalui model Vertex AI

Ekspresi SQL berikut membuat model jarak jauh dengan koneksi default:

CREATE OR REPLACE MODEL `mydataset.flash_model`
  REMOTE WITH CONNECTION DEFAULT
  OPTIONS(ENDPOINT = 'gemini-2.0-flash');

Contoh: Membuat model jarak jauh melalui layanan Cloud AI

Ekspresi SQL berikut membuat model jarak jauh melalui layanan Cloud AI dengan koneksi default:

CREATE MODEL `project_id.mydataset.mymodel`
REMOTE WITH CONNECTION DEFAULT
 OPTIONS(REMOTE_SERVICE_TYPE = 'CLOUD_AI_VISION_V1')

Contoh: Membuat model jarak jauh dengan endpoint HTTPS

Ekspresi SQL berikut membuat model jarak jauh dengan endpoint HTTPS dan koneksi default:

CREATE MODEL `project_id.mydataset.mymodel`
 INPUT(f1 INT64, f2 FLOAT64, f3 STRING, f4 ARRAY)
 OUTPUT(out1 INT64, out2 INT64)
 REMOTE WITH CONNECTION DEFAULT
 OPTIONS(ENDPOINT = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/endpoints/1234')

Langkah berikutnya

• Pelajari konfigurasi default di BigQuery.