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

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

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

다음 방법으로 클러스터링된 테이블을 만들 수 있습니다.

• 쿼리 결과에서 테이블 만들기:

  • DDL CREATE TABLE AS SELECT 문을 실행합니다.
  • 클러스터링된 대상 테이블을 만드는 쿼리를 실행합니다.

• clustering_column_list를 포함한 CLUSTER BY 절이 있는 DDL CREATE TABLE 문을 사용합니다.

• bq 명령줄 도구 bq mk 명령어를 실행합니다.

• tables.insert API 메서드를 호출합니다.

• BigQuery에 데이터를 로드합니다.

• 클라이언트 라이브러리를 사용합니다.

테이블 이름 지정

BigQuery에서 테이블을 만들 때 테이블 이름은 데이터 세트별로 고유해야 합니다. 테이블 이름을 지정하는 규칙은 다음과 같습니다.

• 최대 총 1,024 UTF-8 바이트의 문자를 포함합니다.
• L(문자), M(표시), N(숫자), Pc(밑줄 포함 커넥터), Pd(대시), Zs(공백) 카테고리의 유니코드를 포함합니다. 자세한 내용은 일반 카테고리를 참조하세요.

table 01, ग्राहक, 00_お客様, étudiant-01은 모두 유효한 테이블 이름 예시입니다.

주의사항:

• 테이블 이름은 기본적으로 대소문자를 구분합니다. mytable 및 MyTable은 대소문자 구분이 사용 중지된 데이터 세트에 속하지 않는 한 동일한 데이터 세트에 공존할 수 있습니다.
• 일부 테이블 이름과 테이블 이름 프리픽스가 예약되어 있습니다. 테이블 이름 또는 프리픽스가 예약되어 있다는 오류가 표시되면 다른 이름을 선택한 후 다시 시도하세요.

• 시퀀스에 점 연산자(.)를 여러 개 포함하면 중복된 연산자가 암시적으로 삭제됩니다.

  예를 들어 원래 구문이 project_name....dataset_name..table_name이면

  구문이 project_name.dataset_name.table_name으로 바뀝니다.

필수 권한

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

• bigquery.tables.create
• bigquery.tables.updateData
• bigquery.jobs.create

또한 테이블에 기록하는 데이터에 액세스하기 위해 bigquery.tables.getData 권한이 필요할 수 있습니다.

다음과 같은 사전 정의된 각 IAM 역할에는 테이블을 만드는 데 필요한 권한이 포함되어 있습니다.

• roles/bigquery.dataEditor
• roles/bigquery.dataOwner
• roles/bigquery.admin(bigquery.jobs.create 권한 포함)
• roles/bigquery.user(bigquery.jobs.create 권한 포함)
• roles/bigquery.jobUser(bigquery.jobs.create 권한 포함)

또한 bigquery.datasets.create 권한이 있으면 만들 데이터 세트에서 테이블을 만들고 업데이트할 수 있습니다.

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

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

클러스터링 열은 BigQuery에서 테이블을 만들 때 지정합니다. 테이블이 생성되면 클러스터링 열을 수정할 수 있습니다. 자세한 내용은 클러스터링 사양 수정을 참조하세요.

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

• DATE
• BOOLEAN
• GEOGRAPHY
• INTEGER
• NUMERIC
• BIGNUMERIC
• STRING
• TIMESTAMP
• RANGE(미리보기)

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

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

스키마 정의가 있는 빈 클러스터링된 테이블을 만들려면 다음 작업을 수행합니다.

콘솔

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

   BigQuery로 이동

2. 탐색기 창에서 프로젝트를 펼친 후 데이터 세트를 선택합니다.
3. 데이터 세트 정보 섹션에서 테이블 만들기를 클릭합니다.
4. 테이블 만들기 패널에서 다음 세부정보를 지정합니다.
1. 소스 섹션의 다음 항목으로 테이블 만들기 목록에서 빈 테이블을 선택합니다.
2. 대상 섹션에서 다음 세부정보를 지정합니다.
   1. 데이터 세트에서 테이블을 만들 데이터 세트를 선택합니다.
   2. 테이블 필드에 만들려는 테이블의 이름을 입력합니다.
   3. 테이블 유형 필드가 기본 테이블로 설정되어 있는지 확인합니다.
3. 스키마 섹션에 스키마 정의를 입력합니다. 다음 방법 중 하나를 사용하여 스키마 정보를 직접 입력할 수 있습니다.
   • 선택사항 1: 텍스트로 수정을 클릭하고 스키마를 JSON 배열 형식으로 붙여넣습니다. JSON 배열을 사용하는 경우 JSON 스키마 파일 만들기와 동일한 프로세스를 수행하여 스키마를 생성합니다. 다음 명령어를 입력하면 기존 테이블의 스키마를 JSON 형식으로 볼 수 있습니다.

         bq show --format=prettyjson dataset.table
         

   • 선택사항 2: 필드 추가를 클릭하고 테이블 스키마를 입력합니다. 각 필드의 이름, 유형, 모드를 지정합니다.
4. 클러스터링 순서에 쉼표로 구분된 열 이름을 1~4개 입력합니다.
5. 선택사항: 고급 옵션 섹션에서 고객 관리 암호화 키를 사용하려면 고객 관리 암호화 키(CMEK) 사용 옵션을 선택합니다. 기본적으로 BigQuery는 Google 관리 키를 사용하여 저장된 고객 콘텐츠를 암호화합니다.
6. 테이블 만들기를 클릭합니다.

SQL

CREATE TABLE DDL 문 명령어를 CLUSTER BY 옵션과 함께 사용합니다. 다음 예시에서는 mydataset에 myclusteredtable이라는 클러스터링된 테이블을 만듭니다.

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

   BigQuery로 이동

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

   CREATE TABLE mydataset.myclusteredtable
   (
     customer_id STRING,
     transaction_amount NUMERIC
   )
   CLUSTER BY
     customer_id
     OPTIONS (
       description = 'a table clustered by customer_id');
   

3. 실행을 클릭합니다.

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

bq

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

• --table 또는 -t 단축키
• --schema. 테이블의 스키마 정의를 인라인으로 제공하거나 JSON 스키마 파일을 사용할 수 있습니다.
• --clustering_fields. 클러스터링 열을 최대 4개까지 지정할 수 있습니다.

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

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

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

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

bq mk \
    --table \
    --expiration INTEGER1 \
    --schema SCHEMA \
    --clustering_fields CLUSTER_COLUMNS \
    --description "DESCRIPTION" \
    --label KEY:VALUE,KEY:VALUE \
    PROJECT_ID:DATASET.TABLE

다음을 바꿉니다.

• INTEGER1: 테이블의 기본 수명(초)입니다. 최솟값은 3,600초(1시간)입니다. 만료 시간은 현재 UTC 시간과 정수 값을 더한 값으로 계산됩니다. 테이블을 생성할 때 테이블의 만료 시간을 설정하면 데이터 세트의 기본 테이블 만료 시간 설정은 무시됩니다. 이 값을 설정하면 지정한 시간 이후에 테이블이 삭제됩니다.
• SCHEMA: COLUMN:DATA_TYPE,COLUMN:DATA_TYPE 형식의 인라인 스키마 정의 또는 로컬 머신의 JSON 스키마 파일 경로입니다.
• CLUSTER_COLUMNS. 클러스터링 열을 최대 4개까지 포함시킬 수 있는 쉼표로 구분된 목록입니다. 목록에는 공백이 포함될 수 없습니다.
• DESCRIPTION: 따옴표로 묶은 테이블 설명입니다.
• KEY:VALUE: 라벨을 나타내는 키-값 쌍입니다. 쉼표로 구분된 목록을 사용하여 라벨을 여러 개 입력할 수 있습니다.
• PROJECT_ID: 프로젝트 ID입니다.
• DATASET: 프로젝트의 데이터 세트입니다.
• TABLE: 생성할 테이블의 이름입니다.

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

예를 들면 다음과 같습니다.

다음 명령어를 입력하여 기본 프로젝트의 mydataset에 myclusteredtable이라는 이름의 클러스터링된 테이블을 만듭니다. 테이블 만료 시간은 2,592,000초(30일 기준 1개월)로 설정되고, 설명은 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' \
    --clustering_fields customer_id \
    --description "This is my clustered table" \
    --label org:dev \
    mydataset.myclusteredtable

다음 명령어를 입력하여 기본 프로젝트가 아니라 myotherproject에 myclusteredtable이라는 이름의 클러스터링된 테이블을 만듭니다. 설명은 This is my clustered table로, 라벨은 organization:development로 설정됩니다. 이 명령어는 --table 대신 단축형 -t를 사용합니다. 이 명령어는 테이블 만료 시간을 지정하지 않습니다. 데이터 세트에 기본 테이블 만료 시간이 있으면, 그 값이 적용됩니다. 데이터 세트에 기본 테이블 만료 시간이 없으면 테이블이 만료되지 않습니다.

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

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

테이블을 만든 후 테이블의 설명 및 라벨을 업데이트할 수 있습니다.

Terraform

google_bigquery_table 리소스를 사용합니다.

참고: Terraform을 사용해서 BigQuery 객체를 만들려면 Cloud Resource Manager API를 사용 설정해야 합니다.

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

다음 예시에서는 ID 및 Created 열에 클러스터링된 mytable이라는 테이블을 만듭니다.

resource "google_bigquery_dataset" "default" {
  dataset_id                      = "mydataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

resource "google_bigquery_table" "default" {
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "mytable"
  deletion_protection = false # set to "true" in production

  clustering = ["ID", "Created"]

  schema = <<EOF
[
  {
    "name": "ID",
    "type": "INT64",
    "description": "Item ID"
  },
  {
    "name": "Item",
    "type": "STRING",
    "mode": "NULLABLE"
  },
 {
   "name": "Created",
   "type": "TIMESTAMP"
 }
]
EOF

}

Google Cloud 프로젝트에 Terraform 구성을 적용하려면 다음 섹션의 단계를 완료하세요.

Cloud Shell 준비

1. Cloud Shell을 실행합니다.

2. Terraform 구성을 적용할 기본 Google Cloud 프로젝트를 설정합니다.

   이 명령어는 프로젝트당 한 번만 실행하면 되며 어떤 디렉터리에서도 실행할 수 있습니다.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Terraform 구성 파일에서 명시적 값을 설정하면 환경 변수가 재정의됩니다.

디렉터리 준비

각 Terraform 구성 파일에는 자체 디렉터리(루트 모듈이라고도 함)가 있어야 합니다.

1. Cloud Shell에서 디렉터리를 만들고 해당 디렉터리 내에 새 파일을 만드세요. 파일 이름에는 .tf 확장자가 있어야 합니다(예: main.tf). 이 튜토리얼에서는 파일을 main.tf라고 합니다.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 튜토리얼을 따라 하는 경우 각 섹션이나 단계에서 샘플 코드를 복사할 수 있습니다.

   샘플 코드를 새로 만든 main.tf에 복사합니다.

   필요한 경우 GitHub에서 코드를 복사합니다. 이는 Terraform 스니펫이 엔드 투 엔드 솔루션의 일부인 경우에 권장됩니다.

3. 환경에 적용할 샘플 매개변수를 검토하고 수정합니다.
4. 변경사항을 저장합니다.
5. Terraform을 초기화합니다. 이 작업은 디렉터리당 한 번만 수행하면 됩니다.

   terraform init

   원하는 경우 최신 Google 공급업체 버전을 사용하려면 -upgrade 옵션을 포함합니다.

   terraform init -upgrade

변경사항 적용

1. 구성을 검토하고 Terraform에서 만들거나 업데이트할 리소스가 예상과 일치하는지 확인합니다.

   terraform plan

   필요에 따라 구성을 수정합니다.

2. 다음 명령어를 실행하고 프롬프트에 yes를 입력하여 Terraform 구성을 적용합니다.

   terraform apply

   Terraform에 '적용 완료' 메시지가 표시될 때까지 기다립니다.

3. 결과를 보려면 Google Cloud 프로젝트를 엽니다. Google Cloud 콘솔에서 UI의 리소스로 이동하여 Terraform이 리소스를 만들었거나 업데이트했는지 확인합니다.

참고: Terraform 샘플은 일반적으로 필요한 API가 Google Cloud 프로젝트에서 사용 설정되었다고 가정합니다.

API

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

Python

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

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

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

schema = [
    bigquery.SchemaField("full_name", "STRING"),
    bigquery.SchemaField("city", "STRING"),
    bigquery.SchemaField("zipcode", "INTEGER"),
]

table = bigquery.Table(table_id, schema=schema)
table.clustering_fields = ["city", "zipcode"]
table = client.create_table(table)  # Make an API request.
print(
    "Created clustered table {}.{}.{}".format(
        table.project, table.dataset_id, table.table_id
    )
)

Go

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

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

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
}

Java

이 샘플을 사용해 보기 전에 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.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());
    }
  }
}

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

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

• 새 대상 테이블에 결과를 쓰고 클러스터링 열을 지정합니다.
• DDL CREATE TABLE AS SELECT 문을 사용하여 만듭니다. 이 방법에 대한 자세한 내용은 데이터 정의 언어 문 사용 페이지의 쿼리 결과에서 클러스터링된 테이블 만들기를 참조하세요.

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

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

SQL

쿼리 결과에서 클러스터링된 테이블을 만들려면 CREATE TABLE DDL 문을 CLUSTER BY 옵션과 함께 사용합니다. 다음 예시에서는 기존의 클러스터링되지 않은 테이블을 쿼리하여 customer_id로 클러스터링된 새 테이블을 만듭니다.

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

   BigQuery로 이동

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

   CREATE TABLE mydataset.clustered_table
   (
     customer_id STRING,
     transaction_amount NUMERIC
   )
   CLUSTER BY
     customer_id
   AS (
     SELECT * FROM mydataset.unclustered_table
   );
   

3. 실행을 클릭합니다.

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

bq

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

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

다음을 바꿉니다.

• LOCATION: 위치의 이름. --location 플래그는 선택사항입니다. 예를 들어 도쿄 리전에서 BigQuery를 사용하는 경우에는 플래그 값을 asia-northeast1로 설정할 수 있습니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.
• QUERY: GoogleSQL 구문의 쿼리입니다. 현재, 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로 데이터 로드 소개를 참조하세요.

로드 작업 정의 시 클러스터링을 정의하려면 다음과 같이 하세요.

SQL

LOAD DATA 문을 사용합니다. 다음 예시는 AVRO 데이터를 로드하여 transaction_date 필드로 파티션을 나누고 customer_id 필드로 클러스터링된 테이블을 만듭니다. 또한 파티션이 3일 후 만료되도록 구성합니다.

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

   BigQuery로 이동

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

   LOAD DATA INTO mydataset.mytable
   PARTITION BY transaction_date
   CLUSTER BY customer_id
     OPTIONS (
       partition_expiration_days = 3)
   FROM FILES(
     format = 'AVRO',
     uris = ['gs://bucket/path/file.avro']);
   

3. 실행을 클릭합니다.

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

API

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

Go

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

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

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
}

Java

이 샘플을 사용해 보기 전에 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.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());
    }
  }
}

Python

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

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

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

job_config = bigquery.LoadJobConfig(
    skip_leading_rows=1,
    source_format=bigquery.SourceFormat.CSV,
    schema=[
        bigquery.SchemaField("timestamp", bigquery.SqlTypeNames.TIMESTAMP),
        bigquery.SchemaField("origin", bigquery.SqlTypeNames.STRING),
        bigquery.SchemaField("destination", bigquery.SqlTypeNames.STRING),
        bigquery.SchemaField("amount", bigquery.SqlTypeNames.NUMERIC),
    ],
    time_partitioning=bigquery.TimePartitioning(field="timestamp"),
    clustering_fields=["origin", "destination"],
)

job = client.load_table_from_uri(
    ["gs://cloud-samples-data/bigquery/sample-transactions/transactions.csv"],
    table_id,
    job_config=job_config,
)

job.result()  # Waits for the job to complete.

table = client.get_table(table_id)  # Make an API request.
print(
    "Loaded {} rows and {} columns to {}".format(
        table.num_rows, len(table.schema), table_id
    )
)

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

테이블 및 뷰에 대한 액세스를 구성하려면 허용되는 리소스 범위 순서(가장 큰 크기부터 가장 작은 크기 순서)대로 나열된 다음 수준의 항목에 IAM 역할을 부여하면 됩니다.

• Google Cloud 리소스 계층 구조의 상위 수준(예: 프로젝트, 폴더 또는 조직 수준)
• 데이터 세트 수준
• 테이블 또는 보기 수준

다음 방법을 사용해서 테이블 내에서 데이터 액세스를 제한할 수도 있습니다.

• 열 수준 보안
• 열 데이터 마스킹
• 행 수준 보안

IAM으로 보호되는 모든 리소스에 대한 액세스 권한은 적층식입니다. 예를 들어 항목이 프로젝트와 같은 높은 수준에서 액세스할 수 없는 경우 데이터 세트 수준에서 항목에 액세스 권한을 부여하면 해당 항목에서 데이터 세트의 테이블과 뷰에 액세스할 수 있습니다. 마찬가지로, 항목이 높은 수준 또는 데이터 세트 수준에서 액세스할 수 없는 경우 테이블 또는 뷰 수준에서 항목에 액세스 권한을 부여할 수 있습니다.

프로젝트, 폴더 또는 조직 수준과 같이 Google Cloud 리소스 계층 구조의 상위 수준에서 IAM 역할을 부여하면 포괄적인 리소스 집합에 대한 액세스 권한이 항목에 부여됩니다. 예를 들어 프로젝트 수준에서 항목에 역할을 부여하면 프로젝트의 모든 데이터 세트에 적용되는 권한이 항목에 부여됩니다.

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

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

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

IAM으로 보호되는 리소스에는 '거부' 권한을 설정할 수 없습니다.

역할 및 권한에 대한 자세한 내용은 IAM 문서의 역할 이해 및 BigQuery IAM 역할 및 권한을 참조하세요.

클러스터링된 테이블 사용

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

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

• Google Cloud 콘솔 사용
• bq 명령줄 도구의 bq show 명령어 사용
• tables.get API 메서드 호출
• INFORMATION_SCHEMA 뷰 쿼리

필수 권한

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

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

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

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

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

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

콘솔

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

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

   

SQL

클러스터링된 테이블의 경우 INFORMATION_SCHEMA.COLUMNS 뷰에서 CLUSTERING_ORDINAL_POSITION 열을 쿼리하여 테이블의 클러스터링 열에서 열의 1부터 시작하는 오프셋을 찾을 수 있습니다.

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

   BigQuery로 이동

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

   CREATE TABLE mydataset.data (column1 INT64, column2 INT64)
   CLUSTER BY column1, column2;
   SELECT
     column_name, clustering_ordinal_position
   FROM
     mydataset.INFORMATION_SCHEMA.COLUMNS;
   

3. 실행을 클릭합니다.

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

클러스터링 서수 위치는 column1은 1, column2는 2입니다. INFORMATION_SCHEMA의 TABLES, TABLE_OPTIONS, COLUMNS, COLUMN_FIELD_PATH 뷰를 통해 더 많은 테이블 메타데이터를 사용할 수 있습니다.

bq

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 메서드를 호출하고 관련 매개변수를 모두 제공합니다.

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

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

• Google Cloud 콘솔 사용
• bq 명령줄 도구의 bq ls 명령어 사용
• tables.list API 메서드 호출
• 클라이언트 라이브러리 사용
• INFORMATION_SCHEMA.COLUMNS 뷰의 CLUSTERING_ORDINAL_POSITION 열 쿼리

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

클러스터링 사양 수정

테이블의 클러스터링 사양을 변경 또는 삭제하거나 클러스터링된 테이블의 클러스터링된 열 집합을 변경할 수 있습니다. 클러스터링된 열 집합을 업데이트하는 방법은 연속 스트리밍 삽입을 사용하는 테이블에 유용합니다. 이러한 테이블은 다른 방법으로는 쉽게 바꿀 수 없기 때문입니다.

파티션을 나누지 않거나 파티션을 나눈 테이블에 새 클러스터링 사양을 적용하려면 다음 단계를 따르세요.

1. bq 도구에서 새 클러스터링과 일치하도록 테이블의 클러스터링 사양을 업데이트합니다.

    bq update --clustering_fields=CLUSTER_COLUMN DATASET.ORIGINAL_TABLE 

   다음을 바꿉니다.

   • CLUSTER_COLUMN: 클러스터링된 열(예: mycolumn)
   • DATASET: 테이블이 포함된 데이터 세트의 이름(예: mydataset)
   • ORIGINAL_TABLE: 원본 테이블의 이름(예: mytable)

   tables.update 또는 tables.patch API 메서드를 호출하여 클러스터링 사양을 수정할 수도 있습니다.

2. 새로운 클러스터링 사양에 따라 모든 행을 클러스터링하려면 다음 UPDATE 문을 실행합니다.

   UPDATE DATASET.ORIGINAL_TABLE SET CLUSTER_COLUMN=CLUSTER_COLUMN WHERE true
   

   참고: 장기 스토리지에 있는 테이블에 새 클러스터링 사양이 적용되면 테이블은 활성 스토리지 가격으로 되돌아갑니다. 자세한 내용은 스토리지 가격 책정을 참조하세요.

테이블 보안

BigQuery에서 테이블에 대한 액세스를 제어하려면 테이블 액세스 제어 소개를 참조하세요.

다음 단계

• 클러스터링된 테이블 쿼리에 대한 자세한 내용은 클러스터링된 테이블 쿼리를 참조하세요.
• BigQuery의 파티션을 나눈 테이블 지원 개요는 파티션을 나눈 테이블 소개를 참조하세요.
• 파티션을 나눈 테이블을 만드는 방법은 파티션을 나눈 테이블 만들기를 참조하세요.
• BigQuery INFORMATION_SCHEMA 소개에서 INFORMATION_SCHEMA의 개요 참조