Amazon S3 BigLake 테이블 만들기

이 문서에서는 Amazon Simple Storage Service(Amazon S3) BigLake 테이블을 만드는 방법을 설명합니다. BigLake 테이블을 사용하면 액세스 위임을 통해 Amazon S3의 데이터를 쿼리할 수 있습니다. 액세스 위임은 BigLake 테이블에 대한 액세스 권한을 기본 데이터 스토어에 대한 액세스 권한과 분리합니다.

BigQuery와 Amazon S3 간의 데이터 흐름 방식에 대한 자세한 내용은 데이터 쿼리 시 데이터 흐름을 참조하세요.

시작하기 전에

Amazon S3 데이터에 액세스할 수 있는 연결이 있는지 확인합니다.

필요한 역할

외부 테이블을 만드는 데 필요한 권한을 얻으려면 관리자에게 데이터 세트에 대한 BigQuery 관리자(roles/bigquery.admin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 외부 테이블을 만드는 데 필요한 권한이 포함됩니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 확장하세요.

필수 권한

외부 테이블을 만들려면 다음 권한이 필요합니다.

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

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

데이터 세트 생성

외부 테이블을 만들기 전에 지원되는 리전에 데이터 세트를 만들어야 합니다. 다음 옵션 중 하나를 선택합니다.

콘솔

  1. BigQuery 페이지로 이동합니다.

    BigQuery로 이동

  2. 탐색기 창에서 데이터 세트를 만들 프로젝트를 선택합니다.
  3. 작업 보기 옵션을 확장하고 데이터 세트 만들기를 클릭합니다.
  4. 데이터 세트 만들기 페이지에서 다음 세부정보를 지정합니다.
    1. 데이터 세트 ID에 고유한 데이터 세트 이름을 입력합니다.
    2. 데이터 위치에서 지원되는 리전을 선택합니다.
    3. 선택사항: 테이블을 자동으로 삭제하려면 테이블 만료 시간 설정 체크박스를 선택하고 기본 최대 테이블 기간을 일 단위로 설정합니다. 테이블이 만료될 때 Amazon S3의 데이터는 삭제되지 않습니다.
    4. 기본 콜레이션을 사용하려면 고급 옵션 섹션을 펼친 다음 기본 콜레이션 사용 설정 옵션을 선택합니다.
    5. 데이터 세트 만들기를 클릭합니다.

SQL

CREATE SCHEMA DDL 문을 사용합니다. 다음 예시에서는 aws-us-east-1 리전에 데이터 세트를 만듭니다.

  1. Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.

    BigQuery로 이동

  2. 쿼리 편집기에서 다음 문을 입력합니다.

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

  3. 실행을 클릭합니다.

쿼리를 실행하는 방법에 대한 자세한 내용은 대화형 쿼리 실행을 참조하세요.

bq

명령줄 환경에서 bq mk 명령어를 사용하여 데이터 세트를 만듭니다.

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

--project_id 매개변수는 기본 프로젝트를 재정의합니다.

다음을 바꿉니다.

  • LOCATION: 데이터 세트 위치

    지원되는 리전에 대한 자세한 내용은 위치를 참조하세요. 데이터 세트를 만든 후에는 위치를 변경할 수 없습니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.

  • PROJECT_ID: 프로젝트 ID입니다.

  • DATASET_NAME: 만들려는 데이터 세트의 이름입니다.

    기본 프로젝트가 아닌 다른 프로젝트에서 데이터 세트를 만들려면 해당 프로젝트 ID를 PROJECT_ID:DATASET_NAME 형식으로 데이터 세트 이름에 추가합니다.

자바

이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용Java 설정 안내를 따르세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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());
    }
  }
}

파티션을 나누지 않은 데이터에 BigLake 테이블 만들기

다음 옵션 중 하나를 선택합니다.

콘솔

  1. BigQuery 페이지로 이동합니다.

    BigQuery로 이동

  2. 탐색기 창에서 프로젝트를 펼친 후 데이터 세트를 선택합니다.

  3. 데이터 세트 정보 섹션에서 테이블 만들기를 클릭합니다.

  4. 테이블 만들기 페이지의 소스 섹션에서 다음을 수행합니다.

    1. 다음 항목으로 테이블 만들기에서 Amazon S3을 선택합니다.
    2. S3 경로 선택s3://BUCKET_NAME/PATH 형식으로 Amazon S3 데이터를 가리키는 URI를 입력합니다. BUCKET_NAME을 Amazon S3 버킷 이름으로 바꿉니다. 버킷 리전은 데이터 세트의 리전과 동일해야 합니다. PATH를 내보낸 파일을 쓰려는 경로로 바꿉니다. 와일드 카드 1개(*)를 포함할 수 있습니다.
    3. 파일 형식에 Amazon S3의 데이터 형식을 선택합니다. 지원되는 형식은 AVRO, PARQUET, ORC, CSV, JSONL(줄바꿈으로 구분된 JSON)입니다.
  5. 대상 섹션에서 다음 세부정보를 지정합니다.

    1. 데이터 세트에서 적절한 데이터 세트를 선택합니다.
    2. 테이블 필드에 테이블 이름을 입력합니다.
    3. 테이블 유형외부 테이블로 설정되어 있는지 확인합니다.
    4. 연결 ID의 경우 드롭다운에서 적절한 연결 ID를 선택합니다. 연결에 대한 자세한 내용은 Amazon S3에 연결을 참조하세요.
  6. 스키마 섹션에서 스키마 자동 감지를 사용 설정하거나 소스 파일이 있는 경우 스키마를 수동으로 지정할 수 있습니다. 소스 파일이 없으면 스키마를 수동으로 지정해야 합니다.

    • 스키마 자동 감지를 사용 설정하려면 자동 감지 옵션을 선택합니다.

    • 스키마를 수동으로 지정하려면 자동 감지 옵션을 선택 해제한 상태로 둡니다. 텍스트로 편집을 사용 설정하고 테이블 스키마를 JSON 배열로 입력합니다.

  7. 테이블 만들기를 클릭합니다.

SQL

BigLake 테이블을 만들려면 WITH CONNECTION 절이 있는 CREATE EXTERNAL TABLE을 사용합니다.

  1. Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.

    BigQuery로 이동

  2. 쿼리 편집기에서 다음 문을 입력합니다.

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

    다음을 바꿉니다.

    • DATASET_NAME: 사용자가 만든 데이터 세트의 이름
    • TABLE_NAME: 이 테이블에 지정할 이름
    • AWS_LOCATION: Google Cloud의 AWS 위치(예: `aws-us-east-1`)
    • CONNECTION_NAME: 사용자가 만든 연결의 이름
    • DATA_FORMAT: 지원되는 BigQuery 제휴 형식(예: AVRO, CSV 또는 DELTA_LAKE(미리보기))
    • S3_URI: Amazon S3 데이터를 가리키는 URI(예: s3://bucket/path)
    • STALENESS_INTERVAL: 캐시된 메타데이터가 BigLake 테이블에 대한 작업에서 사용되는지 여부와 작업이 사용하기 위해 캐시된 메타데이터가 작업에서 사용되려면 얼마나 최신이어야 하는지를 지정합니다. 메타데이터 캐싱 고려사항에 대한 자세한 내용은 성능을 위한 메타데이터 캐싱을 참조하세요.

      메타데이터 캐싱을 사용 중지하려면 0을 지정합니다. 이 값이 기본값입니다.

      메타데이터 캐싱을 사용 설정하려면 30분에서 7일 사이의 간격 리터럴 값을 지정합니다. 예를 들어 4시간 비활성 간격의 경우 INTERVAL 4 HOUR를 지정합니다. 이 값을 사용하면 지난 4시간 이내에 새로고침된 경우 테이블에 대한 작업이 캐시된 메타데이터를 사용합니다. 캐시된 메타데이터가 이보다 오래된 경우 작업은 대신 Amazon S3에서 메타데이터를 검색합니다.

    • CACHE_MODE: 메타데이터 캐시를 자동 또는 수동으로 새로고침할지 지정합니다. 메타데이터 캐싱 고려사항에 대한 자세한 내용은 성능을 위한 메타데이터 캐싱을 참조하세요.

      시스템 정의 간격(일반적으로 30~60분)으로 메타데이터 캐시를 새로고침하려면 AUTOMATIC으로 설정합니다.

      지정한 일정에 따라 메타데이터 캐시를 새로고침하려면 MANUAL로 설정합니다. 이 경우 BQ.REFRESH_EXTERNAL_METADATA_CACHE 시스템 프로시져를 호출하여 캐시를 새로고침할 수 있습니다.

      STALENESS_INTERVAL이 0보다 큰 값으로 설정된 경우 CACHE_MODE를 설정해야 합니다.

  3. 실행을 클릭합니다.

쿼리를 실행하는 방법에 대한 자세한 내용은 대화형 쿼리 실행을 참조하세요.

예:

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

테이블 정의 파일을 만듭니다.


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

다음을 바꿉니다.

  • DATA_FORMAT: 지원되는 BigQuery 제휴 형식(예: AVRO 또는 CSV)
  • S3_URI: Amazon S3 데이터를 가리키는 URI(예: s3://bucket/path)
  • AWS_LOCATION: Google Cloud의 AWS 위치(예: aws-us-east-1)
  • CONNECTION_NAME: 사용자가 만든 연결의 이름

  • CACHE_MODE: 메타데이터 캐시를 자동 또는 수동으로 새로고침할지 지정합니다. 후속 bq mk 명령어에서 --max_staleness 플래그를 사용하여 메타데이터 캐싱을 사용 설정하려는 경우에만 이 플래그를 포함해야 합니다. 메타데이터 캐싱 고려사항에 대한 자세한 내용은 성능을 위한 메타데이터 캐싱을 참조하세요.

    시스템 정의 간격(일반적으로 30~60분)으로 메타데이터 캐시를 새로고침하려면 AUTOMATIC으로 설정합니다.

    지정한 일정에 따라 메타데이터 캐시를 새로고침하려면 MANUAL로 설정합니다. 이 경우 BQ.REFRESH_EXTERNAL_METADATA_CACHE 시스템 프로시저를 호출하여 캐시를 새로고침할 수 있습니다. STALENESS_INTERVAL이 0보다 큰 값으로 설정된 경우 CACHE_MODE를 설정해야 합니다.

그런 다음 BigLake 테이블을 만듭니다.

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

다음을 바꿉니다.

  • STALENESS_INTERVAL: 캐시된 메타데이터가 BigLake 테이블에 대한 작업에서 사용되는지 여부와 작업이 사용하기 위해 캐시된 메타데이터가 작업에서 사용되려면 얼마나 최신이어야 하는지를 지정합니다. 메타데이터 캐싱 고려사항에 대한 자세한 내용은 성능을 위한 메타데이터 캐싱을 참조하세요.

    메타데이터 캐싱을 사용 중지하려면 0을 지정합니다. 이 값이 기본값입니다.

    메타데이터 캐싱을 사용 설정하려면 30분에서 7일 사이의 간격 리터럴 값을 지정합니다. 예를 들어 4시간 비활성 간격의 경우 INTERVAL 4 HOUR을 지정합니다. 이 값을 사용하면 지난 4시간 이내에 새로고침된 경우 테이블에 대한 작업이 캐시된 메타데이터를 사용합니다. 캐시된 메타데이터가 이보다 오래된 경우 작업은 대신 Amazon S3에서 메타데이터를 검색합니다.

  • DATASET_NAME: 사용자가 만든 데이터 세트의 이름

  • TABLE_NAME: 이 테이블에 지정할 이름

예를 들어 다음 명령어는 새 BigLake 테이블 awsdataset.awstable을 만들며, 이 테이블은 s3://s3-bucket/path/file.csv 경로에 저장된 Amazon S3 데이터를 쿼리할 수 있고 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

tables.insert API 메서드를 호출하여, 전달한 Table 리소스ExternalDataConfiguration을 생성합니다.

schema 속성을 지정하거나 autodetect 속성을 true로 설정하여 지원되는 데이터 소스에 스키마 자동 감지를 사용 설정합니다.

Amazon S3에 연결하는 데 사용할 연결을 식별하려면 connectionId 속성을 지정합니다.

자바

이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용Java 설정 안내를 따르세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.

BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

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());
    }
  }
}

파티션을 나눈 데이터에 BigLake 테이블 만들기

Amazon S3에서 Hive 파티션을 나눈 데이터에 대한 BigLake 테이블을 만들 수 있습니다. 외부에서 파티션을 나눈 테이블을 만든 후에는 파티션 키를 변경할 수 없습니다. 파티션을 변경하려면 테이블을 다시 만들어야 합니다.

Hive 파티션을 나눈 데이터를 기반으로 BigLake 테이블을 만들려면 다음 옵션 중 하나를 선택합니다.

콘솔

  1. BigQuery 페이지로 이동합니다.

    BigQuery로 이동

  2. 탐색기 창에서 프로젝트를 확장하고 데이터 세트를 선택합니다.

  3. 작업 보기를 클릭한 후 테이블 만들기를 클릭합니다. 그러면 테이블 만들기 창이 열립니다.

  4. 소스 섹션에서 다음 세부정보를 지정합니다.

    1. 다음 항목으로 테이블 만들기에서 Amazon S3을 선택합니다.

    2. 와일드 카드를 사용하여 폴더 경로를 제공합니다. 예를 들면 s3://mybucket/*입니다.

      폴더는 생성, 추가 또는 덮어쓰려는 테이블이 포함된 데이터 세트와 동일한 위치에 있어야 합니다.

    3. 파일 형식 목록에서 파일 유형을 선택합니다.

    4. 소스 데이터 파티션 나누기 체크박스를 선택한 후 다음 세부정보를 지정합니다.

      1. 소스 URI 프리픽스 선택에 URI 프리픽스를 입력합니다. 예를 들면 s3://mybucket/my_files입니다.
      2. 선택사항: 이 테이블의 모든 쿼리에 파티션 필터가 필요하면 파티션 필터 필요 체크박스를 선택합니다. 파티션 필터를 필수항목으로 설정하면 비용을 줄이고 성능을 높일 수 있습니다. 자세한 내용은 쿼리에서 파티션 키에 조건자 필터 필요를 참조하세요.
      3. 파티션 추론 모드 섹션에서 다음 옵션 중 하나를 선택합니다.

        • 유형을 자동으로 추론: 파티션 스키마 감지 모드를 AUTO로 설정합니다.
        • 모든 열은 문자열: 파티션 스키마 감지 모드를 STRINGS로 설정합니다.
        • 직접 제공: 파티션 스키마 감지 모드를 CUSTOM으로 설정하고 파티션 키의 스키마 정보를 직접 입력합니다. 자세한 내용은 커스텀 파티션 키 스키마 제공을 참조하세요.
  5. 대상 섹션에서 다음 세부정보를 지정합니다.

    1. 프로젝트에서 테이블을 만들 프로젝트를 선택합니다.
    2. 데이터 세트에서 테이블을 만들 데이터 세트를 선택합니다.
    3. 테이블에 만들 테이블의 이름을 입력합니다.
    4. 테이블 유형에서 외부 테이블이 선택되었는지 확인합니다.
    5. 연결 ID에 대해 이전에 만든 연결을 선택합니다.
  6. 스키마 섹션에서 스키마 자동 감지를 사용 설정하거나 소스 파일이 있는 경우 스키마를 수동으로 지정할 수 있습니다. 소스 파일이 없으면 스키마를 수동으로 지정해야 합니다.

    • 스키마 자동 감지를 사용 설정하려면 자동 감지 옵션을 선택합니다.

    • 스키마를 수동으로 지정하려면 자동 감지 옵션을 선택 해제한 상태로 둡니다. 텍스트로 편집을 사용 설정하고 테이블 스키마를 JSON 배열로 입력합니다.

  7. 스키마와 일치하지 않는 추가 열 값이 있는 행을 무시하려면 고급 옵션 섹션을 펼치고 알 수 없는 값을 선택합니다.

  8. 테이블 만들기를 클릭합니다.

SQL

CREATE EXTERNAL TABLE DDL 문을 사용합니다.

  1. Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.

    BigQuery로 이동

  2. 쿼리 편집기에서 다음 문을 입력합니다.

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

    다음을 바꿉니다.

    • PROJECT_ID: 테이블을 만들 프로젝트의 이름(예: myproject)
    • DATASET: 테이블을 만들 BigQuery 데이터 세트의 이름(예: mydataset)
    • EXTERNAL_TABLE_NAME: 만들려는 테이블의 이름(예: mytable)
    • PARTITION_COLUMN: 파티션 나누기 열의 이름
    • PARTITION_COLUMN_TYPE: 파티션 나누기 열의 유형
    • REGION: 연결이 포함된 리전(예: us)
    • CONNECTION_ID: 연결의 이름(예: myconnection)
    • HIVE_PARTITION_URI_PREFIX: 하이브 파티션 나누기 URI 프리픽스. 예를 들면 s3://mybucket/입니다.
    • FILE_PATH: 만들려는 외부 테이블의 데이터 소스 경로(예: s3://mybucket/*.parquet)
    • TABLE_FORMAT: 만들려는 테이블의 형식(예: PARQUET)
    • STALENESS_INTERVAL: 캐시된 메타데이터가 BigLake 테이블에 대한 작업에서 사용되는지 여부와 작업이 사용하기 위해 캐시된 메타데이터가 작업에서 사용되려면 얼마나 최신이어야 하는지를 지정합니다. 메타데이터 캐싱 고려사항에 대한 자세한 내용은 성능을 위한 메타데이터 캐싱을 참조하세요.

      메타데이터 캐싱을 사용 중지하려면 0을 지정합니다. 이 값이 기본값입니다.

      메타데이터 캐싱을 사용 설정하려면 30분에서 7일 사이의 간격 리터럴 값을 지정합니다. 예를 들어 4시간 비활성 간격의 경우 INTERVAL 4 HOUR를 지정합니다. 이 값을 사용하면 지난 4시간 이내에 새로고침된 경우 테이블에 대한 작업이 캐시된 메타데이터를 사용합니다. 캐시된 메타데이터가 이보다 오래된 경우 작업은 대신 Amazon S3에서 메타데이터를 검색합니다.

    • CACHE_MODE: 메타데이터 캐시를 자동 또는 수동으로 새로고침할지 지정합니다. 메타데이터 캐싱 고려사항에 대한 자세한 내용은 성능을 위한 메타데이터 캐싱을 참조하세요.

      시스템 정의 간격(일반적으로 30~60분)으로 메타데이터 캐시를 새로고침하려면 AUTOMATIC으로 설정합니다.

      지정한 일정에 따라 메타데이터 캐시를 새로고침하려면 MANUAL로 설정합니다. 이 경우 BQ.REFRESH_EXTERNAL_METADATA_CACHE 시스템 프로시져를 호출하여 캐시를 새로고침할 수 있습니다.

      STALENESS_INTERVAL이 0보다 큰 값으로 설정된 경우 CACHE_MODE를 설정해야 합니다.

  3. 실행을 클릭합니다.

쿼리를 실행하는 방법에 대한 자세한 내용은 대화형 쿼리 실행을 참조하세요.

예시

다음 예시에서는 Amazon S3에서 파티션을 나눈 데이터에 대해 BigLake 테이블을 만듭니다. 스키마는 자동으로 감지됩니다.

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

먼저 bq mkdef 명령어를 사용하여 테이블 정의 파일을 만듭니다.

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

다음을 바꿉니다.

  • SOURCE_FORMAT: 외부 데이터 소스의 형식. 예를 들면 CSV입니다.
  • REGION: 연결이 포함된 리전(예: us)
  • CONNECTION_ID: 연결의 이름(예: myconnection)
  • PARTITIONING_MODE: Hive 파티션 나누기 모드. 다음 값 중 하나를 사용합니다.
    • AUTO: 키 이름과 유형을 자동으로 감지
    • STRINGS: 키 이름을 문자열로 자동으로 변환
    • CUSTOM: 소스 URI 프리픽스의 키 스키마를 인코딩
  • URI_SHARED_PREFIX: 소스 URI 프리픽스
  • BOOLEAN: 쿼리 시 조건자 필터를 요구할지 여부를 지정. 이 플래그는 선택사항입니다. 기본값은 false입니다.

  • CACHE_MODE: 메타데이터 캐시를 자동 또는 수동으로 새로고침할지 지정합니다. 후속 bq mk 명령어에서 --max_staleness 플래그를 사용하여 메타데이터 캐싱을 사용 설정하려는 경우에만 이 플래그를 포함해야 합니다. 메타데이터 캐싱 고려사항에 대한 자세한 내용은 성능을 위한 메타데이터 캐싱을 참조하세요.

    시스템 정의 간격(일반적으로 30~60분)으로 메타데이터 캐시를 새로고침하려면 AUTOMATIC으로 설정합니다.

    지정한 일정에 따라 메타데이터 캐시를 새로고침하려면 MANUAL로 설정합니다. 이 경우 BQ.REFRESH_EXTERNAL_METADATA_CACHE 시스템 프로시저를 호출하여 캐시를 새로고침할 수 있습니다. STALENESS_INTERVAL이 0보다 큰 값으로 설정된 경우 CACHE_MODE를 설정해야 합니다.

  • URIS: 와일드 카드 형식을 사용하는 Amazon S3 폴더의 경로입니다.

  • DEFINITION_FILE: 로컬 머신에 있는 테이블 정의 파일의 경로

PARTITIONING_MODECUSTOM이면 다음 형식을 사용하여 소스 URI 프리픽스에 파티션 키 스키마를 포함합니다.

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

테이블 정의 파일을 만든 후 bq mk 명령어를 사용하여 BigLake 테이블을 만듭니다.

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

다음을 바꿉니다.

  • STALENESS_INTERVAL: 캐시된 메타데이터가 BigLake 테이블에 대한 작업에서 사용되는지 여부와 작업이 사용하기 위해 캐시된 메타데이터가 작업에서 사용되려면 얼마나 최신이어야 하는지를 지정합니다. 메타데이터 캐싱 고려사항에 대한 자세한 내용은 성능을 위한 메타데이터 캐싱을 참조하세요.

    메타데이터 캐싱을 사용 중지하려면 0을 지정합니다. 이 값이 기본값입니다.

    메타데이터 캐싱을 사용 설정하려면 30분에서 7일 사이의 간격 리터럴 값을 지정합니다. 예를 들어 4시간 비활성 간격의 경우 INTERVAL 4 HOUR을 지정합니다. 이 값을 사용하면 지난 4시간 이내에 새로고침된 경우 테이블에 대한 작업이 캐시된 메타데이터를 사용합니다. 캐시된 메타데이터가 이보다 오래된 경우 작업은 대신 Amazon S3에서 메타데이터를 검색합니다.

  • DEFINITION_FILE: 테이블 정의 파일의 경로

  • DATASET_NAME: 테이블이 포함된 데이터 세트의 이름입니다.

  • TABLE_NAME: 생성할 테이블의 이름

  • SCHEMA: JSON 스키마 파일 경로를 지정하거나 field:data_type,field:data_type,... 형식으로 스키마를 지정합니다. 스키마 자동 감지를 사용하려면 이 인수를 생략하세요.

예시

다음 예시에서는 Amazon S3 데이터에 AUTO Hive 파티션 나누기 모드를 사용합니다.

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

다음 예시에서는 Amazon S3 데이터에 STRING Hive 파티션 나누기 모드를 사용합니다.

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

BigQuery API를 사용하여 Hive 파티션 나누기를 설정하려면 테이블 정의 파일을 만들 때 ExternalDataConfiguration 객체에 hivePartitioningOptions 객체를 포함하세요. BigLake 테이블을 만들려면 connectionId 필드의 값도 지정해야 합니다.

hivePartitioningOptions.mode 필드를 CUSTOM로 설정한 경우, hivePartitioningOptions.sourceUriPrefix 필드에 파티션 키 스키마를 인코딩해야 합니다(예: s3://BUCKET/PATH_TO_TABLE/{KEY1:TYPE1}/{KEY2:TYPE2}/...).

쿼리 시 조건자 필터를 사용하도록 하려면 hivePartitioningOptions.requirePartitionFilter 필드를 true로 설정합니다.

Delta Lake 테이블

이 미리보기에 등록하려면 다음 양식을 작성하세요.

이 기능에 대한 의견이나 지원을 요청하려면 bq-federated-formats@google.com으로 이메일을 보내세요.

Delta Lake는 페타바이트급 확장 데이터 테이블을 지원하는 오픈소스 테이블 형식입니다. Delta Lake 테이블은 임시 및 영구 테이블 모두로 쿼리할 수 있으며 BigLake 테이블로 지원됩니다.

스키마 동기화

Delta Lake는 메타데이터의 일부로 표준 스키마를 유지합니다. JSON 메타데이터 파일을 사용하여 스키마를 업데이트할 수는 없습니다. 스키마를 업데이트하려면 다음 안내를 따르세요.

  1. --autodetect_schema 플래그와 함께 bq update 명령어를 사용합니다.

    bq update --autodetect_schema
    PROJECT_ID:DATASET.TABLE
    

    다음을 바꿉니다.

    • PROJECT_ID: 업데이트할 테이블이 포함된 프로젝트 ID

    • DATASET: 업데이트할 테이블이 포함된 데이터 세트

    • TABLE: 스냅샷을 작성하려는 테이블

유형 변환

BigQuery는 Delta Lake 데이터 유형을 다음 BigQuery 데이터 유형으로 변환합니다.

Delta Lake 유형 BigQuery 유형
boolean BOOL
byte INT64
int INT64
long INT64
float FLOAT64
double FLOAT64
Decimal(P/S) 정밀도에 따라 NUMERIC 또는 BIG_NUMERIC
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>>

제한사항

다음 제한사항이 Delta Lake 테이블에 적용됩니다.

  • 외부 테이블 제한사항이 Delta Lake 테이블에 적용됩니다.

  • Delta Lake 테이블은 BigQuery Omni에서만 지원되며 관련 제한사항이 있습니다.

  • 새 JSON 메타데이터 파일로 테이블을 업데이트할 수는 없습니다. 스키마 테이블 업데이트 자동 감지 작업을 사용해야 합니다. 자세한 내용은 스키마 동기화를 참조하세요.

  • BigLake 보안 기능은 BigQuery 서비스를 통해 액세스할 때 Delta Lake 테이블만 보호합니다.

Delta Lake 테이블 만들기

다음 예시에서는 Delta Lake 형식의 CREATE EXTERNAL TABLE 문을 사용하여 외부 테이블을 만듭니다.

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

다음을 바꿉니다.

  • table_name: 테이블의 이름

  • connection_name: 연결의 이름입니다. 연결에서 Amazon S3 또는 Blob Storage 소스를 식별해야 합니다.

  • parent_directory: 상위 디렉터리의 URI입니다.

Delta Lake로 교차 클라우드 전송

다음 예시에서는 LOAD DATA 문을 사용하여 데이터를 적절한 테이블에 로드합니다.

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

교차 클라우드 데이터 전송에 대한 더 많은 예시를 보려면 교차 클라우드 운영으로 데이터 로드를 참조하세요.

BigLake 테이블 쿼리

자세한 내용은 Amazon S3 데이터 쿼리를 참조하세요.

리소스 메타데이터 보기

INFORMATION_SCHEMA 뷰로 리소스 메타데이터를 볼 수 있습니다. JOBS_BY_*, JOBS_TIMELINE_BY_*, RESERVATION* 보기를 쿼리할 때는 테이블 리전과 함께 배치된 쿼리의 처리 위치를 지정해야 합니다. BigQuery Omni 위치에 대한 자세한 내용은 위치를 참조하세요. 다른 모든 시스템 테이블의 경우 쿼리 작업 위치 지정은 선택사항입니다.

BigQuery Omni에서 지원되는 시스템 테이블에 대한 자세한 내용은 제한사항을 참조하세요.

JOBS_*RESERVATION* 시스템 테이블을 쿼리하려면 다음 방법 중 하나를 선택하여 처리 위치를 지정합니다.

콘솔

  1. BigQuery 페이지로 이동합니다.

    BigQuery로 이동

  2. 편집기 탭이 표시되지 않으면 새 쿼리 작성을 클릭합니다.

  3. 더보기 > 쿼리 설정을 클릭합니다. 쿼리 설정 대화상자가 열립니다.

  4. 쿼리 설정 대화상자의 추가 설정 > 데이터 위치에서 BigQuery Omni 리전과 함께 배치된 BigQuery 리전을 선택합니다. 예를 들어 BigQuery Omni 리전이 aws-us-east-1인 경우 us-east4를 지정합니다.

  5. 나머지 필드를 선택하고 저장을 클릭합니다.

bq

--location 플래그를 사용하여 작업 처리 위치를 BigQuery Omni 리전과 함께 배치된 BigQuery 리전으로 설정합니다. 예를 들어 BigQuery Omni 리전이 aws-us-east-1인 경우 us-east4를 지정합니다.

예시

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

프로그래매틱 방식으로 작업을 실행하는 경우 위치 인수를 BigQuery Omni 리전과 같은 위치에 배치된 BigQuery 리전으로 설정합니다. 예를 들어 BigQuery Omni 리전이 aws-us-east-1인 경우 us-east4를 지정합니다.

다음 예시는 메타데이터 새로고침 작업을 나열합니다.

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;

VPC 서비스 제어

VPC 서비스 제어 경계를 추가적인 방어 계층으로 사용하여 BigQuery Omni에서 외부 클라우드 서비스로의 액세스를 제한할 수 있습니다. 예를 들어 VPC 서비스 제어 경계를 사용하여 BigQuery Omni 테이블에서 특정 Amazon S3 버킷 또는 Blob Storage 컨테이너로 내보내기를 제한할 수 있습니다.

VPC 서비스 제어에 대한 자세한 내용은 VPC 서비스 제어 개요를 참조하세요.

필요한 권한

서비스 경계를 구성하는 데 필요한 권한이 있는지 확인합니다. VPC 서비스 제어를 구성하는 데 필요한 IAM 역할 목록을 보려면 VPC 서비스 제어 문서의 IAM으로 액세스 제어를 참조하세요.

Google Cloud 콘솔을 사용하여 VPC 서비스 제어 설정

  1. Google Cloud 콘솔 탐색 메뉴에서 보안을 클릭한 다음 VPC 서비스 제어를 클릭합니다.

    VPC 서비스 제어로 이동

  2. BigQuery Omni용 VPC 서비스 제어를 설정하려면 서비스 경계 만들기 가이드의 단계를 진행하면서 이그레스 규칙 창이 표시되면 다음 단계를 따르세요.

    1. 이그레스 규칙 창에서 규칙 추가를 클릭합니다.

    2. API 클라이언트의 FROM 속성 섹션의 ID 목록에서 옵션을 선택합니다.

    3. 외부 리소스의 To 속성을 선택합니다.

    4. 외부 리소스를 추가하려면 외부 리소스 추가를 클릭합니다.

    5. 외부 리소스 추가 대화상자의 외부 리소스 이름에 유효한 리소스 이름을 입력합니다. 예를 들면 다음과 같습니다.

      • Amazon Simple Storage Service(Amazon S3): s3://BUCKET_NAME

        BUCKET_NAME을 Amazon S3 버킷 이름으로 바꿉니다.

      • Azure Blob Storage: azure://myaccount.blob.core.windows.net/CONTAINER_NAME

        CONTAINER NAME을 Blob Storage 컨테이너 이름으로 바꿉니다.

      이그레스 규칙 속성 목록은 이그레스 규칙 참조를 확인하세요.

    6. 외부 리소스에서 허용할 메서드를 선택합니다.

      1. 모든 메서드를 허용하려면 메서드 목록에서 모든 메서드를 선택합니다.
      2. 특정 메서드를 허용하려면 선택된 메서드를 선택하고 메서드 선택을 클릭한 후 외부 리소스에서 허용할 메서드를 선택합니다.
    7. 경계 만들기를 클릭합니다.

gcloud CLI를 사용하여 VPC 서비스 제어 설정

gcloud CLI를 사용하여 VPC 서비스 제어를 설정하려면 다음 단계를 수행합니다.

  1. 기본 액세스 정책을 설정합니다.
  2. 이그레스 정책 입력 파일을 만듭니다.
  3. 이그레스 정책을 추가합니다.

기본 액세스 정책 설정

액세스 정책은 액세스 수준 및 서비스 경계에 대한 조직 전반의 컨테이너입니다. 기본 액세스 정책을 설정하거나 액세스 정책 이름을 가져오는 방법에 대한 상세 설명은 액세스 정책 관리를 참조하세요.

이그레스 정책 입력 파일 만들기

이그레스 규칙 블록은 경계 내에서 경계 외부의 리소스로 허용된 액세스를 정의합니다. 외부 리소스의 경우 externalResources 속성은 VPC 서비스 제어 경계 내에서 액세스가 허용되는 외부 리소스 경로를 정의합니다.

JSON 파일 또는 YAML 파일을 사용하여 이그레스 규칙을 구성할 수 있습니다. 다음 샘플에서는 .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: 경계 외부의 지정된 프로젝트에 있는 Google Cloud 리소스에 허용되는 서비스 작업을 나열합니다.

  • operations: from 블록 조건을 충족하는 클라이언트가 액세스할 수 있는 서비스 및 작업 또는 메서드의 목록을 나열합니다.

  • serviceName: BigQuery Omni에 bigquery.googleapis.com을 설정합니다.

  • methodSelectors: from 조건을 충족하는 클라이언트가 액세스할 수 있는 메서드를 나열합니다. 서비스에서 제한될 수 있는 메서드 및 권한은 지원되는 서비스 메서드 제한사항을 참조하세요.

  • method : 모든 serviceName 메서드를 허용하는 유효한 서비스 메서드 또는 \"*\"입니다.

  • permission: \"*\", externalResource.read 또는 externalResource.write 등의 유효한 서비스 권한입니다. 이 권한이 필요한 작업의 경우 경계 외부의 리소스에 대한 액세스가 허용됩니다.

  • externalResources: 경계 내부의 클라이언트가 액세스할 수 있는 외부 리소스를 나열합니다. EXTERNAL_RESOURCE_PATH를 유효한 Amazon S3 버킷(예: s3://bucket_name) 또는 Blob Storage 컨테이너 경로(예: azure://myaccount.blob.core.windows.net/container_name)로 바꿉니다.

  • egressFrom: 경계 내부의 지정된 프로젝트에서 Google Cloud 리소스의 허용된 서비스 작업을 나열합니다.

  • identityType 또는 identities: 경계 외부의 지정된 리소스에 액세스할 수 있는 ID 유형을 정의합니다. IDENTITY_TYPE을 다음의 유효한 값 중 하나로 바꿉니다.

    • ANY_IDENTITY: 모든 ID 허용
    • ANY_USER_ACCOUNT: 모든 사용자 허용
    • ANY_SERVICE_ACCOUNT: 모든 서비스 계정 허용
  • identities: 경계 외부의 지정된 리소스에 액세스할 수 있는 서비스 계정을 나열합니다.

  • serviceAccount (선택사항): SERVICE_ACCOUNT를 경계 외부의 지정된 리소스에 액세스할 수 있는 서비스 계정으로 바꿉니다.

예시

다음 예시는 경계 내부에서 AWS의 s3://mybucket Amazon S3 위치로 이그레스 작업을 허용하는 정책입니다.

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

다음 예시에서는 Blob Storage 컨테이너에 대한 이그레스 작업을 허용합니다.

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

이그레스 정책에 대한 상세 설명은 이그레스 규칙 참조를 확인하세요.

이그레스 정책 추가

새 서비스 경계를 만들 때 이그레스 정책을 추가하려면 gcloud access-context-manager perimeters create 명령어를 사용합니다. 예를 들어 다음 명령어는 프로젝트 번호 12345가 있는 프로젝트를 포함하는 omniPerimeter라는 새 경계를 만들고 BigQuery API를 제한하며 egress.yaml 파일에서 정의된 이그레스 정책을 추가합니다.

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

기존 서비스 경계에 이그레스 정책을 추가하려면 gcloud access-context-manager perimeters update 명령어를 사용합니다. 예를 들어 다음 명령어는 egress.yaml 파일에서 정의된 이그레스 정책을 omniPerimeter라는 기존 서비스 경계에 추가합니다.

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

경계 검증

경계를 검증하려면 gcloud access-context-manager perimeters describe 명령어를 사용합니다.

gcloud access-context-manager perimeters describe PERIMETER_NAME

PERIMETER_NAME을 경계 이름으로 바꾸세요.

예를 들어 다음 명령어는 경계 omniPerimeter를 설명합니다.

gcloud access-context-manager perimeters describe omniPerimeter

자세한 내용은 서비스 경계 관리를 참조하세요.

제한사항

Amazon S3 및 Blob Storage를 기반으로 BigLake 테이블에 적용되는 전체 제한사항 목록은 제한사항을 참조하세요.

다음 단계