Amazon S3 BigLake 외부 테이블 만들기

콘솔

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

   BigQuery로 이동

2. 탐색기 창에서 데이터 세트를 만들 프로젝트를 선택합니다.
3. more_vert 작업 보기 옵션을 확장하고 데이터 세트 만들기를 클릭합니다.
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. play_circle 실행을 클릭합니다.

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

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 형식으로 데이터 세트 이름에 추가합니다.

자바

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

콘솔

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

   BigQuery로 이동

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

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

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

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

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, ICEBERG 또는 PARQUET(미리보기))
   • 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. play_circle 실행을 클릭합니다.

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

예:

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, DELTA_LAKE, ICEBERG 또는 PARQUET)
• 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 속성을 지정합니다.

자바

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

콘솔

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

   BigQuery로 이동

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

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

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. play_circle 실행을 클릭합니다.

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

예시

다음 예시에서는 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_MODE가 CUSTOM이면 다음 형식을 사용하여 소스 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로 설정합니다.

콘솔

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

   BigQuery로 이동

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

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를 지정합니다.

AWS CLI

다음 명령어를 실행하여 aws:SourceVpc 속성을 사용하는 조건이 포함된 S3 버킷 정책을 적용합니다.

  aws s3api put-bucket-policy \
    --bucket=BUCKET_NAME \
    --policy "{
      \"Version\": \"2012-10-17\",
      \"Id\": \"RestrictBucketReads\",
      \"Statement\": [
          {
              \"Sid\": \"AccessOnlyToOmniVPC\",
              \"Principal\": \"*\",
              \"Action\": [\"s3:ListBucket\", \"s3:GetObject\"],
              \"Effect\": \"Allow\",
              \"Resource\": [\"arn:aws:s3:::BUCKET_NAME\",
                             \"arn:aws:s3:::BUCKET_NAME/*\"],
              \"Condition\": {
                  \"StringEquals\": {
                    \"aws:SourceVpc\": \"VPC_ID\"
                  }
              }
          }
      ]
    }"

다음을 바꿉니다.

• BUCKET_NAME: BigQuery에서 액세스하도록 할 Amazon S3 버킷
• VPC_ID: Amazon S3 버킷과 함께 배치된 BigQuery Omni 리전의 BigQuery Omni VPC ID입니다. 이 정보는 이 페이지의 표에서 확인할 수 있습니다.

Terraform

Terraform 구성 파일에 다음을 추가합니다.

  resource "aws_s3_bucket" "example" {
    bucket = "BUCKET_NAME"
  }

  resource "aws_s3_bucket_policy" "example" {
    bucket = aws_s3_bucket.example.id
    policy = jsonencode({
      Version = "2012-10-17"
      Id      = "RestrictBucketReads"
      Statement = [
          {
              Sid       = "AccessOnlyToOmniVPC"
              Effect    = "Allow"
              Principal = "*"
              Action    = ["s3:GetObject", "s3:ListBucket"]
              Resource  = [
                  aws_s3_bucket.example.arn,
                  "${aws_s3_bucket.example.arn}/*"
                  ]
              Condition = {
                  StringEquals = {
                      "aws:SourceVpc": "VPC_ID"
                  }
              }
          },
      ]
    })
  }

다음을 바꿉니다.

• BUCKET_NAME: BigQuery에서 액세스하도록 할 Amazon S3 버킷
• VPC_ID: Amazon S3 버킷과 함께 배치된 BigQuery Omni 리전의 BigQuery Omni VPC ID입니다.