이 페이지는 Cloud Translation API를 통해 번역되었습니다.

기본 연결 개요

워크플로를 간소화하려면 외부 테이블 및 BigQuery ML 원격 모델을 만들기 위해 BigQuery에서 기본 Cloud 리소스 연결을 구성할 수 있습니다. 관리자가 기본 연결을 구성하면 사용자는 리소스 생성 중에 연결 세부정보를 지정할 필요 없이 이를 참조할 수 있습니다.

BigQuery는 다음 리소스의 기본 연결을 지원합니다.

기본 연결을 사용하려면 다음 SQL 절에 DEFAULT 키워드를 지정합니다.

CREATE EXTERNAL TABLE 문의 WITH CONNECTION 절
원격 모델의 CREATE MODEL 문의 REMOTE WITH CONNECTION 절

시작하기 전에

Enable the BigQuery Connection API.

Enable the API

필수 역할 및 권한

기본 연결을 사용하려면 다음 Identity and Access Management (IAM) 역할을 사용하세요.

프로젝트에서 기본 연결인 BigQuery 연결 사용자(roles/bigquery.connectionUser) 사용
기본 연결 설정: 프로젝트의 BigQuery 관리자 (roles/bigquery.admin)
기본 연결의 서비스 계정에 권한을 부여해야 하는 경우 다음 단계를 따르세요.
- 기본 연결이 외부 테이블을 만드는 데 사용되는 경우: 외부 테이블에서 사용하는 모든 Cloud Storage 버킷의 스토리지 관리자 (roles/storage.admin)
- 기본 연결이 원격 모델을 만드는 데 사용되는 경우: Vertex AI 엔드포인트가 포함된 프로젝트의 프로젝트 IAM 관리자 (roles/resourcemanager.projectIamAdmin) 다음 유형의 원격 모델의 경우 현재 프로젝트는 다음과 같습니다.
  - Cloud AI 서비스를 통한 원격 모델
  - 모델 이름을 엔드포인트로 지정하여 만든 Google 또는 파트너 모델을 통한 원격 모델
  다른 모든 원격 모델의 경우 대상 모델이 배포된 Vertex AI 엔드포인트가 포함된 프로젝트입니다.
  
  원격 모델을 사용하여 객체 테이블의 비정형 데이터를 분석하는 경우 객체 테이블에서 사용하는 Cloud Storage 버킷이 Vertex AI 엔드포인트와 다른 프로젝트에 있는 경우 객체 테이블에서 사용하는 Cloud Storage 버킷에 스토리지 관리자 (roles/storage.admin)도 있어야 합니다.
기본 연결로 사용하기 위해 연결을 구성하는 관리자 또는 아직 서비스 계정에 적절한 역할이 부여되지 않은 기본 연결을 사용하는 사용자인 경우에만 이러한 역할이 필요합니다. 자세한 내용은 기본 연결 구성을 참고하세요.

이러한 사전 정의된 역할에는 이 문서의 작업을 수행하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 확장하세요.

필수 권한

기본 연결 사용: bigquery.connections.use
연결 만들기: bigquery.connections.*
기본 연결을 설정합니다. bigquery.config.*
외부 테이블을 만드는 데 사용되는 기본 연결(storage.buckets.getIamPolicy 및 storage.buckets.setIamPolicy)의 서비스 계정 권한을 설정합니다.
원격 모델을 만드는 데 사용되는 기본 연결의 서비스 계정 권한을 설정합니다.
- resourcemanager.projects.getIamPolicy 및 resourcemanager.projects.setIamPolicy
- 기본 연결이 객체 테이블의 비정형 데이터를 처리하는 원격 모델과 함께 사용되는 경우 storage.buckets.getIamPolicy 및 storage.buckets.setIamPolicy

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

기본 연결 구성

기본 연결을 처음으로 구성하려면 다음 방법 중 하나를 사용하세요.

연결을 만들고 연결의 서비스 계정에 적절한 역할을 부여한 후 연결을 기본 연결로 설정합니다.

기본 연결을 만들고 구성하는 사용자에게는 BigQuery 관리자 역할과 저장소 관리자 또는 프로젝트 IAM 관리자 역할이 필요합니다(해당하는 경우). 기본 연결 사용자에게는 BigQuery 연결 사용자 역할이 필요합니다.
연결을 만든 다음 기본 연결로 설정합니다. 기본 연결이 사용되면 서비스는 기본 연결의 서비스 계정에 적절한 역할을 부여합니다.

기본 연결을 만들고 설정하는 사용자에게는 BigQuery 관리자 역할이 필요합니다. 기본 연결 사용자에게는 BigQuery 연결 사용자 역할과 저장소 관리자 또는 프로젝트 IAM 관리자 역할이 필요합니다(해당하는 경우).
지원되는 문에 DEFAULT 키워드를 지정합니다. 서비스는 연결을 만들고 연결의 서비스 계정에 적절한 역할을 부여한 후 연결을 기본 연결로 설정합니다.

기본 연결 사용자에게는 BigQuery 관리자 역할과 저장소 관리자 또는 프로젝트 IAM 관리자 역할이 필요합니다(해당하는 경우).

프로젝트의 기본 연결 설정

ALTER PROJECT SET OPTIONS DDL 문을 사용하여 프로젝트의 기본 Cloud 리소스 연결을 설정합니다.

다음 예에서는 프로젝트의 기본 연결을 설정합니다.

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

다음을 바꿉니다.

PROJECT_ID: 기본 연결을 설정하는 프로젝트의 ID입니다.
REGION: 연결의 리전
CONNECTION_ID: 테이블 및 모델의 기본값으로 사용할 연결의 ID 또는 이름입니다. 연결 ID 또는 이름만 지정하고 이름 또는 ID에 연결된 프로젝트 ID 및 리전 접두사는 제외합니다.

프로젝트의 기본 연결을 구성하는 방법에 관한 자세한 내용은 기본 구성 관리를 참고하세요.

기본 연결의 권한 프로비저닝

기본 연결을 사용하여 외부 테이블 또는 원격 모델을 만들 때 서비스 계정에 아직 적절한 역할이 없는 경우Google Cloud 는 기본 연결의 서비스 계정에 적절한 역할을 부여합니다. 외부 테이블 또는 원격 모델에서 사용하는 Cloud Storage 또는 Vertex AI 리소스에 대한 관리 권한이 없는 경우 이 작업이 실패합니다.

기본 연결의 서비스 계정에 다음 역할이 부여됩니다.

테이블 또는 모델 유형	원격 리소스	연결의 서비스 계정에 할당된 역할
Cloud Storage BigLake 테이블	Cloud Storage	`roles/storage.legacyBucketReader` `roles/storage.legacyObjectReader`
객체 테이블	Cloud Storage	`roles/storage.legacyBucketReader` `roles/storage.legacyObjectReader`
BigQuery의 BigLake Iceberg 테이블	Cloud Storage	`roles/storage.legacyBucketWriter` `roles/storage.legacyObjectOwner`
Vertex AI 모델을 통한 BigQuery ML 원격 모델	Google 소유 모델	`roles/aiplatform.user`
	Model Garden에서 엔드포인트에 배포 가능
	사용자 모델
	미세 조정된 모델	`roles/aiplatform.serviceAgent`
Cloud AI 서비스를 통한 BigQuery ML 원격 모델	문서 프로세서	`roles/documentai.apiUser`
	음성 인식기	`roles/speech.serviceAgent`
	Cloud NLP	`roles/serviceusage.serviceUsageConsumer`
	Cloud Vision	`roles/serviceusage.serviceUsageConsumer`
	Cloud Translation	`roles/cloudtranslate.user`

`CONNECTION DEFAULT`를 사용하여 외부 테이블 만들기

다음 예는 BigQuery에서 WITH CONNECTION DEFAULT를 지정하여 외부 테이블을 만드는 방법을 보여줍니다.

예: Cloud Storage BigLake 테이블 만들기

다음 SQL 표현식은 기본 연결을 사용하여 Cloud Storage BigLake 테이블을 만듭니다.

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

예: 기본 연결로 객체 테이블 만들기

다음 SQL 표현식은 기본 연결을 사용하여 객체 테이블을 만듭니다.

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

예: 기본 연결을 사용하여 BigQuery에서 BigLake Iceberg 테이블 만들기

다음 SQL 표현식은 기본 연결을 사용하여 BigQuery의 BigLake Iceberg 테이블을 만듭니다.

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');

`REMOTE WITH CONNECTION DEFAULT`를 사용하여 원격 모델 만들기

다음 예에서는 BigQuery에서 REMOTE WITH CONNECTION DEFAULT를 지정하여 원격 모델을 만드는 방법을 보여줍니다.

예: Vertex AI 모델을 통해 원격 모델 만들기

다음 SQL 표현식은 기본 연결을 사용하여 원격 모델을 만듭니다.

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

예: Cloud AI 서비스를 통해 원격 모델 만들기

다음 SQL 표현식은 기본 연결을 사용하여 Cloud AI 서비스에 대한 원격 모델을 만듭니다.

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

예: HTTPS 엔드포인트로 원격 모델 만들기

다음 SQL 표현식은 HTTPS 엔드포인트가 있는 원격 모델과 기본 연결을 만듭니다.

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')

다음 단계

BigQuery의 기본 구성에 대해 알아보세요.