클러스터링된 테이블 만들기 및 사용

이 문서에서는 BigQuery에서 클러스터링된 테이블을 만들고 사용하는 방법을 설명합니다. BigQuery의 클러스터링된 테이블 지원 개요는 클러스터링된 테이블 소개를 참조하세요.

제한사항

BigQuery의 클러스터링된 테이블에는 다음과 같은 제한사항이 적용됩니다.

  • 클러스터링은 파티션을 나눈 테이블에서만 지원됩니다.
  • 클러스터링된 테이블을 쿼리하거나 클러스터링된 테이블에 쿼리 결과를 쓰는 데는 표준 SQL만 지원됩니다.
  • 테이블이 생성된 경우에만 클러스터링 열을 지정할 수 있습니다.
  • 클러스터링된 테이블이 생성된 후에는 클러스터링 열을 수정할 수 없습니다.
  • 클러스터링 열은 최상위 수준의 반복되지 않는 열이어야 하며 다음 유형 중 하나여야 합니다.

    • DATE
    • BOOL
    • GEOGRAPHY
    • INT64
    • NUMERIC
    • STRING
    • TIMESTAMP

    데이터 유형에 대한 자세한 내용은 표준 SQL 데이터 유형을 참조하세요.

  • 클러스터링 열은 최대 4개 지정할 수 있습니다.

  • 클러스터링에 STRING 유형 열을 사용하는 경우 BigQuery는 처음 1,024자만 사용하여 데이터를 클러스터링합니다. 열의 값 자체는 1,024자보다 길 수 있습니다.

    클러스터링된 테이블 만들기

현재, 파티션을 나눈 테이블만 클러스터링할 수 있습니다. 여기에는 수집 시간으로 파티션을 나눈 테이블TIMESTAMP 또는 DATE 열로 파티션을 나눈 테이블이 모두 포함됩니다.

BigQuery에서 클러스터링된 테이블을 만드는 방법은 다음과 같습니다.

테이블 이름 지정

BigQuery에서 테이블을 만들 때 테이블 이름은 데이터세트마다 고유해야 합니다. 테이블 이름의 제한사항은 아래와 같습니다.

  • 최대 1,024자
  • 문자(대문자 또는 소문자), 숫자, 밑줄 포함

필수 권한

테이블을 만들려면 최소한 다음 권한이 부여되어 있어야 합니다.

  • 테이블을 만들 수 있는 bigquery.tables.create 권한
  • 로드 작업, 쿼리 작업 또는 복사 작업을 사용하여 테이블에 데이터를 쓸 수 있는 bigquery.tables.updateData 권한
  • 테이블에 데이터를 쓰는 쿼리 작업, 로드 작업, 복사 작업을 실행할 수 있는 bigquery.jobs.create 권한

테이블에 쓰려는 데이터에 액세스하려면 bigquery.tables.getData와 같은 추가 권한이 필요할 수 있습니다.

다음과 같은 사전 정의된 Cloud IAM 역할에는 bigquery.tables.createbigquery.tables.updateData 권한이 모두 포함되어 있습니다.

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

다음과 같은 사전 정의된 Cloud IAM 역할에는 bigquery.jobs.create 권한이 포함되어 있습니다.

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

또한 bigquery.datasets.create 권한이 있는 사용자는 데이터세트를 만들 때 해당 데이터세트에 대한 bigquery.dataOwner 액세스 권한을 부여받습니다. bigquery.dataOwner 액세스 권한이 있는 사용자는 데이터세트에서 테이블을 만들고 업데이트할 수 있습니다.

BigQuery의 Cloud IAM 역할 및 권한에 대한 자세한 내용은 사전 정의된 역할 및 권한을 참조하세요.

스키마 정의가 있는 빈 클러스터링된 테이블 만들기

클러스터링 열은 BigQuery에서 테이블을 만들 때 지정합니다. 테이블이 생성된 후에는 클러스터링 열을 수정할 수 없습니다. 파티션을 나눈 테이블에만 클러스터링 열을 지정할 수 있습니다.

클러스터링 열은 최상위 수준의 반복되지 않는 열이어야 하며 다음과 같은 간단한 데이터 유형 중 하나여야 합니다.

  • DATE
  • BOOLEAN
  • GEOGRAPHY
  • INTEGER
  • NUMERIC
  • STRING
  • TIMESTAMP

클러스터링 열은 최대 4개 지정할 수 있습니다. 여러 열을 지정할 경우 열 순서에 따라 데이터 정렬 방식이 결정됩니다. 예를 들어 테이블이 a, b, c열로 클러스터링되면 데이터도 동일한 순서(a열, b열, c열 순)로 정렬됩니다. 가장 자주 필터링되거나 집계되는 열을 앞에 배치하는 것이 좋습니다.

클러스터링 열의 순서는 쿼리 성능 및 가격에도 영향을 줍니다. 클러스터링된 테이블의 쿼리 권장사항에 대한 자세한 내용은 클러스터링된 테이블 쿼리를 참조하세요.

스키마 정의가 있는 빈 클러스터링된 테이블을 만드는 방법은 다음과 같습니다.

Console

  1. Google Cloud Console에서 BigQuery 웹 UI로 이동합니다.

    BigQuery 웹 UI로 이동

  2. 탐색 패널의 리소스 섹션에서 프로젝트를 펼치고 데이터세트를 선택합니다.

  3. 창 오른쪽에 있는 세부정보 패널에서 테이블 만들기를 클릭합니다.

    테이블 만들기 버튼

  4. 테이블 만들기 페이지의 소스 아래에서 다음 항목으로 테이블 만들기에 대해 빈 테이블을 선택합니다.

    다음 항목으로 테이블 만들기 옵션

  5. 대상 아래에서 다음 작업을 수행합니다.

    • 데이터세트 이름에서 적절한 데이터세트를 선택하고 테이블 이름 필드에 만들려는 테이블의 이름을 입력합니다.
    • 테이블 유형기본 테이블로 설정되어 있는지 확인합니다.
  6. 스키마 아래에서 스키마 정의를 입력합니다.

    • 다음과 같이 스키마 정보를 직접 입력합니다.

      • 텍스트로 수정을 사용 설정하고 테이블 스키마를 JSON 배열로 입력합니다.

      • 필드 추가를 사용하여 스키마를 직접 입력합니다.

  7. 파티션 및 클러스터 설정 아래에서 필드로 파티션 나누기를 선택하고 DATE 또는 TIMESTAMP 열을 선택합니다. 스키마에 DATE 또는 TIMESTAMP 열이 포함되지 않은 경우에는 이 옵션을 사용할 수 없습니다.

    수집 시간으로 파티션을 나눈 테이블을 만들려면 수집 시간으로 파티션 나누기를 선택합니다.

  8. (선택사항) 파티션 필터에서 파티션 필터 필요 체크박스를 클릭하여 사용자가 쿼리할 파티션을 지정하는 WHERE 절을 포함하도록 합니다. 파티션 필터를 필수항목으로 설정하면 비용을 줄이고 성능을 높일 수 있습니다. 자세한 내용은 파티션을 나눈 테이블 쿼리를 참조하세요.

  9. (선택사항) 클러스터링 순서에 쉼표로 구분된 열 이름을 1~4개 입력합니다.

  10. (선택사항) 고급 옵션을 클릭하고 암호화에서 고객 관리 키를 클릭하여 Cloud Key Management Service 키를 사용합니다. Google 관리 키 설정을 그대로 두면 BigQuery는 저장 데이터를 암호화합니다.

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

기본 UI

  1. 기본 BigQuery 웹 UI로 이동합니다.

    기본 BigQuery 웹 UI로 이동

  2. 탐색창에서 데이터세트 이름 옆에 있는 아래쪽 화살표 아이콘(아래쪽 화살표 아이콘)을 클릭하고 새 테이블 만들기를 클릭합니다.

  3. 테이블 만들기 페이지의 소스 데이터 섹션에서 빈 테이블 만들기를 클릭합니다.

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

    • 테이블 이름으로 적절한 데이터세트를 선택하고 테이블 이름 필드에 생성 중인 테이블 이름을 입력합니다.
    • 테이블 유형기본 테이블로 설정되어 있는지 확인합니다.
  5. 스키마 섹션에서 스키마 정의를 직접 입력합니다.

    • 스키마 정보를 직접 입력하는 방법은 다음과 같습니다.

      • 텍스트로 편집을 클릭하고 테이블 스키마를 JSON 배열로 입력합니다.

      • 필드 추가를 사용하여 스키마를 입력합니다.

  6. 옵션 아래에서 다음 작업을 수행합니다.

    • 파티션 나누기 유형에서 없음을 클릭하고 을 선택합니다.
    • 파티션 나누기 필드에서 다음 중 하나를 선택합니다.
      • DATE 또는 TIMESTAMP 열로 파티션을 나눈 테이블을 만들려면 timestamp를 선택합니다.
      • 수집 시간으로 파티션을 나눈 테이블을 만들려면 _PARTITIONTIME을 선택합니다.
    • 클러스터링 필드에 1~4개의 필드 이름을 입력합니다.
    • 대상 암호화에서 Default 옵션을 그대로 둡니다. 이 속성은 고객 관리 암호화 키를 위한 것입니다. 기본적으로 BigQuery는 비활성 상태로 저장된 고객 콘텐츠를 암호화합니다.

      파티션을 나눈 테이블 세부정보

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

테이블이 생성된 후에 클러스터링된 테이블의 테이블 만료 시간, 설명, 라벨을 업데이트할 수 있습니다. BigQuery 웹 UI를 사용하여 테이블을 만든 경우에는 파티션 만료 시간을 추가할 수 없습니다.

CLI

mk 명령어를 다음 플래그와 함께 사용합니다.

  • --table 또는 -t 단축키
  • --schema. 테이블의 스키마 정의를 인라인으로 제공하거나 JSON 스키마 파일을 사용할 수 있습니다.
  • --time_partitioning_type(수집 시간으로 파티션을 나눈 테이블) 또는 --time_partitioning_field(파티션을 나눈 테이블). 현재, --time_partitioning_type에 지원되는 유일한 값은 DAY입니다.
  • --clustering_fields. 클러스터링 열은 최대 4개 지정할 수 있습니다.

선택적 매개변수에는 --expiration, --description, --time_partitioning_expiration, --destination_kms_key, --label이 있습니다.

기본 프로젝트가 아닌 다른 프로젝트에서 테이블을 만드는 경우 프로젝트 ID를 project_id:dataset 형식으로 데이터세트에 추가합니다.

여기서는 --destination_kms_key를 설명하지 않습니다. --destination_kms_key 사용에 대한 자세한 내용은 고객 관리 암호화 키를 참조하세요.

다음 명령어를 입력하여 스키마 정의가 있는 빈 클러스터링된 테이블을 만듭니다.

    bq mk \
    --table \
    --expiration integer1 \
    --schema schema \
    --time_partitioning_type=DAY \
    --time_partitioning_field partition_column \
    --clustering_fields cluster_columns \
    --time_partitioning_expiration integer2 \
    --description "description" \
    --label key:value,key:value \
    project_id:dataset.table
    

다음을 바꿉니다.

  • integer1: 테이블의 기본 수명(초)입니다. 최솟값은 3,600초(1시간)입니다. 만료 시간은 현재 UTC 시간과 정수 값을 더한 값으로 계산됩니다. 시간으로 파티션을 나눈 테이블을 생성할 때 테이블의 만료 시간을 설정하면 데이터세트의 기본 테이블 만료 시간 설정은 무시됩니다. 이 값을 설정하면 지정한 시간 이후의 모든 파티션과 테이블이 삭제됩니다.
  • schema: column:data_type,column:data_type 형식의 인라인 스키마 정의 또는 로컬 머신의 JSON 스키마 파일 경로입니다.
  • partition_column: 파티션을 나눈 테이블을 만드는 데 사용할 TIMESTAMP 또는 DATE 열의 이름입니다. 파티션을 나눈 테이블을 만드는 경우 --time_partitioning_type=DAY 플래그를 지정할 필요가 없습니다.
  • cluster_columns: 최대 4개의 클러스터링 열이 쉼표로 구분되어 포함된 목록입니다.
  • integer2: 테이블 파티션의 기본 수명(초)입니다. 최솟값은 없습니다. 만료 시간은 파티션의 날짜와 정수 값을 더한 값입니다. 파티션 만료 시간은 테이블의 만료 시간과 별개이며 테이블 만료 시간보다 우선하지 않습니다. 파티션 만료 시간을 테이블 만료 시간보다 길게 설정하면 테이블 만료 시간이 우선합니다.
  • description: 따옴표로 묶은 테이블의 설명입니다.
  • key:value: 라벨을 나타내는 키-값 쌍입니다. 쉼표로 구분된 목록을 사용하여 여러 라벨을 입력할 수도 있습니다.
  • project_id: 프로젝트 ID입니다.
  • dataset: 프로젝트의 데이터세트입니다.
  • table: 만들려는 파티션을 나눈 테이블의 이름입니다.

명령줄에서 스키마를 지정할 때는 RECORD(STRUCT) 유형을 포함하거나, 열 설명을 포함하거나, 열 모드를 지정할 수 없습니다. 모든 모드는 기본적으로 NULLABLE로 설정됩니다. 설명, 모드, RECORD 유형을 포함하려면 대신 JSON 스키마 파일을 제공해야 합니다.

예:

다음 명령어를 입력하여 기본 프로젝트의 mydatasetmyclusteredtable이라는 이름의 클러스터링된 테이블을 만듭니다. 이 테이블은 파티션을 나눈 테이블(TIMESTAMP 열로 파티션을 나눔)입니다. 파티션 나누기 만료 시간은 86,400초(1일), 테이블 만료 시간은 2,592,000초(30일로 구성된 한 달)로 설정되고 설명은 This is my clustered table, 라벨은 organization:development로 설정됩니다. 이 명령어는 --table 대신 단축형 -t를 사용합니다.

스키마는 timestamp:timestamp,customer_id:string,transaction_amount:float와 같이 인라인으로 지정됩니다. 지정된 클러스터링 필드 customer_id는 파티션을 클러스터링하는 데 사용됩니다.

bq mk -t \
    --expiration 2592000 \
    --schema 'timestamp:timestamp,customer_id:string,transaction_amount:float' \
    --time_partitioning_field timestamp \
    --clustering_fields customer_id \
    --time_partitioning_expiration 86400  \
    --description "This is my clustered table" \
    --label org:dev \
    mydataset.myclusteredtable
    

다음 명령어를 입력하여 기본 프로젝트가 아니라 myotherprojectmyclusteredtable이라는 이름의 클러스터링된 테이블을 만듭니다. 이 테이블은 수집 시간으로 파티션을 나눈 테이블입니다. 파티션 나누기 만료 시간은 259,200초(3일), 설명은 This is my partitioned table, 라벨은 organization:development로 설정됩니다. 이 명령어는 --table 대신 -t 단축키를 사용합니다. 이 명령어는 테이블 만료 시간을 지정하지 않습니다. 데이터세트에 기본 테이블 만료 시간이 있으면 해당 값이 적용됩니다. 데이터세트에 기본 테이블 만료 시간이 없으면 테이블이 만료되지 않지만 파티션은 3일 후에 만료됩니다.

스키마는 로컬 JSON 파일 /tmp/myschema.json에 지정됩니다. customer_id 필드는 파티션을 클러스터링하는 데 사용됩니다.

bq mk -t \
    --expiration 2592000 \
    --schema /tmp/myschema.json \
    --time_partitioning_type=DAY \
    --clustering_fields=customer_id \
    --time_partitioning_expiration 86400  \
    --description "This is my partitioned table" \
    --label org:dev \
    myotherproject:mydataset.myclusteredtable
    

테이블이 생성된 후에 파티션을 나눈 테이블의 테이블 만료 시간, 파티션 만료 시간, 설명, 라벨을 업데이트할 수 있습니다.

API

timePartitioning 속성, clustering.fields 속성, schema 속성을 지정하는 테이블 리소스가 정의된 tables.insert 메서드를 호출합니다.

Go

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

import (
    	"context"
    	"fmt"
    	"time"

    	"cloud.google.com/go/bigquery"
    )

    // createTableClustered demonstrates creating a BigQuery table with advanced properties like
    // partitioning and clustering features.
    func createTableClustered(projectID, datasetID, tableID string) error {
    	// projectID := "my-project-id"
    	// datasetID := "mydatasetid"
    	// tableID := "mytableid"
    	ctx := context.Background()

    	client, err := bigquery.NewClient(ctx, projectID)
    	if err != nil {
    		return fmt.Errorf("bigquery.NewClient: %v", err)
    	}
    	defer client.Close()

    	sampleSchema := bigquery.Schema{
    		{Name: "timestamp", Type: bigquery.TimestampFieldType},
    		{Name: "origin", Type: bigquery.StringFieldType},
    		{Name: "destination", Type: bigquery.StringFieldType},
    		{Name: "amount", Type: bigquery.NumericFieldType},
    	}
    	metaData := &bigquery.TableMetadata{
    		Schema: sampleSchema,
    		TimePartitioning: &bigquery.TimePartitioning{
    			Field:      "timestamp",
    			Expiration: 90 * 24 * time.Hour,
    		},
    		Clustering: &bigquery.Clustering{
    			Fields: []string{"origin", "destination"},
    		},
    	}
    	tableRef := client.Dataset(datasetID).Table(tableID)
    	if err := tableRef.Create(ctx, metaData); err != nil {
    		return err
    	}
    	return nil
    }
    

자바

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

import com.google.cloud.bigquery.BigQuery;
    import com.google.cloud.bigquery.BigQueryException;
    import com.google.cloud.bigquery.BigQueryOptions;
    import com.google.cloud.bigquery.Clustering;
    import com.google.cloud.bigquery.Field;
    import com.google.cloud.bigquery.Schema;
    import com.google.cloud.bigquery.StandardSQLTypeName;
    import com.google.cloud.bigquery.StandardTableDefinition;
    import com.google.cloud.bigquery.TableId;
    import com.google.cloud.bigquery.TableInfo;
    import com.google.cloud.bigquery.TimePartitioning;
    import com.google.common.collect.ImmutableList;

    public class CreateClusteredTable {
      public static void runCreateClusteredTable() {
        // TODO(developer): Replace these variables before running the sample.
        String datasetName = "MY_DATASET_NAME";
        String tableName = "MY_TABLE_NAME";
        createClusteredTable(datasetName, tableName);
      }

      public static void createClusteredTable(String datasetName, String tableName) {
        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(datasetName, tableName);

          TimePartitioning partitioning = TimePartitioning.of(TimePartitioning.Type.DAY);

          Schema schema =
              Schema.of(
                  Field.of("name", StandardSQLTypeName.STRING),
                  Field.of("post_abbr", StandardSQLTypeName.STRING),
                  Field.of("date", StandardSQLTypeName.DATE));

          Clustering clustering =
              Clustering.newBuilder().setFields(ImmutableList.of("name", "post_abbr")).build();

          StandardTableDefinition tableDefinition =
              StandardTableDefinition.newBuilder()
                  .setSchema(schema)
                  .setTimePartitioning(partitioning)
                  .setClustering(clustering)
                  .build();
          TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

          bigquery.create(tableInfo);
          System.out.println("Clustered table created successfully");
        } catch (BigQueryException e) {
          System.out.println("Clustered table was not created. \n" + e.toString());
        }
      }
    }

쿼리 결과에서 클러스터링된 테이블 만들기

쿼리 결과에서 클러스터링된 테이블을 만드는 방법에는 두 가지가 있습니다.

파티션을 나눈 테이블이나 파티션을 나누지 않은 테이블을 쿼리하여 클러스터링된 테이블을 만들 수 있습니다. 쿼리 결과를 사용하여 기존 테이블을 클러스터링된 테이블로 변경할 수는 없습니다.

쿼리 결과에서 클러스터링된 테이블을 만드는 경우 표준 SQL을 사용해야 합니다. 현재, 클러스터링된 테이블을 쿼리하거나 쿼리 결과를 클러스터링된 테이블에 쓰는 용도로 legacy SQL을 사용할 수 없습니다.

Console

Console BigQuery 웹 UI를 사용하여 데이터를 쿼리하는 경우 DDL 문을 사용하지 않으면 대상 테이블에 클러스터링 옵션을 지정할 수 없습니다. 자세한 내용은 데이터 정의 언어 문 사용을 참조하세요.

기본 UI

기본 BigQuery 웹 UI를 사용하여 데이터를 쿼리하는 경우 DDL 문을 사용하지 않으면 대상 테이블에 클러스터링 옵션을 지정할 수 없습니다. 자세한 내용은 데이터 정의 언어 문 사용을 참조하세요.

CLI

다음 명령어를 입력하여 쿼리 결과에서 클러스터링된 새 대상 테이블을 만듭니다.

    bq --location=location query \
    --use_legacy_sql=false 'query'
    

다음을 바꿉니다.

  • location: 위치의 이름입니다. --location 플래그는 선택사항입니다. 예를 들어 도쿄 리전에서 BigQuery를 사용한다면 플래그 값을 asia-northeast1로 설정할 수 있습니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.
  • query: 표준 SQL 구문의 쿼리입니다. 현재, legacy SQL을 사용하여 클러스터링된 테이블을 쿼리하거나 쿼리 결과를 클러스터링된 테이블에 쓸 수 없습니다. 쿼리에는 클러스터링된 테이블 생성 옵션을 지정하는 CREATE TABLE DDL 문이 포함될 수 있습니다. 개별 명령줄 플래그를 지정하지 않고 DDL을 사용할 수 있습니다.

예:

다음 명령어를 입력하여 mydataset에 있는 myclusteredtable이라는 클러스터링된 대상 테이블에 쿼리 결과를 씁니다. 여기서 mydataset는 기본 프로젝트에 있습니다. 이 쿼리는 파티션을 나눈 테이블이 아닌 mytable에서 데이터를 검색합니다. 테이블의 customer_id 열은 테이블을 클러스터링하는 데 사용됩니다. 테이블의 timestamp 열은 파티션을 나눈 테이블을 만드는 데 사용됩니다.

bq query --use_legacy_sql=false \
    'CREATE TABLE
       mydataset.myclusteredtable
     PARTITION BY
       DATE(timestamp)
     CLUSTER BY
       customer_id AS
     SELECT
       *
     FROM
       `mydataset.mytable`'
    

API

쿼리 결과를 클러스터링된 테이블에 저장하려면 jobs.insert 메서드를 호출하고, query 작업을 구성하고, 클러스터링된 테이블을 만드는 CREATE TABLE DDL 문을 포함합니다.

작업 리소스jobReference 섹션에 있는 location 속성에 사용자 위치를 지정합니다.

데이터 로드 시 클러스터링된 테이블 만들기

데이터를 새 테이블에 로드할 때 클러스터링 열을 지정하면 클러스터링된 테이블을 만들 수 있습니다. 이때 데이터를 로드하기 전에 빈 테이블을 만들지 않아도 됩니다. 클러스터링된 테이블을 만들면서 동시에 데이터를 로드할 수 있습니다.

데이터 로드에 대한 자세한 내용은 BigQuery로 데이터 로드 소개를 참조하세요.

로드 작업 정의 시 클러스터링을 정의하려면 다음 작업을 수행합니다.

API

로드 작업을 통해 테이블 생성 시 클러스터링 구성을 정의하려면 테이블에 Clustering 속성을 채우면 됩니다.

Go

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

import (
    	"context"
    	"fmt"

    	"cloud.google.com/go/bigquery"
    )

    // importClusteredTable demonstrates creating a table from a load job and defining partitioning and clustering
    // properties.
    func importClusteredTable(projectID, destDatasetID, destTableID string) error {
    	// projectID := "my-project-id"
    	// datasetID := "mydataset"
    	// tableID := "mytable"
    	ctx := context.Background()
    	client, err := bigquery.NewClient(ctx, projectID)
    	if err != nil {
    		return fmt.Errorf("bigquery.NewClient: %v", err)
    	}
    	defer client.Close()

    	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/sample-transactions/transactions.csv")
    	gcsRef.SkipLeadingRows = 1
    	gcsRef.Schema = bigquery.Schema{
    		{Name: "timestamp", Type: bigquery.TimestampFieldType},
    		{Name: "origin", Type: bigquery.StringFieldType},
    		{Name: "destination", Type: bigquery.StringFieldType},
    		{Name: "amount", Type: bigquery.NumericFieldType},
    	}
    	loader := client.Dataset(destDatasetID).Table(destTableID).LoaderFrom(gcsRef)
    	loader.TimePartitioning = &bigquery.TimePartitioning{
    		Field: "timestamp",
    	}
    	loader.Clustering = &bigquery.Clustering{
    		Fields: []string{"origin", "destination"},
    	}
    	loader.WriteDisposition = bigquery.WriteEmpty

    	job, err := loader.Run(ctx)
    	if err != nil {
    		return err
    	}
    	status, err := job.Wait(ctx)
    	if err != nil {
    		return err
    	}

    	if status.Err() != nil {
    		return fmt.Errorf("job completed with error: %v", status.Err())
    	}
    	return nil
    }
    

자바

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

import com.google.cloud.bigquery.BigQuery;
    import com.google.cloud.bigquery.BigQueryException;
    import com.google.cloud.bigquery.BigQueryOptions;
    import com.google.cloud.bigquery.Clustering;
    import com.google.cloud.bigquery.Field;
    import com.google.cloud.bigquery.FormatOptions;
    import com.google.cloud.bigquery.Job;
    import com.google.cloud.bigquery.JobInfo;
    import com.google.cloud.bigquery.LoadJobConfiguration;
    import com.google.cloud.bigquery.Schema;
    import com.google.cloud.bigquery.StandardSQLTypeName;
    import com.google.cloud.bigquery.TableId;
    import com.google.cloud.bigquery.TimePartitioning;
    import com.google.common.collect.ImmutableList;

    public class LoadTableClustered {

      public static void runLoadTableClustered() throws Exception {
        // TODO(developer): Replace these variables before running the sample.
        String datasetName = "MY_DATASET_NAME";
        String tableName = "MY_TABLE_NAME";
        String sourceUri = "/path/to/file.csv";
        loadTableClustered(datasetName, tableName, sourceUri);
      }

      public static void loadTableClustered(String datasetName, String tableName, String sourceUri)
          throws Exception {
        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(datasetName, tableName);

          Schema schema =
              Schema.of(
                  Field.of("name", StandardSQLTypeName.STRING),
                  Field.of("post_abbr", StandardSQLTypeName.STRING),
                  Field.of("date", StandardSQLTypeName.DATE));

          TimePartitioning partitioning = TimePartitioning.of(TimePartitioning.Type.DAY);

          Clustering clustering =
              Clustering.newBuilder().setFields(ImmutableList.of("name", "post_abbr")).build();

          LoadJobConfiguration loadJobConfig =
              LoadJobConfiguration.builder(tableId, sourceUri)
                  .setFormatOptions(FormatOptions.csv())
                  .setSchema(schema)
                  .setTimePartitioning(partitioning)
                  .setClustering(clustering)
                  .build();

          Job loadJob = bigquery.create(JobInfo.newBuilder(loadJobConfig).build());

          // Load data from a GCS parquet file into the table
          // Blocks until this load table job completes its execution, either failing or succeeding.
          Job completedJob = loadJob.waitFor();

          // Check for errors
          if (completedJob == null) {
            throw new Exception("Job not executed since it no longer exists.");
          } else if (completedJob.getStatus().getError() != null) {
            // You can also look at queryJob.getStatus().getExecutionErrors() for all
            // errors, not just the latest one.
            throw new Exception(
                "BigQuery was unable to load into the table due to an error: \n"
                    + loadJob.getStatus().getError());
          }
          System.out.println("Data successfully loaded into clustered table during load job");
        } catch (BigQueryException | InterruptedException e) {
          System.out.println("Data not loaded into clustered table during load job \n" + e.toString());
        }
      }
    }

클러스터링된 테이블에 대한 액세스 제어

테이블이나 뷰에 액세스 제어를 직접 할당할 수는 없습니다. 액세스 권한을 부여할 수 있는 최저 BigQuery 리소스 수준은 데이터세트 수준입니다. 테이블 및 뷰에 대한 액세스 권한을 구성하려면 데이터세트 수준 이상에서 항목에 Cloud IAM 역할을 부여합니다.

데이터세트 수준에서 역할을 부여하면 특정 데이터세트의 테이블과 뷰에서 항목이 수행할 수 있는 작업이 지정됩니다. 데이터세트 수준의 액세스 권한 제어 구성에 대한 자세한 내용은 데이터세트에 대한 액세스 제어를 참조하세요.

프로젝트, 폴더, 조직 수준과 같이 Google Cloud 리소스 계층 구조의 상위 수준에서 Cloud IAM 역할을 부여할 수도 있습니다. 상위 수준에서 역할을 부여하면 항목이 더욱 다양한 리소스에 액세스할 수 있습니다. 예를 들어 프로젝트 수준에서 항목에 역할을 부여하면 프로젝트의 모든 데이터세트에 적용되는 권한이 항목에 부여됩니다. 리소스에 대한 액세스 권한 부여 방법에 대한 자세한 내용은 Cloud IAM 문서의 리소스에 대한 액세스 권한 부여, 변경, 취소를 참조하세요.

Cloud IAM 커스텀 역할을 만들 수도 있습니다. 커스텀 역할을 만들 경우 항목이 수행하도록 하려는 특정 작업에 따라 권한을 부여합니다.

역할과 권한에 대한 자세한 내용은 다음을 참조하세요.

클러스터링된 테이블 사용

클러스터링된 테이블 정보 가져오기

다음과 같은 방법으로 테이블에 대한 정보를 가져올 수 있습니다.

  • Cloud Console 또는 기본 BigQuery 웹 UI 사용
  • bq show CLI 명령어 사용
  • tables.get API 메서드 호출
  • INFORMATION_SCHEMA 뷰 쿼리

필수 권한

테이블에 대한 정보를 가져오려면 최소한 bigquery.tables.get 권한이 부여되어 있어야 합니다. 다음과 같은 사전 정의된 Cloud IAM 역할에는 bigquery.tables.get 권한이 포함되어 있습니다.

  • bigquery.metadataViewer
  • bigquery.dataViewer
  • bigquery.dataOwner
  • bigquery.dataEditor
  • bigquery.admin

또한 bigquery.datasets.create 권한이 있는 사용자는 데이터세트를 만들 때 해당 데이터세트에 대한 bigquery.dataOwner 액세스 권한을 부여받습니다. bigquery.dataOwner 액세스 권한이 있는 사용자는 데이터세트에서 테이블 정보를 가져올 수 있습니다.

BigQuery의 Cloud IAM 역할 및 권한에 대한 자세한 내용은 사전 정의된 역할 및 권한을 참조하세요.

클러스터링된 테이블 정보 가져오기

클러스터링된 테이블 정보를 보는 방법은 다음과 같습니다.

Console

  1. Google Cloud Console에서 리소스 창으로 이동합니다. 데이터세트 이름을 클릭하여 펼친 다음 확인하려는 테이블 이름을 클릭합니다.

  2. 세부정보를 클릭하면 페이지에 클러스터링 열을 포함한 테이블의 세부정보가 표시됩니다.

    테이블 세부정보

기본 UI

  1. 탐색창에서 데이터세트 왼쪽에 있는 아래쪽 화살표 아이콘(아래쪽 화살표 아이콘)을 클릭하여 펼치거나 데이터세트 이름을 더블클릭합니다. 그러면 데이터세트에 있는 테이블과 뷰가 표시됩니다.

  2. 테이블 이름을 클릭합니다.

  3. 세부정보를 클릭하면 테이블 세부정보 페이지에 클러스터링 열을 포함한 테이블의 세부정보가 표시됩니다.

    클러스터링된 테이블의 세부정보

CLI

bq show 명령어를 실행하여 모든 테이블 정보를 표시합니다. 테이블 스키마 정보만 표시하려면 --schema 플래그를 사용합니다. --format 플래그를 사용하면 출력을 제어할 수 있습니다.

기본 프로젝트가 아닌 프로젝트의 테이블에 대한 정보를 가져오려면 프로젝트 ID를 project_id:dataset 형식으로 데이터세트에 추가합니다.

    bq show \
    --schema \
    --format=prettyjson \
    project_id:dataset.table
    

다음을 바꿉니다.

  • project_id: 프로젝트 ID입니다.
  • dataset: 데이터세트의 이름입니다.
  • table: 테이블의 이름입니다.

예:

다음 명령어를 입력하여 mydataset에 있는 myclusteredtable과 관련된 모든 정보를 표시합니다. 여기서 mydataset는 기본 프로젝트에 있습니다.

bq show --format=prettyjson mydataset.myclusteredtable
    

다음과 유사하게 출력됩니다.

    {
      "clustering": {
        "fields": [
          "customer_id"
        ]
      },
    ...
    }
    

API

bigquery.tables.get 메서드를 호출하고 관련 매개변수를 모두 제공합니다.

SQL

클러스터링된 테이블의 경우 INFORMATION_SCHEMA.COLUMNS 뷰의 CLUSTERING_ORDINAL_POSITION 열을 쿼리하여 테이블의 클러스터링 열에 대한 정보를 검색할 수 있습니다.

    -- Set up a table with clustering.
    CREATE TABLE myDataset.data (column1 INT64, column2 INT64)
    PARTITION BY _PARTITIONDATE
    CLUSTER BY column1, column2;

    -- This query returns 1 for column1 and 2 for column2.
    SELECT column_name, clustering_ordinal_position
    FROM myDataset.INFORMATION_SCHEMA.COLUMNS;
    

INFORMATION_SCHEMATABLES, TABLE_OPTIONS, COLUMNS, COLUMN_FIELD_PATH 뷰를 통해 더 많은 테이블 메타데이터를 사용할 수 있습니다.

데이터세트의 클러스터링된 테이블 나열

다음과 같은 방법으로 데이터세트의 클러스터링된 테이블을 나열할 수 있습니다.

  • Cloud Console 또는 기본 BigQuery 웹 UI 사용
  • bq ls CLI 명령어 사용
  • tables.list API 메서드 호출
  • 클라이언트 라이브러리 사용
  • INFORMATION_SCHEMA.COLUMNS 뷰의 CLUSTERING_ORDINAL_POSITION 열 쿼리

클러스터링된 테이블을 나열하는 데 필요한 권한과 테이블을 나열하는 단계는 파티션을 나눈 테이블과 동일합니다. 테이블 나열에 대한 자세한 내용은 데이터세트의 파티션을 나눈 테이블 나열을 참조하세요.

개발 중인 기능

다음 기능은 개발 중이며, 현재 알파 출시 버전에서는 사용할 수 없습니다.

  • 파티션을 나누지 않은 네이티브 테이블 클러스터링 지원
  • 클러스터링 열에 필터를 사용하는 특정 유형의 쿼리 비용 절감

다음 단계