테이블 만들기 및 사용

이 문서에서는 BigQuery에서 표준(기본 제공) 테이블을 만들고 사용하는 방법을 설명합니다. 다른 테이블 유형 만들기에 대한 자세한 내용은 다음을 참조하세요.

• 파티션을 나눈 테이블 만들기
• 클러스터링된 테이블 만들기 및 사용

테이블을 만든 후에는 다음과 같은 작업을 수행할 수 있습니다.

• 테이블 데이터에 대한 액세스 제어
• 테이블에 대한 정보 가져오기
• 데이터 세트의 테이블 나열
• 테이블 메타데이터 가져오기

테이블 속성 업데이트, 테이블 복사, 테이블 삭제를 비롯하여 테이블 관리에 대한 자세한 내용은 테이블 관리를 참조하세요.

시작하기 전에

BigQuery에서 테이블을 만들기 전에 먼저 다음을 수행하세요.

• BigQuery 시작 가이드에 따라 프로젝트를 설정합니다.
• 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으로 바뀝니다.

테이블 만들기

다음 방법으로 BigQuery에서 테이블을 만들 수 있습니다.

• Google Cloud 콘솔 또는 bq 명령줄 도구 bq mk 명령어를 사용하여 수동으로 만들기
• tables.insert API 메서드를 호출하여 프로그래매틱 방식으로 만들기
• 클라이언트 라이브러리를 사용하여 만들기
• 쿼리 결과에서 만들기
• 외부 데이터 소스를 참조하는 테이블을 정의하여 만들기
• 데이터를 로드할 때 만들기
• CREATE TABLE 데이터 정의 언어(DDL) 문을 사용하여 만듭니다.

필수 권한

테이블을 만들려면 다음 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 역할과 권한에 대한 자세한 내용은 사전 정의된 역할 및 권한을 참조하세요.

스키마 정의가 있는 빈 테이블 만들기

다음 방법으로 스키마 정의가 있는 빈 테이블을 만들 수 있습니다.

• Google Cloud 콘솔을 사용하여 스키마를 입력합니다.
• bq 명령줄 도구를 사용하여 스키마를 인라인으로 제공합니다.
• bq 명령줄 도구를 사용하여 JSON 스키마 파일을 제출합니다.
• API의 tables.insert 메서드를 호출할 때 테이블 리소스에 스키마를 제공합니다.

테이블 스키마 지정에 대한 자세한 내용은 스키마 지정을 참조하세요.

테이블을 만든 후에는 테이블에 데이터를 로드하거나 쿼리 결과를 쓰는 방법으로 테이블을 채울 수 있습니다.

스키마 정의가 있는 빈 테이블을 만들려면 다음 안내를 따르세요.

콘솔

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. 선택사항: 파티션 및 클러스터 설정을 지정합니다. 자세한 내용은 파티션을 나눈 테이블 만들기 및 클러스터링된 테이블 만들기 및 사용을 참조하세요.
5. 선택사항: 고급 옵션 섹션에서 고객 관리 암호화 키를 사용하려면 고객 관리 암호화 키(CMEK) 사용 옵션을 선택합니다. 기본적으로 BigQuery는 Google에서 소유한 Google 관리 키를 사용하여 저장된 고객 콘텐츠를 암호화합니다.
6. 테이블 만들기를 클릭합니다.

참고: Google Cloud 콘솔을 사용하여 빈 테이블을 만들 때는 라벨, 설명 또는 만료 시간을 추가할 수 없습니다. 테이블을 만들 때 bq 명령줄 도구 또는 API를 사용하여 이러한 선택적 속성을 추가할 수 있습니다. Google Cloud 콘솔에서 테이블을 만든 후에 만료 시간, 설명, 라벨을 추가할 수 있습니다.

SQL

다음 예시에서는 2023년 1월 1일에 만료되는 newtable라는 테이블을 만듭니다.

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

   BigQuery로 이동

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

   CREATE TABLE mydataset.newtable (
     x INT64 OPTIONS (description = 'An optional INTEGER field'),
     y STRUCT <
       a ARRAY <STRING> OPTIONS (description = 'A repeated STRING field'),
       b BOOL
     >
   ) OPTIONS (
       expiration_timestamp = TIMESTAMP '2023-01-01 00:00:00 UTC',
       description = 'a table that expires in 2023',
       labels = [('org_unit', 'development')]);
   

3. 실행을 클릭합니다.

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

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. --table 또는 -t 플래그와 함께 bq mk 명령어를 사용합니다. 인라인으로 또는 JSON 스키마 파일을 사용하여 테이블 스키마 정보를 제공할 수 있습니다. 전체 파라미터 목록은 bq mk --table 참조를 확인하세요. 선택적 파라미터는 다음과 같습니다.

   • --expiration
   • --description
   • --time_partitioning_field
   • --time_partitioning_type
   • --range_partitioning
   • --clustering_fields
   • --destination_kms_key
   • --label

   여기서는 --time_partitioning_field, --time_partitioning_type, --range_partitioning, --clustering_fields, --destination_kms_key를 설명하지 않습니다. 이러한 선택적 매개변수에 대한 자세한 내용은 다음 링크를 참조하세요.

   • --time_partitioning_field, --time_partitioning_type, --range_partitioning에 대한 자세한 내용은 파티션을 나눈 테이블을 참조하세요.
   • --clustering_fields에 대한 자세한 내용은 클러스터링된 테이블을 참조하세요.
   • --destination_kms_key에 대한 자세한 내용은 고객 관리 암호화 키를 참조하세요.

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

   기존 데이터 세트에 스키마 정의가 있는 빈 테이블을 만들려면 다음을 입력합니다.

   bq mk \
   --table \
   --expiration=integer \
   --description=description \
   --label=key_1:value_1 \
   --label=key_2:value_2 \
   --add_tags=key_3:value_3[,...] \
   project_id:dataset.table \
   schema
   

   다음을 바꿉니다.

   • integer은 테이블의 기본 수명(단위: 초)입니다. 최솟값은 3,600초(1시간)입니다. 만료 시간은 현재 UTC 시간과 정수 값을 더한 값으로 계산됩니다. 테이블을 만들 때 만료 시간을 설정하면 데이터 세트의 기본 테이블 만료 시간 설정이 무시됩니다.
   • description은 따옴표로 묶은 테이블 설명입니다.
   • key_1:value_1 및 key_2:value_2는 라벨을 지정하는 키-값 쌍입니다.
   • key_3:value_3는 태그를 지정하는 키-값 쌍입니다. 키-값 쌍 사이 쉼표를 사용하여 동일한 플래그 아래에 여러 태그를 추가합니다.
   • project_id는 프로젝트 ID입니다.
   • dataset는 프로젝트의 데이터 세트입니다.
   • table은 만드는 테이블의 이름입니다.
   • schema는 field:data_type,field:data_type 형식의 인라인 스키마 정의이거나 로컬 머신의 JSON 스키마 파일 경로입니다.

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

   예:

   인라인 스키마 정의를 사용하여 테이블을 만들려면 다음 명령어를 입력합니다. 이 명령어는 기본 프로젝트의 mydataset에 mytable이라는 테이블을 만듭니다. 테이블 만료는 3,600초(1시간)로, 설명은 This is my table로, 라벨은 organization:development로 설정됩니다. 이 명령어는 --table 대신 단축형 -t를 사용합니다. 스키마는 qtr:STRING,sales:FLOAT,year:STRING과 같이 인라인으로 지정됩니다.

   bq mk \
    -t \
    --expiration 3600 \
    --description "This is my table" \
    --label organization:development \
    mydataset.mytable \
    qtr:STRING,sales:FLOAT,year:STRING
   

   JSON 스키마 파일을 사용하여 테이블을 만들려면 다음 명령어를 입력합니다. 이 명령어는 기본 프로젝트의 mydataset에 mytable이라는 테이블을 만듭니다. 테이블 만료는 3,600초(1시간)로, 설명은 This is my table로, 라벨은 organization:development로 설정됩니다. 스키마 파일의 경로는 /tmp/myschema.json입니다.

   bq mk \
    --table \
    --expiration 3600 \
    --description "This is my table" \
    --label organization:development \
    mydataset.mytable \
    /tmp/myschema.json
   

   JSON 스키마 파일을 사용하여 테이블을 만들려면 다음 명령어를 입력합니다. 이 명령어는 myotherproject의 mydataset에 mytable이라는 테이블을 만듭니다. 테이블 만료는 3,600초(1시간)로, 설명은 This is my table로, 라벨은 organization:development로 설정됩니다. 스키마 파일의 경로는 /tmp/myschema.json입니다.

   bq mk \
    --table \
    --expiration 3600 \
    --description "This is my table" \
    --label organization:development \
    myotherproject:mydataset.mytable \
    /tmp/myschema.json
   

   테이블을 만든 후 테이블의 만료 시간, 설명, 라벨을 업데이트할 수 있습니다. 또한 스키마 정의를 수정할 수 있습니다.

Terraform

google_bigquery_table 리소스를 사용합니다.

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

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

테이블 만들기

다음 예시에서는 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

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

}

테이블 만들기 및 액세스 권한 부여

다음 예시에서는 mytable이라는 테이블을 만든 후 google_bigquery_table_iam_policy 리소스를 사용해서 액세스 권한을 부여합니다. 테이블이 있는 데이터 세트에 액세스 권한이 없는 주 구성원에게 테이블 액세스 권한을 부여하려는 경우에만 이 단계를 수행합니다.

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

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

}

data "google_iam_policy" "default" {
  binding {
    role = "roles/bigquery.dataOwner"
    members = [
      "user:[e-mail]",
    ]
  }
}

resource "google_bigquery_table_iam_policy" "policy" {
  dataset_id  = google_bigquery_table.default.dataset_id
  table_id    = google_bigquery_table.default.table_id
  policy_data = data.google_iam_policy.default.policy_data
}

고객 관리 암호화 키로 테이블 만들기

다음 예시에서는 mytable이라는 테이블을 만들고 google_kms_crypto_key 및 google_kms_key_ring 리소스도 사용해서 테이블에 대해 Cloud Key Management Service 키를 지정합니다. 이 예시를 실행하기 전에 Cloud Key Management Service API를 사용 설정해야 합니다.

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

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

  encryption_configuration {
    kms_key_name = google_kms_crypto_key.crypto_key.id
  }

  depends_on = [google_project_iam_member.service_account_access]
}

resource "google_kms_crypto_key" "crypto_key" {
  name     = "example-key"
  key_ring = google_kms_key_ring.key_ring.id
}

resource "random_id" "default" {
  byte_length = 8
}

resource "google_kms_key_ring" "key_ring" {
  name     = "${random_id.default.hex}-example-keyring"
  location = "us"
}

# Enable the BigQuery service account to encrypt/decrypt Cloud KMS keys
data "google_project" "project" {
}

resource "google_project_iam_member" "service_account_access" {
  project = data.google_project.project.project_id
  role    = "roles/cloudkms.cryptoKeyEncrypterDecrypter"
  member  = "serviceAccount:bq-${data.google_project.project.number}@bigquery-encryption.iam.gserviceaccount.com"
}

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

테이블 리소스가 정의된 tables.insert 메서드를 호출합니다.

C#

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

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

using Google.Cloud.BigQuery.V2;

public class BigQueryCreateTable
{
    public BigQueryTable CreateTable(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var dataset = client.GetDataset(datasetId);
        // Create schema for new table.
        var schema = new TableSchemaBuilder
        {
            { "full_name", BigQueryDbType.String },
            { "age", BigQueryDbType.Int64 }
        }.Build();
        // Create the table
        return dataset.CreateTable(tableId: "your_table_id", schema: schema);
    }
}

Go

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

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

import (
	"context"
	"fmt"
	"time"

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

// createTableExplicitSchema demonstrates creating a new BigQuery table and specifying a schema.
func createTableExplicitSchema(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: "full_name", Type: bigquery.StringFieldType},
		{Name: "age", Type: bigquery.IntegerFieldType},
	}

	metaData := &bigquery.TableMetadata{
		Schema:         sampleSchema,
		ExpirationTime: time.Now().AddDate(1, 0, 0), // Table will be automatically deleted in 1 year.
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, metaData); err != nil {
		return err
	}
	return nil
}

자바

이 샘플을 사용해 보기 전에 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.Field;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.TableDefinition;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

public class CreateTable {

  public static void runCreateTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    Schema schema =
        Schema.of(
            Field.of("stringField", StandardSQLTypeName.STRING),
            Field.of("booleanField", StandardSQLTypeName.BOOL));
    createTable(datasetName, tableName, schema);
  }

  public static void createTable(String datasetName, String tableName, Schema schema) {
    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);
      TableDefinition tableDefinition = StandardTableDefinition.of(schema);
      TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

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

Node.js

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

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

// Import the Google Cloud client library and create a client
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function createTable() {
  // Creates a new table named "my_table" in "my_dataset".

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";
  // const schema = 'Name:string, Age:integer, Weight:float, IsMagic:boolean';

  // For all options, see https://cloud.google.com/bigquery/docs/reference/v2/tables#resource
  const options = {
    schema: schema,
    location: 'US',
  };

  // Create a new table in the dataset
  const [table] = await bigquery
    .dataset(datasetId)
    .createTable(tableId, options);

  console.log(`Table ${table.id} created.`);
}

PHP

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

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

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableId = 'The BigQuery table ID';
// $fields = [
//    [
//        'name' => 'field1',
//        'type' => 'string',
//        'mode' => 'required'
//    ],
//    [
//        'name' => 'field2',
//        'type' => 'integer'
//    ],
//];

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$schema = ['fields' => $fields];
$table = $dataset->createTable($tableId, ['schema' => $schema]);
printf('Created table %s' . PHP_EOL, $tableId);

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", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
]

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

Ruby

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

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

require "google/cloud/bigquery"

def create_table dataset_id = "my_dataset"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table_id = "my_table"

  table = dataset.create_table table_id do |updater|
    updater.string  "full_name", mode: :required
    updater.integer "age",       mode: :required
  end

  puts "Created table: #{table_id}"
end

스키마 정의가 없는 빈 테이블 만들기

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.Schema;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.TableDefinition;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

// Sample to create a table without schema
public class CreateTableWithoutSchema {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    createTableWithoutSchema(datasetName, tableName);
  }

  public static void createTableWithoutSchema(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);
      TableDefinition tableDefinition = StandardTableDefinition.of(Schema.of());
      TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

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

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

쿼리 결과에서 테이블을 만들려면 결과를 대상 테이블에 써야 합니다.

콘솔

1. Google Cloud 콘솔에서 BigQuery 페이지를 엽니다.

   BigQuery 페이지로 이동

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

3. 유효한 SQL 쿼리를 입력하세요.

4. 더보기를 클릭한 다음 쿼리 옵션을 선택합니다.

   

5. 쿼리 결과의 대상 테이블 설정 옵션을 선택합니다.

   

6. 대상 섹션에서 테이블을 만들 데이터 세트를 선택한 다음 테이블 ID를 선택합니다.

7. 대상 테이블 쓰기 환경설정 섹션에서 다음 중 하나를 선택합니다.

   • 비어 있으면 쓰기 — 테이블이 비어 있는 경우에만 쿼리 결과를 테이블에 씁니다.
   • 테이블에 추가 — 쿼리 결과를 기존 테이블에 추가합니다.
   • 테이블 덮어쓰기 — 쿼리 결과를 사용하여 기존 테이블을 같은 이름으로 덮어씁니다.

8. (선택사항) 데이터 위치에서 해당 위치를 선택합니다.

9. 쿼리 설정을 업데이트하려면 저장을 클릭합니다.

10. 실행을 클릭합니다. 그러면 지정한 테이블에 쿼리 결과를 쓰는 쿼리 작업이 생성됩니다.

또는 쿼리를 실행하기 전에 대상 테이블 지정을 잊은 경우 편집기 위의 결과 저장 버튼을 클릭하여 캐시된 결과 테이블을 영구 테이블에 복사할 수 있습니다.

SQL

다음 예시에서는 CREATE TABLE 문을 사용하여 공개 bikeshare_trips 테이블의 데이터로부터 trips 테이블을 만듭니다.

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

   BigQuery로 이동

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

   CREATE TABLE mydataset.trips AS (
     SELECT
       bike_id,
       start_time,
       duration_minutes
     FROM
       bigquery-public-data.austin_bikeshare.bikeshare_trips
   );
   

3. 실행을 클릭합니다.

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

자세한 내용은 기존 테이블에서 새 테이블 만들기를 참조하세요.

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. bq query 명령어를 입력하고 --destination_table 플래그를 지정하여 쿼리 결과에 기반한 영구 테이블을 만듭니다. GoogleSQL 구문을 사용하려면 use_legacy_sql=false 플래그를 지정합니다. 기본 프로젝트에 없는 테이블에 쿼리 결과를 쓰려면 프로젝트 ID를 project_id:dataset 형식으로 데이터 세트 이름에 추가합니다.

   (선택사항) --location 플래그를 지정하고 값을 사용자 위치로 설정합니다.

   기존 대상 테이블의 쓰기 처리를 제어하려면 다음 플래그 옵션 중 하나를 지정합니다.

   • --append_table: 대상 테이블이 있으면 쿼리 결과가 테이블에 추가됩니다.

   • --replace: 대상 테이블이 있으면 쿼리 결과로 테이블을 덮어씁니다.

     bq --location=location query \
     --destination_table project_id:dataset.table \
     --use_legacy_sql=false 'query'
     

     다음을 바꿉니다.

   • location은 쿼리 처리에 사용되는 위치의 이름입니다. --location 플래그는 선택사항입니다. 예를 들어 도쿄 리전에서 BigQuery를 사용한다면 플래그 값을 asia-northeast1로 설정할 수 있습니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.

   • project_id는 프로젝트 ID입니다.

   • dataset는 쿼리 결과를 쓸 테이블이 포함된 데이터 세트의 이름입니다.

   • table은 쿼리 결과를 쓸 테이블의 이름입니다.

   • query는 GoogleSQL 구문의 쿼리입니다.

     쓰기 처리 플래그를 지정하지 않으면 비어 있는 경우에만 테이블에 결과를 쓰는 것이 기본 동작입니다. 테이블이 있지만 비어 있지 않으면 다음 오류가 반환됩니다. `BigQuery error in query operation: Error processing job project_id:bqjob_123abc456789_00000e1234f_1': Already Exists: Table project_id:dataset.table.

     예:

     참고: 이 예시에서는 미국 기반의 공개 데이터 세트를 쿼리합니다. 공개 데이터 세트가 미국의 멀티 리전 위치에 저장되기 때문에, 대상 테이블을 포함하는 데이터 세트도 미국에 있어야 합니다. 한 위치에서 데이터 세트를 쿼리하고 결과를 다른 위치에 있는 대상 테이블에 기록할 수는 없습니다.

     mydataset에 있는 mytable이라는 대상 테이블에 쿼리 결과를 쓰려면 다음 명령어를 입력합니다. 데이터 세트는 기본 프로젝트에 있습니다. 명령어에 쓰기 처리 플래그가 지정되지 않았으므로 테이블은 새 테이블이거나 비어 있어야 합니다. 그렇지 않으면 Already exists 오류가 반환됩니다. 쿼리는 USA Name Data 공개 데이터 세트에서 데이터를 검색합니다.

     bq query \
     --destination_table mydataset.mytable \
     --use_legacy_sql=false \
     'SELECT
     name,
     number
     FROM
     `bigquery-public-data`.usa_names.usa_1910_current
     WHERE
     gender = "M"
     ORDER BY
     number DESC'
     

     쿼리 결과를 사용하여 mydataset에 있는 mytable이라는 대상 테이블을 덮어쓰려면 다음 명령어를 입력합니다. 데이터 세트는 기본 프로젝트에 있습니다. 이 명령어는 --replace 플래그를 사용하여 대상 테이블을 덮어씁니다.

     bq query \
     --destination_table mydataset.mytable \
     --replace \
     --use_legacy_sql=false \
     'SELECT
     name,
     number
     FROM
     `bigquery-public-data`.usa_names.usa_1910_current
     WHERE
     gender = "M"
     ORDER BY
     number DESC'
     

     mydataset에 있는 mytable이라는 대상 테이블에 쿼리 결과를 추가하려면 다음 명령어를 입력합니다. 데이터 세트는 기본 프로젝트가 아닌 my-other-project에 있습니다. 이 명령어는 --append_table 플래그를 사용하여 쿼리 결과를 대상 테이블에 추가합니다.

     bq query \
     --append_table \
     --use_legacy_sql=false \
     --destination_table my-other-project:mydataset.mytable \
     'SELECT
     name,
     number
     FROM
     `bigquery-public-data`.usa_names.usa_1910_current
     WHERE
     gender = "M"
     ORDER BY
     number DESC'
     

     이러한 각 예시의 출력은 다음과 같습니다. 읽기 편하도록 출력 일부는 잘려 있습니다.

     Waiting on bqjob_r123abc456_000001234567_1 ... (2s) Current status: DONE
     +---------+--------+
     |  name   | number |
     +---------+--------+
     | Robert  |  10021 |
     | John    |   9636 |
     | Robert  |   9297 |
     | ...              |
     +---------+--------+
     

API

쿼리 결과를 영구 테이블에 저장하려면 jobs.insert 메서드를 호출하고, query 작업을 구성하고, destinationTable 속성의 값을 포함합니다. 기존 대상 테이블의 쓰기 처리를 제어하려면 writeDisposition 속성을 구성합니다.

쿼리 작업의 처리 위치를 제어하려면 작업 리소스의 jobReference 섹션에 location 속성을 지정합니다.

Go

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

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

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// queryWithDestination demonstrates saving the results of a query to a specific table by setting the destination
// via the API properties.
func queryWithDestination(w io.Writer, 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()

	q := client.Query("SELECT 17 as my_col")
	q.Location = "US" // Location must match the dataset(s) referenced in query.
	q.QueryConfig.Dst = client.Dataset(destDatasetID).Table(destTableID)
	// Run the query and print results when the query job is completed.
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}
	it, err := job.Read(ctx)
	for {
		var row []bigquery.Value
		err := it.Next(&row)
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintln(w, row)
	}
	return nil
}

자바

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

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

쿼리 결과를 영구 테이블에 저장하려면 QueryJobConfiguration에서 대상 테이블을 원하는 TableId로 설정합니다.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableId;

public class SaveQueryToTable {

  public static void runSaveQueryToTable() {
    // TODO(developer): Replace these variables before running the sample.
    String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
    String destinationTable = "MY_TABLE";
    String destinationDataset = "MY_DATASET";

    saveQueryToTable(destinationDataset, destinationTable, query);
  }

  public static void saveQueryToTable(
      String destinationDataset, String destinationTableId, String query) {
    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();

      // Identify the destination table
      TableId destinationTable = TableId.of(destinationDataset, destinationTableId);

      // Build the query job
      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query).setDestinationTable(destinationTable).build();

      // Execute the query.
      bigquery.query(queryConfig);

      // The results are now saved in the destination table.

      System.out.println("Saved query ran successfully");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Saved query did not run \n" + e.toString());
    }
  }
}

Node.js

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

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

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function queryDestinationTable() {
  // Queries the U.S. given names dataset for the state of Texas
  // and saves results to permanent table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // Create destination table reference
  const dataset = bigquery.dataset(datasetId);
  const destinationTable = dataset.table(tableId);

  const query = `SELECT name
    FROM \`bigquery-public-data.usa_names.usa_1910_2013\`
    WHERE state = 'TX'
    LIMIT 100`;

  // For all options, see https://cloud.google.com/bigquery/docs/reference/v2/tables#resource
  const options = {
    query: query,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
    destination: destinationTable,
  };

  // Run the query as a job
  const [job] = await bigquery.createQueryJob(options);

  console.log(`Job ${job.id} started.`);
  console.log(`Query results loaded to table ${destinationTable.id}`);
}

Python

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

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

쿼리 결과를 영구 테이블에 저장하려면 QueryJobConfig를 만들고 대상을 원하는 TableReference로 설정합니다. 작업 구성을 쿼리 메서드에 전달합니다.

from google.cloud import bigquery

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

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

job_config = bigquery.QueryJobConfig(destination=table_id)

sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""

# Start the query, passing in the extra configuration.
query_job = client.query(sql, job_config=job_config)  # Make an API request.
query_job.result()  # Wait for the job to complete.

print("Query results loaded to the table {}".format(table_id))

외부 데이터 소스를 참조하는 테이블 만들기

외부 데이터 소스는 데이터가 BigQuery 스토리지에 저장되어 있지 않더라도 BigQuery에서 직접 쿼리할 수 있는 데이터 소스입니다. 예를 들어 다른 Google Cloud 데이터베이스, Cloud Storage의 파일 또는 다른 클라우드 제품에 BigQuery에서 분석하려는 데이터가 있는데 마이그레이션 준비가 되지 않았을 수 있습니다.

자세한 내용은 외부 데이터 소스 소개를 참조하세요.

데이터 로드 시 테이블 만들기

BigQuery로 데이터를 로드할 때 데이터를 새 테이블 또는 파티션으로 로드할 수도 있고, 데이터를 기존 테이블 또는 파티션에 추가할 수도 있으며, 테이블 또는 파티션을 덮어쓸 수도 있습니다. 데이터를 로드하기 전에 빈 테이블을 만들지 않아도 됩니다. 새 테이블을 만들면서 동시에 데이터를 로드할 수 있습니다.

데이터를 BigQuery로 로드하면 테이블 또는 파티션 스키마를 제공할 수 있으며, 지원되는 데이터 형식인 경우에는 스키마 자동 감지를 사용할 수 있습니다.

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

테이블에 대한 액세스 제어

테이블 및 뷰에 대한 액세스를 구성하려면 허용되는 리소스 범위 순서(가장 큰 크기부터 가장 작은 크기 순서)대로 나열된 다음 수준의 항목에 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. 탐색 패널의 리소스 섹션에서 프로젝트를 펼친 후 데이터 세트를 선택합니다.

2. 데이터세트 이름을 클릭하여 펼칩니다. 데이터 세트의 테이블과 뷰가 표시됩니다.

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

4. 세부정보 패널에서 세부정보를 클릭하여 테이블 설명과 테이블 정보를 표시합니다.

5. 선택적으로 스키마 탭으로 전환하여 테이블의 스키마 정의를 봅니다.

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

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

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

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

   각 항목의 의미는 다음과 같습니다.

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

   예:

   다음 명령어를 입력하여 mydataset의 mytable 관련 정보를 모두 표시합니다. mydataset는 기본 프로젝트에 있습니다.

   bq show --format=prettyjson mydataset.mytable
   

   다음 명령어를 입력하여 mydataset의 mytable 관련 정보를 모두 표시합니다. mydataset는 기본 프로젝트가 아닌 myotherproject에 있습니다.

   bq show --format=prettyjson myotherproject:mydataset.mytable
   

   mydataset의 mytable 관련 스키마 정보만 표시하려면 다음 명령어를 입력합니다. mydataset는 기본 프로젝트가 아닌 myotherproject에 있습니다.

   bq show --schema --format=prettyjson myotherproject:mydataset.mytable
   

API

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

Go

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

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

import (
	"context"
	"fmt"
	"io"

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

// printTableInfo demonstrates fetching metadata from a table and printing some basic information
// to an io.Writer.
func printTableInfo(w io.Writer, projectID, datasetID, tableID 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()

	meta, err := client.Dataset(datasetID).Table(tableID).Metadata(ctx)
	if err != nil {
		return err
	}
	// Print basic information about the table.
	fmt.Fprintf(w, "Schema has %d top-level fields\n", len(meta.Schema))
	fmt.Fprintf(w, "Description: %s\n", meta.Description)
	fmt.Fprintf(w, "Rows in managed storage: %d\n", meta.NumRows)
	return nil
}

자바

이 샘플을 사용해 보기 전에 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.Table;
import com.google.cloud.bigquery.TableId;

public class GetTable {

  public static void runGetTable() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "bigquery_public_data";
    String datasetName = "samples";
    String tableName = "shakespeare";
    getTable(projectId, datasetName, tableName);
  }

  public static void getTable(String projectId, 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(projectId, datasetName, tableName);
      Table table = bigquery.getTable(tableId);
      System.out.println("Table info: " + table.getDescription());
    } catch (BigQueryException e) {
      System.out.println("Table not retrieved. \n" + e.toString());
    }
  }
}

Node.js

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

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

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function getTable() {
  // Retrieves table named "my_table" in "my_dataset".

  /**
   * TODO(developer): Uncomment the following lines before running the sample
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";

  // Retrieve table reference
  const dataset = bigquery.dataset(datasetId);
  const [table] = await dataset.table(tableId).get();

  console.log('Table:');
  console.log(table.metadata.tableReference);
}
getTable();

PHP

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

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

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
//$projectId = 'The Google project ID';
//$datasetId = 'The BigQuery dataset ID';
//$tableId   = 'The BigQuery table ID';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);

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 model to fetch.
# table_id = 'your-project.your_dataset.your_table'

table = client.get_table(table_id)  # Make an API request.

# View table properties
print(
    "Got table '{}.{}.{}'.".format(table.project, table.dataset_id, table.table_id)
)
print("Table schema: {}".format(table.schema))
print("Table description: {}".format(table.description))
print("Table has {} rows".format(table.num_rows))

INFORMATION_SCHEMA를 사용하여 테이블 정보 가져오기

INFORMATION_SCHEMA는 데이터 세트, 루틴, 테이블, 뷰, 작업, 예약, 데이터 스트리밍에 대한 메타데이터에 액세스할 수 있는 일련의 뷰입니다.

다음 뷰를 쿼리하여 테이블 정보를 가져올 수 있습니다.

• INFORMATION_SCHEMA.TABLES 및 INFORMATION_SCHEMA.TABLE_OPTIONS 뷰를 사용하여 프로젝트의 테이블 및 뷰에 대한 메타데이터를 가져옵니다.
• INFORMATION_SCHEMA.COLUMNS 및 INFORMATION_SCHEMA.COLUMN_FIELD_PATHS 뷰를 사용하여 테이블의 열(필드)에 대한 메타데이터를 검색합니다.
• INFORMATION_SCHEMA.TABLE_STORAGE 뷰를 사용하여 테이블별로 현재 및 이전 스토리지 사용량에 대한 메타데이터를 검색합니다.

TABLES 및 TABLE_OPTIONS 뷰에는 뷰에 대한 대략적인 정보도 포함되어 있습니다. 자세한 정보를 보려면 INFORMATION_SCHEMA.VIEWS 뷰를 대신 쿼리하세요.

TABLES 뷰

INFORMATION_SCHEMA.TABLES 뷰를 쿼리하면 데이터 세트의 각 테이블 또는 뷰당 하나의 행이 쿼리 결과에 포함됩니다. 뷰에 대한 자세한 내용은 INFORMATION_SCHEMA.VIEWS 뷰를 대신 쿼리하세요.

INFORMATION_SCHEMA.TABLES 뷰에는 다음과 같은 스키마가 있습니다.

열 이름	데이터 유형	값
table_catalog	STRING	데이터 세트가 포함된 프로젝트의 프로젝트 ID
table_schema	STRING	테이블이나 뷰가 포함된 데이터 세트 이름(datasetId라고도 함)
table_name	STRING	테이블 또는 뷰의 이름(tableId라고도 함)
table_type	STRING	테이블 유형. 다음 중 하나입니다. BASE TABLE: 표준 테이블 CLONE: 테이블 클론 SNAPSHOT: 테이블 스냅샷 VIEW: 뷰 MATERIALIZED VIEW: 구체화된 뷰 또는 구체화된 뷰 복제본 EXTERNAL: 외부 데이터 소스를 참조하는 테이블
is_insertable_into	STRING	테이블의 DML INSERT 문 지원 여부에 따라 YES 또는 NO
is_typed	STRING	값이 항상 NO임
creation_time	TIMESTAMP	테이블 생성 시간
base_table_catalog	STRING	테이블 클론 및 테이블 스냅샷의 경우 기본 테이블의 프로젝트입니다. table_type이 CLONE 또는 SNAPSHOT으로 설정된 테이블에만 적용됩니다.
base_table_schema	STRING	테이블 클론 및 테이블 스냅샷의 경우 기본 테이블의 데이터 세트입니다. table_type이 CLONE 또는 SNAPSHOT으로 설정된 테이블에만 적용됩니다.
base_table_name	STRING	테이블 클론 및 테이블 스냅샷의 경우 기본 테이블의 이름입니다. table_type이 CLONE 또는 SNAPSHOT으로 설정된 테이블에만 적용됩니다.
snapshot_time_ms	TIMESTAMP	테이블 클론 및 테이블 스냅샷의 경우 이 테이블을 만들기 위해 기본 테이블에서 클론 또는 스냅샷 작업이 실행된 시간입니다. 시간 이동이 사용된 경우 이 필드에 시간 이동 타임스탬프가 포함됩니다. 그렇지 않으면 snapshot_time_ms 필드가 creation_time 필드와 동일합니다. table_type이 CLONE 또는 SNAPSHOT으로 설정된 테이블에만 적용됩니다.
replica_source_catalog	STRING	구체화된 뷰 복제본의 경우 기본 구체화된 뷰의 프로젝트입니다.
replica_source_schema	STRING	구체화된 뷰 복제본의 경우 기본 구체화된 뷰의 데이터 세트입니다.
replica_source_name	STRING	구체화된 뷰 복제본의 경우 기본 구체화된 뷰의 이름입니다.
replication_status	STRING	구체화된 뷰 복제본의 경우 기본 구체화된 뷰에서 구체화된 뷰 복제본으로의 복제 상태로, 다음 중 하나입니다. REPLICATION_STATUS_UNSPECIFIED ACTIVE: 복제가 오류 없이 활성 상태입니다. SOURCE_DELETED: 소스 구체화된 뷰가 삭제되었습니다. PERMISSION_DENIED: 구체화 뷰를 생성한 쿼리에 사용된 소스 Amazon S3 BigLake 테이블이 포함된 데이터 세트에 대해 소스 구체화 뷰가 승인되지 않았습니다. UNSUPPORTED_CONFIGURATION: 소스 구체화된 뷰 승인 이외의 복제본 기본 요건에 문제가 있습니다.
replication_error	STRING	replication_status가 구체화된 뷰 복제본의 복제 문제를 나타내는 경우 replication_error에서 문제에 대한 추가 세부정보를 제공합니다.
ddl	STRING	CREATE TABLE 또는 CREATE VIEW와 같은 테이블을 다시 만드는 데 사용할 수 있는 DDL 문
default_collation_name	STRING	기본 대조 사양 이름(있는 경우)입니다. 그 외의 경우는 NULL입니다.
upsert_stream_apply_watermark	TIMESTAMP	변경 데이터 캡처(CDC)를 사용하는 테이블의 경우 행 수정이 마지막으로 적용된 시간입니다. 자세한 내용은 테이블 upsert 작업 진행률 모니터링을 참조하세요.

예시

예시 1:

다음 예시에서는 이름이 mydataset인 데이터 세트에 있는 모든 테이블의 테이블 메타데이터를 검색합니다. 반환되는 메타데이터는 기본 프로젝트에서 mydataset에 있는 모든 테이블 유형에 사용됩니다.

mydataset에는 다음 테이블이 포함되어 있습니다.

• mytable1: 표준 BigQuery 테이블
• myview1: BigQuery 뷰

기본 프로젝트가 아닌 프로젝트에 쿼리를 실행하려면 프로젝트 ID를 `project_id`.dataset.INFORMATION_SCHEMA.view 형식으로 데이터 세트에 추가합니다(예: `myproject`.mydataset.INFORMATION_SCHEMA.TABLES).

참고: INFORMATION_SCHEMA 뷰 이름은 대소문자를 구분합니다.

SELECT
  table_catalog, table_schema, table_name, table_type,
  is_insertable_into, creation_time, ddl
FROM
  mydataset.INFORMATION_SCHEMA.TABLES;

결과는 다음과 비슷합니다. 가독성을 위해 일부 열은 결과에서 제외됩니다.

+----------------+---------------+----------------+------------+--------------------+---------------------+---------------------------------------------+
| table_catalog  | table_schema  |   table_name   | table_type | is_insertable_into |    creation_time    |                     ddl                     |
+----------------+---------------+----------------+------------+--------------------+---------------------+---------------------------------------------+
| myproject      | mydataset     | mytable1       | BASE TABLE | YES                | 2018-10-29 20:34:44 | CREATE TABLE `myproject.mydataset.mytable1` |
|                |               |                |            |                    |                     | (                                           |
|                |               |                |            |                    |                     |   id INT64                                  |
|                |               |                |            |                    |                     | );                                          |
| myproject      | mydataset     | myview1        | VIEW       | NO                 | 2018-12-29 00:19:20 | CREATE VIEW `myproject.mydataset.myview1`   |
|                |               |                |            |                    |                     | AS SELECT 100 as id;                        |
+----------------+---------------+----------------+------------+--------------------+---------------------+---------------------------------------------+

예시 2:

다음 예시에서는 INFORMATION_SCHEMA.TABLES 뷰에서 CLONE 또는 SNAPSHOT 유형의 모든 테이블에 대해 테이블 메타데이터를 검색합니다. 반환되는 메타데이터는 기본 프로젝트의 mydataset에 있는 테이블의 메타데이터입니다.

기본 프로젝트가 아닌 프로젝트에 쿼리를 실행하려면 프로젝트 ID를 `project_id`.dataset.INFORMATION_SCHEMA.view 형식으로 데이터세트에 추가합니다(예: `myproject`.mydataset.INFORMATION_SCHEMA.TABLES).

  SELECT
    table_name, table_type, base_table_catalog,
    base_table_schema, base_table_name, snapshot_time_ms
  FROM
    mydataset.INFORMATION_SCHEMA.TABLES
  WHERE
    table_type = 'CLONE'
  OR
    table_type = 'SNAPSHOT';

결과는 다음과 비슷합니다. 가독성을 위해 일부 열은 결과에서 제외됩니다.

  +--------------+------------+--------------------+-------------------+-----------------+---------------------+
  | table_name   | table_type | base_table_catalog | base_table_schema | base_table_name | snapshot_time_ms    |
  +--------------+------------+--------------------+-------------------+-----------------+---------------------+
  | items_clone  | CLONE      | myproject          | mydataset         | items           | 2018-10-31 22:40:05 |
  | orders_bk    | SNAPSHOT   | myproject          | mydataset         | orders          | 2018-11-01 08:22:39 |
  +--------------+------------+--------------------+-------------------+-----------------+---------------------+

예 3:

다음 예시는 census_bureau_usa 데이터 세트에 있는 population_by_zip_2010 테이블의 INFORMATION_SCHEMA.TABLES 뷰에서 table_name 및 ddl 열을 검색합니다. 이 데이터 세트는 BigQuery 공개 데이터 세트 프로그램의 일부입니다.

쿼리하려는 테이블이 다른 프로젝트에 있으므로 프로젝트 ID를 다음 형식으로 데이터 세트에 추가합니다. `project_id`.dataset.INFORMATION_SCHEMA.view 이 예시에서 값은 `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.TABLES입니다.

SELECT
  table_name, ddl
FROM
  `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.TABLES
WHERE
  table_name = 'population_by_zip_2010';

결과는 다음과 비슷합니다.

+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|       table_name       |                                                                                                            ddl                                                                                                             |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| population_by_zip_2010 | CREATE TABLE `bigquery-public-data.census_bureau_usa.population_by_zip_2010`                                                                                                                                               |
|                        | (                                                                                                                                                                                                                          |
|                        |   geo_id STRING OPTIONS(description="Geo code"),                                                                                                                                                                           |
|                        |   zipcode STRING NOT NULL OPTIONS(description="Five digit ZIP Code Tabulation Area Census Code"),                                                                                                                          |
|                        |   population INT64 OPTIONS(description="The total count of the population for this segment."),                                                                                                                             |
|                        |   minimum_age INT64 OPTIONS(description="The minimum age in the age range. If null, this indicates the row as a total for male, female, or overall population."),                                                          |
|                        |   maximum_age INT64 OPTIONS(description="The maximum age in the age range. If null, this indicates the row as having no maximum (such as 85 and over) or the row is a total of the male, female, or overall population."), |
|                        |   gender STRING OPTIONS(description="male or female. If empty, the row is a total population summary.")                                                                                                                    |
|                        | )                                                                                                                                                                                                                          |
|                        | OPTIONS(                                                                                                                                                                                                                   |
|                        |   labels=[("freebqcovid", "")]                                                                                                                                                                                             |
|                        | );                                                                                                                                                                                                                         |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  

TABLE_OPTIONS 뷰

INFORMATION_SCHEMA.TABLE_OPTIONS 뷰를 쿼리하면 쿼리 결과에 데이터 세트의 각 테이블이나 뷰의 옵션마다 행 하나가 포함됩니다. 뷰에 대한 자세한 내용을 확인하려면 대신 INFORMATION_SCHEMA.VIEWS 뷰를 쿼리하세요.

INFORMATION_SCHEMA.TABLE_OPTIONS 뷰에는 다음과 같은 스키마가 있습니다.

열 이름	데이터 유형	값
TABLE_CATALOG	STRING	데이터 세트가 포함된 프로젝트의 프로젝트 ID
TABLE_SCHEMA	STRING	테이블이나 뷰가 포함된 데이터 세트 이름(또는 datasetId라고 함)
TABLE_NAME	STRING	테이블 또는 뷰의 이름(또는 tableId라고 함)
OPTION_NAME	STRING	옵션 표의 이름 값 중 하나
OPTION_TYPE	STRING	옵션 표의 데이터 유형 값 중 하나
OPTION_VALUE	STRING	옵션 표의 값 옵션 중 하나

옵션 표

OPTION_NAME	OPTION_TYPE	OPTION_VALUE
description	STRING	테이블 설명
enable_refresh	BOOL	구체화된 뷰에 자동 새로고침이 사용 설정되었는지 여부
expiration_timestamp	TIMESTAMP	이 테이블이 만료되는 시간
friendly_name	STRING	테이블을 설명하는 이름
kms_key_name	STRING	테이블을 암호화하는 데 사용된 Cloud KMS 키의 이름
labels	ARRAY<STRUCT<STRING, STRING>>	테이블의 라벨을 나타내는 STRUCT 배열
partition_expiration_days	FLOAT64	파티션을 나눈 테이블의 모든 파티션 기본 수명(일)
refresh_interval_minutes	FLOAT64	구체화된 뷰가 새로고침되는 빈도
require_partition_filter	BOOL	테이블에 대한 쿼리에 파티션 필터가 필요한지 여부
tags	ARRAY<STRUCT<STRING, STRING>>	네임스페이스화된 <키, 값> 구문의 테이블에 연결된 태그. 자세한 내용은 태그 및 조건부 액세스를 참조하세요.

외부 테이블에 다음 옵션을 사용할 수 있습니다.

옵션
allow_jagged_rows	BOOL true이면 뒤에 오는 선택적인 열이 누락된 행을 허용합니다. CSV 데이터에 적용됩니다.
allow_quoted_newlines	BOOL true이면 파일에서 따옴표 안에 줄바꿈 문자가 포함된 데이터 섹션을 허용합니다. CSV 데이터에 적용됩니다.
bigtable_options	STRING Bigtable 외부 테이블을 만들 때만 필요합니다. Bigtable 외부 테이블의 스키마를 JSON 형식으로 지정합니다. Bigtable 테이블 정의 옵션의 목록은 REST API 참조에서 BigtableOptions를 참조하세요.
column_name_character_map	STRING 지원되는 열 이름 문자의 범위와 지원되지 않는 문자의 처리 동작을 정의합니다. 지원되는 값은 다음과 같습니다. STRICT. 유연한 열 이름을 사용 설정합니다. 열 이름에 지원되지 않는 문자가 포함된 작업을 로드하면 오류 메시지와 함께 실패합니다. 이 설정이 기본 설정입니다. V1. 열 이름에는 표준 열 이름 문자만 포함할 수 있습니다. 지원되지 않는 문자는 밑줄로 대체됩니다. V2. 유연한 열 이름을 사용 설정합니다. 지원되지 않는 문자는 밑줄로 대체됩니다. 외부 테이블이 있는 사용 사례를 제외하고 이 설정이 권장됩니다. CSV 및 Parquet 데이터에 적용됩니다.
compression	STRING 데이터 소스의 압축 유형입니다. 지원되는 값은 GZIP입니다. 지정하지 않으면 데이터 소스는 압축되지 않습니다. CSV 및 JSON 데이터에 적용됩니다.
decimal_target_types	ARRAY<STRING> Decimal 유형을 변환하는 방법을 결정합니다. ExternalDataConfiguration.decimal_target_types와 동일합니다. 예: ["NUMERIC", "BIGNUMERIC"]
description	STRING 이 테이블에 대한 설명입니다.
enable_list_inference	BOOL true이면 특히 Parquet LIST 논리 유형에 대해 스키마 추론을 사용합니다. Parquet 데이터에 적용됩니다.
enable_logical_types	BOOL true이면 Avro 논리 유형을 해당 SQL 유형으로 변환합니다. 자세한 내용은 논리 유형을 참조하세요. Avro 데이터에 적용됩니다.
encoding	STRING 데이터의 문자 인코딩입니다. 지원되는 값은 UTF8(또는 UTF-8), ISO_8859_1(또는 ISO-8859-1)입니다. CSV 데이터에 적용됩니다.
enum_as_string	BOOL true이면 기본적으로 BYTES 대신 Parquet ENUM 논리 유형을 STRING으로 추론합니다. Parquet 데이터에 적용됩니다.
expiration_timestamp	TIMESTAMP 이 테이블이 만료되는 시간입니다. 지정하지 않으면 테이블이 만료되지 않습니다. 예시: "2025-01-01 00:00:00 UTC"
field_delimiter	STRING CSV 파일의 필드 구분 기호입니다. CSV 데이터에 적용됩니다.
format	STRING 외부 데이터의 형식입니다. CREATE EXTERNAL TABLE의 지원 값으로는 AVRO, CLOUD_BIGTABLE, CSV, DATASTORE_BACKUP, DELTA_LAKE(미리보기), GOOGLE_SHEETS, NEWLINE_DELIMITED_JSON(또는 JSON), ORC, PARQUET 등이 있습니다. LOAD DATA의 지원 값으로는 AVRO, CSV, DELTA_LAKE(미리보기), NEWLINE_DELIMITED_JSON(또는 JSON), ORC, PARQUET 등이 있습니다. 값 JSON은 NEWLINE_DELIMITED_JSON과 동일합니다.
hive_partition_uri_prefix	STRING 파티션 키 인코딩이 시작되기 전에 모든 소스 URI의 공통 프리픽스입니다. 파티션을 나눈 하이브 외부 테이블에만 적용됩니다. Avro, CSV, JSON, Parquet, ORC 데이터에 적용됩니다. 예: "gs://bucket/path"
file_set_spec_type	STRING 로드 작업 및 외부 테이블의 소스 URI를 해석하는 방법을 지정합니다. 미리보기에서: 지원되는 값은 다음과 같습니다. FILE_SYSTEM_MATCH. 객체 저장소의 파일을 나열하여 소스 URI를 확장합니다. FileSetSpecType이 설정되지 않은 경우의 기본 동작입니다. NEW_LINE_DELIMITED_MANIFEST. 제공된 URI가 줄바꿈으로 구분된 매니페스트 파일이며 한 줄에 URI가 하나씩 있음을 나타냅니다. 매니페스트 파일에서 와일드 카드 URI가 지원되지 않으며 모든 참조된 데이터 파일은 매니페스트 파일과 동일한 버킷에 있어야 합니다. 예를 들어 소스 URI가 "gs://bucket/path/file"이고 file_set_spec_type이 FILE_SYSTEM_MATCH인 경우 파일은 데이터 파일로 직접 사용됩니다. file_set_spec_type이 NEW_LINE_DELIMITED_MANIFEST면 파일의 각 줄이 데이터 파일을 가리키는 URI로 해석됩니다.
ignore_unknown_values	BOOL true인 경우 오류를 반환하지 않고 테이블 스키마에 표시되지 않는 추가 값을 무시합니다. CSV 및 JSON 데이터에 적용됩니다.
json_extension	STRING JSON 데이터의 경우 특정 JSON 교환 형식을 나타냅니다. 지정되지 않은 경우 BigQuery는 데이터를 일반 JSON 레코드로 읽습니다. 지원되는 값은 다음과 같습니다. GEOJSON. 줄바꿈으로 구분된 GeoJSON 데이터 자세한 내용은 줄바꿈으로 구분된 GeoJSON 파일에서 외부 테이블 만들기를 참조하세요.
max_bad_records	INT64 데이터를 읽을 때 무시할 불량 레코드의 최대 개수입니다. CSV, JSON, Google Sheets 데이터에 적용됩니다.
max_staleness	INTERVAL BigLake 테이블 및 객체 테이블에 적용할 수 있습니다. 테이블에 대한 작업에서 캐시된 메타데이터를 사용할지 여부와 작업이 사용하기 위해 캐시된 메타데이터가 얼마나 최신이어야 하는지를 지정합니다. 메타데이터 캐싱을 사용 중지하려면 0을 지정합니다. 이 값이 기본값입니다. 메타데이터 캐싱을 사용 설정하려면 30분에서 7일 사이의 간격 리터럴 값을 지정합니다. 예를 들어 4시간 비활성 간격에는 INTERVAL 4 HOUR를 지정합니다. 이 값을 사용하면 지난 4시간 이내에 새로고침된 경우 테이블에 대한 작업이 캐시된 메타데이터를 사용합니다. 캐시된 메타데이터가 이보다 오래된 경우 작업이 Cloud Storage에서 메타데이터를 대신 검색하도록 되돌아갑니다.
null_marker	STRING CSV 파일의 NULL 값을 나타내는 문자열입니다. CSV 데이터에 적용됩니다.
object_metadata	STRING 객체 테이블을 만들 때만 필요합니다. 객체 테이블을 만들 때 이 옵션의 값을 SIMPLE로 설정합니다.
preserve_ascii_control_characters	BOOL true이면 '\x00'부터 '\x1F'까지 ASCII 테이블의 처음 32자에 해당하는 삽입된 ASCII 제어 문자가 유지됩니다. CSV 데이터에 적용됩니다.
projection_fields	STRING 로드할 항목 속성의 목록입니다. Datastore 데이터에 적용됩니다.
quote	STRING CSV 파일에서 데이터 섹션을 인용하는 데 사용되는 문자열입니다. 데이터에 따옴표 붙은 줄바꿈 문자가 있다면 allow_quoted_newlines 속성을 true로 설정합니다. CSV 데이터에 적용됩니다.
reference_file_schema_uri	STRING 사용자가 테이블 스키마와 함께 참조 파일을 제공합니다. Parquet/ORC/AVRO 데이터에 적용됩니다. 예: "gs://bucket/path/reference_schema_file.parquet"
require_hive_partition_filter	BOOL true인 경우 이 테이블에 대한 모든 쿼리에는 데이터를 읽을 때 파티션을 제거하는 데 사용할 수 있는 파티션 필터가 필요합니다. 파티션을 나눈 하이브 외부 테이블에만 적용됩니다. Avro, CSV, JSON, Parquet, ORC 데이터에 적용됩니다.
sheet_range	STRING 쿼리할 Google Sheets 스프레드시트의 범위입니다. Google Sheets 데이터에 적용됩니다. 예시: "sheet1!A1:B20"
skip_leading_rows	INT64 데이터를 읽을 때 건너뛸 파일 상단의 행 수입니다. CSV 및 Google Sheets 데이터에 적용됩니다.
uris	Bigtable 테이블이 아닌 객체 테이블을 포함한 외부 테이블의 경우: ARRAY<STRING> 외부 데이터 위치의 정규화된 URI 배열입니다. 각 URI에는 버킷 이름 뒤에 와야 하는 별표(*) 와일드 카드 문자가 하나 포함될 수 있습니다. 여러 파일을 대상으로 하는 uris 값을 지정하는 경우 해당하는 모든 파일은 호환되는 스키마를 공유해야 합니다. 다음 예시에서는 유효한 uris 값을 보여줍니다. ['gs://bucket/path1/myfile.csv'] ['gs://bucket/path1/*.csv'] ['gs://bucket/path1/*', 'gs://bucket/path2/file00*'] Bigtable 테이블의 경우: STRING 데이터 소스로 사용할 Bigtable 테이블을 식별하는 URI입니다. Bigtable URI는 하나만 지정할 수 있습니다. 예를 들면 https://googleapis.com/bigtable/projects/project_id/instances/instance_id[/appProfiles/app_profile]/tables/table_name입니다. Bigtable URI를 생성하는 방법에 대한 자세한 내용은 Bigtable URI 검색을 참조하세요.

예시

예시 1:

다음 예시에서는 INFORMATION_SCHEMA.TABLE_OPTIONS 뷰를 쿼리하여 기본 프로젝트(myproject)의 mydataset에 있는 모든 테이블의 기본 테이블 만료 시간을 검색합니다.

기본 프로젝트가 아닌 프로젝트에 쿼리를 실행하려면 프로젝트 ID를 `project_id`.dataset.INFORMATION_SCHEMA.view 형식으로 데이터세트에 추가합니다(예: `myproject`.mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS).

참고: INFORMATION_SCHEMA 뷰 이름은 대소문자를 구분합니다.

  SELECT
    *
  FROM
    mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
  WHERE
    option_name = 'expiration_timestamp';

결과는 다음과 비슷합니다.

  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  | table_catalog  | table_schema  | table_name |     option_name      | option_type |             option_value             |
  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  | myproject      | mydataset     | mytable1   | expiration_timestamp | TIMESTAMP   | TIMESTAMP "2020-01-16T21:12:28.000Z" |
  | myproject      | mydataset     | mytable2   | expiration_timestamp | TIMESTAMP   | TIMESTAMP "2021-01-01T21:12:28.000Z" |
  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  

참고: 만료 시간이 지정되지 않은 테이블은 쿼리 결과에서 제외됩니다.

예시 2:

다음 예시는 테스트 데이터가 포함된 mydataset의 모든 테이블에 대한 메타데이터를 검색합니다. 이 쿼리는 description 옵션의 값을 사용하여 설명의 아무 곳에서나 'test'가 포함된 테이블을 찾습니다. mydataset는 기본 프로젝트 myproject에 있습니다.

기본 프로젝트가 아닌 프로젝트에 쿼리를 실행하려면 프로젝트 ID를 `project_id`.dataset.INFORMATION_SCHEMA.view 형식으로 데이터세트에 추가합니다(예: `myproject`.mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS).

  SELECT
    *
  FROM
    mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
  WHERE
    option_name = 'description'
    AND option_value LIKE '%test%';

결과는 다음과 비슷합니다.

  +----------------+---------------+------------+-------------+-------------+--------------+
  | table_catalog  | table_schema  | table_name | option_name | option_type | option_value |
  +----------------+---------------+------------+-------------+-------------+--------------+
  | myproject      | mydataset     | mytable1   | description | STRING      | "test data"  |
  | myproject      | mydataset     | mytable2   | description | STRING      | "test data"  |
  +----------------+---------------+------------+-------------+-------------+--------------+
  

COLUMNS 뷰

INFORMATION_SCHEMA.COLUMNS 뷰를 쿼리하면 테이블의 각 열(필드)당 하나의 행이 쿼리 결과에 포함됩니다.

INFORMATION_SCHEMA.COLUMNS 뷰에는 다음과 같은 스키마가 있습니다.

열 이름	데이터 유형	값
TABLE_CATALOG	STRING	데이터 세트가 포함된 프로젝트의 프로젝트 ID
TABLE_SCHEMA	STRING	테이블이 포함된 데이터 세트 이름(또는 datasetId라고 함)
TABLE_NAME	STRING	테이블 또는 뷰의 이름(또는 tableId라고 함)
COLUMN_NAME	STRING	열 이름
ORDINAL_POSITION	INT64	테이블에 있는 열의 1부터 시작하는 오프셋. _PARTITIONTIME 또는 _PARTITIONDATE와 같은 의사 열이면 값은 NULL입니다.
IS_NULLABLE	STRING	열의 모드가 NULL 값을 허용하는지 여부에 따라 YES 또는 NO
DATA_TYPE	STRING	열의 GoogleSQL 데이터 유형
IS_GENERATED	STRING	값이 항상 NEVER임
GENERATION_EXPRESSION	STRING	값이 항상 NULL임
IS_STORED	STRING	값이 항상 NULL임
IS_HIDDEN	STRING	열이 _PARTITIONTIME 또는 _PARTITIONDATE와 같은 의사 열인지 여부에 따라 YES 또는 NO
IS_UPDATABLE	STRING	값이 항상 NULL임
IS_SYSTEM_DEFINED	STRING	열이 _PARTITIONTIME 또는 _PARTITIONDATE와 같은 의사 열인지 여부에 따라 YES 또는 NO
IS_PARTITIONING_COLUMN	STRING	열이 파티션 나누기 열인지 여부에 따라 YES 또는 NO
CLUSTERING_ORDINAL_POSITION	INT64	테이블 클러스터링 열에 있는 해당 열의 1부터 시작하는 오프셋. 테이블이 클러스터링된 테이블이 아니면 값은 NULL입니다.
COLLATION_NAME	STRING	콜레이션 사양 이름(있는 경우)입니다. 그 외의 경우는 NULL입니다. STRING 또는 ARRAY<STRING>이 전달된 경우 콜레이션 사양(있는 경우)이 반환됩니다. 그 외의 경우는 NULL이 반환됩니다.
COLUMN_DEFAULT	STRING	존재하는 경우 열의 기본값이고 그렇지 않은 경우 값은 NULL입니다.
ROUNDING_MODE	STRING	유형이 매개변수화된 NUMERIC 또는 BIGNUMERIC인 경우 필드에 기록되는 값에 사용되는 반올림 모드입니다. 그렇지 않으면 값은 NULL입니다.

예시

다음 예시는 census_bureau_usa 데이터 세트에 있는 population_by_zip_2010 테이블의 INFORMATION_SCHEMA.COLUMNS 뷰에서 메타데이터를 검색합니다. 이 데이터 세트는 BigQuery 공개 데이터 세트 프로그램의 일부입니다.

쿼리하려는 테이블이 bigquery-public-data 프로젝트라는 다른 프로젝트에 있으므로 프로젝트 ID를 `project_id`.dataset.INFORMATION_SCHEMA.view 형식으로 데이터 세트에 추가합니다(예: `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.TABLES).

다음 열은 현재 나중에 사용하도록 예약되어 있으므로 쿼리 결과에서 제외됩니다.

• IS_GENERATED
• GENERATION_EXPRESSION
• IS_STORED
• IS_UPDATABLE

참고: INFORMATION_SCHEMA 뷰 이름은 대소문자를 구분합니다.

  SELECT
    * EXCEPT(is_generated, generation_expression, is_stored, is_updatable)
  FROM
    `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.COLUMNS
  WHERE
    table_name = 'population_by_zip_2010';

결과는 다음과 비슷합니다. 가독성을 위해 일부 열은 결과에서 제외됩니다.

+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+
|       table_name       | column_name | ordinal_position | is_nullable | data_type | is_hidden | is_system_defined | is_partitioning_column | clustering_ordinal_position |
+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+
| population_by_zip_2010 | zipcode     |                1 | NO          | STRING    | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | geo_id      |                2 | YES         | STRING    | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | minimum_age |                3 | YES         | INT64     | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | maximum_age |                4 | YES         | INT64     | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | gender      |                5 | YES         | STRING    | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | population  |                6 | YES         | INT64     | NO        | NO                | NO                     |                        NULL |
+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+
  

COLUMN_FIELD_PATHS 뷰

INFORMATION_SCHEMA.COLUMN_FIELD_PATHS 뷰를 쿼리하면 RECORD(또는 STRUCT) 열 내에 중첩된 각 열당 하나의 행이 쿼리 결과에 포함됩니다.

INFORMATION_SCHEMA.COLUMN_FIELD_PATHS 뷰에는 다음과 같은 스키마가 있습니다.

열 이름	데이터 유형	값
TABLE_CATALOG	STRING	데이터 세트가 포함된 프로젝트의 프로젝트 ID
TABLE_SCHEMA	STRING	테이블이 포함된 데이터 세트 이름(또는 datasetId라고 함)
TABLE_NAME	STRING	테이블 또는 뷰의 이름(또는 tableId라고 함)
COLUMN_NAME	STRING	열 이름
FIELD_PATH	STRING	`RECORD` 또는 `STRUCT` 열에 있는 중첩된 열의 경로
DATA_TYPE	STRING	열의 GoogleSQL 데이터 유형
DESCRIPTION	STRING	열 설명
COLLATION_NAME	STRING	콜레이션 사양 이름(있는 경우)입니다. 그 외의 경우는 NULL입니다. STRING, ARRAY<STRING> 또는 STRUCT의 STRING 필드가 전달된 경우 콜레이션 사양(있는 경우)이 반환됩니다. 그 외의 경우는 NULL이 반환됩니다.
ROUNDING_MODE	STRING	매개변수화된 NUMERIC 또는 BIGNUMERIC 값에 정밀도 및 확장을 적용할 때 사용되는 반올림 모드입니다. 그렇지 않으면 값은 NULL입니다.

예시

다음 예시는 github_repos 데이터 세트에 있는 commits 테이블의 INFORMATION_SCHEMA.COLUMN_FIELD_PATHS 뷰에서 메타데이터를 검색합니다. 이 데이터 세트는 BigQuery 공개 데이터 세트 프로그램의 일부입니다.

쿼리하려는 테이블이 bigquery-public-data 프로젝트라는 다른 프로젝트에 있으므로 프로젝트 ID를 `project_id`.dataset.INFORMATION_SCHEMA.view 형식으로 데이터 세트에 추가합니다(예: `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS).

commits 테이블에는 다음과 같은 중첩 열과 중첩 및 반복 열이 포함됩니다.

• author: 중첩 RECORD 열
• committer: 중첩 RECORD 열
• trailer: 중첩 및 반복 RECORD 열
• difference: 중첩 및 반복 RECORD 열

author 및 difference 열의 메타데이터를 보려면 다음 쿼리를 실행합니다.

참고: INFORMATION_SCHEMA 뷰 이름은 대소문자를 구분합니다.

SELECT
  *
FROM
  `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS
WHERE
  table_name = 'commits'
  AND (column_name = 'author' OR column_name = 'difference');

결과는 다음과 비슷합니다. 가독성을 위해 일부 열은 결과에서 제외됩니다.

  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+
  | table_name | column_name |     field_path      |                                                                      data_type                                                                      | description |
  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+
  | commits    | author      | author              | STRUCT<name STRING, email STRING, time_sec INT64, tz_offset INT64, date TIMESTAMP>                                                                  | NULL        |
  | commits    | author      | author.name         | STRING                                                                                                                                              | NULL        |
  | commits    | author      | author.email        | STRING                                                                                                                                              | NULL        |
  | commits    | author      | author.time_sec     | INT64                                                                                                                                               | NULL        |
  | commits    | author      | author.tz_offset    | INT64                                                                                                                                               | NULL        |
  | commits    | author      | author.date         | TIMESTAMP                                                                                                                                           | NULL        |
  | commits    | difference  | difference          | ARRAY<STRUCT<old_mode INT64, new_mode INT64, old_path STRING, new_path STRING, old_sha1 STRING, new_sha1 STRING, old_repo STRING, new_repo STRING>> | NULL        |
  | commits    | difference  | difference.old_mode | INT64                                                                                                                                               | NULL        |
  | commits    | difference  | difference.new_mode | INT64                                                                                                                                               | NULL        |
  | commits    | difference  | difference.old_path | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.new_path | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.old_sha1 | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.new_sha1 | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.old_repo | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.new_repo | STRING                                                                                                                                              | NULL        |
  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+
  

뷰 TABLE_STORAGE개

미리보기

이 제품 또는 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 제품 및 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

TABLE_STORAGE 및 TABLE_STORAGE_BY_ORGANIZATION 뷰에는 다음과 같은 스키마가 있습니다.

열 이름	데이터 유형	값
PROJECT_ID	STRING	데이터 세트가 포함된 프로젝트의 프로젝트 ID
PROJECT_NUMBER	INT64	데이터 세트가 포함된 프로젝트의 프로젝트 번호
TABLE_CATALOG	STRING	데이터 세트가 포함된 프로젝트의 프로젝트 ID
TABLE_SCHEMA	STRING	테이블이나 구체화된 뷰가 포함된 데이터 세트 이름(또는 datasetId라고 함)
TABLE_NAME	STRING	테이블 또는 구체화된 뷰의 이름(또는 tableId라고 함)
CREATION_TIME	TIMESTAMP	테이블 생성 시간
TOTAL_ROWS	INT64	테이블 또는 구체화된 뷰의 총 행 수
TOTAL_PARTITIONS	INT64	테이블 또는 구체화된 뷰에 있는 파티션 수. 파티션을 나누지 않은 테이블은 0을 반환합니다.
TOTAL_LOGICAL_BYTES	INT64	테이블 또는 구체화된 뷰에 있는 논리적(비압축) 총 바이트 수
ACTIVE_LOGICAL_BYTES	INT64	90일을 경과하지 않은 논리적(비압축) 바이트 수
LONG_TERM_LOGICAL_BYTES	INT64	90일을 경과한 논리적(비압축) 바이트 수
CURRENT_PHYSICAL_BYTES	INT64	모든 파티션에서 현재 테이블 스토리지의 총 물리적 바이트 수
TOTAL_PHYSICAL_BYTES	INT64	활성, 장기, 시간 이동(데이터 삭제 또는 변경) 바이트를 포함하여 스토리지에 사용된 총 물리적(압축) 바이트 수 장애 안전(시간 이동 기간 후 보관된 데이터 삭제 또는 변경) 바이트는 포함되지 않습니다.
ACTIVE_PHYSICAL_BYTES	INT64	시간 이동(데이터 삭제 또는 변경) 바이트를 포함하여 90일을 경과하지 않은 물리적(압축) 바이트 수
LONG_TERM_PHYSICAL_BYTES	INT64	90일을 경과한 물리적(압축) 바이트 수
TIME_TRAVEL_PHYSICAL_BYTES	INT64	시간 이동 스토리지(데이터 삭제 또는 변경)에 사용된 물리적(압축) 바이트 수
STORAGE_LAST_MODIFIED_TIME	TIMESTAMP	데이터가 테이블에 작성된 가장 최근 시간입니다.
DELETED	BOOLEAN	테이블 삭제 여부
TABLE_TYPE	STRING	테이블 유형입니다. 예를 들면 EXTERNAL 또는 BASE TABLE입니다.
FAIL_SAFE_PHYSICAL_BYTES	INT64	장애 안전 스토리지(데이터 삭제 또는 변경)에 사용된 물리적(압축) 바이트 수

예시

예시 1:

다음 예시에서는 현재 프로젝트에 대해 청구되는 총 논리 바이트를 보여줍니다.

SELECT
  SUM(total_logical_bytes) AS total_logical_bytes
FROM
  `region-REGION`.INFORMATION_SCHEMA.TABLE_STORAGE;

결과는 다음과 비슷합니다.

+---------------------+
| total_logical_bytes |
+---------------------+
| 971329178274633     |
+---------------------+

예시 2:

다음 예시는 향후 30일 동안 논리적 및 물리적 청구 모델 간의 데이터 세트당 가격 차이를 예측하는 방법을 보여줍니다. 이 예시에서는 이후의 스토리지 사용량이 쿼리 실행 시점부터 30일동안 일정하다고 가정합니다. 이 예측은 기본 테이블로 제한되며 데이터 세트 안의 다른 모든 테이블 유형을 제외합니다.

이 쿼리의 가격 책정 변수에 사용된 가격은 us-central1 리전의 가격입니다. 다른 리전에 대해 이 쿼리를 실행하려면 가격 책정 변수를 적절하게 업데이트합니다. 가격 책정 정보는 스토리지 가격 책정을 참조하세요.

1. Google Cloud 콘솔에서 BigQuery 페이지를 엽니다.

   BigQuery 페이지로 이동

2. 쿼리 편집기 상자에 다음과 같은 GoogleSQL 쿼리를 입력합니다. INFORMATION_SCHEMA에는 GoogleSQL 구문이 필요합니다. GoogleSQL은 Google Cloud 콘솔의 기본 구문입니다.

   DECLARE active_logical_gib_price FLOAT64 DEFAULT 0.02;
   DECLARE long_term_logical_gib_price FLOAT64 DEFAULT 0.01;
   DECLARE active_physical_gib_price FLOAT64 DEFAULT 0.04;
   DECLARE long_term_physical_gib_price FLOAT64 DEFAULT 0.02;
   
   WITH
    storage_sizes AS (
      SELECT
        table_schema AS dataset_name,
        -- Logical
        SUM(IF(deleted=false, active_logical_bytes, 0)) / power(1024, 3) AS active_logical_gib,
        SUM(IF(deleted=false, long_term_logical_bytes, 0)) / power(1024, 3) AS long_term_logical_gib,
        -- Physical
        SUM(active_physical_bytes) / power(1024, 3) AS active_physical_gib,
        SUM(active_physical_bytes - time_travel_physical_bytes) / power(1024, 3) AS active_no_tt_physical_gib,
        SUM(long_term_physical_bytes) / power(1024, 3) AS long_term_physical_gib,
        -- Restorable previously deleted physical
        SUM(time_travel_physical_bytes) / power(1024, 3) AS time_travel_physical_gib,
        SUM(fail_safe_physical_bytes) / power(1024, 3) AS fail_safe_physical_gib,
      FROM
        `region-REGION`.INFORMATION_SCHEMA.TABLE_STORAGE_BY_PROJECT
      WHERE total_physical_bytes + fail_safe_physical_bytes > 0
        -- Base the forecast on base tables only for highest precision results
        AND table_type  = 'BASE TABLE'
        GROUP BY 1
    )
   SELECT
     dataset_name,
     -- Logical
     ROUND(active_logical_gib, 2) AS active_logical_gib,
     ROUND(long_term_logical_gib, 2) AS long_term_logical_gib,
     -- Physical
     ROUND(active_physical_gib, 2) AS active_physical_gib,
     ROUND(long_term_physical_gib, 2) AS long_term_physical_gib,
     ROUND(time_travel_physical_gib, 2) AS time_travel_physical_gib,
     ROUND(fail_safe_physical_gib, 2) AS fail_safe_physical_gib,
     -- Compression ratio
     ROUND(SAFE_DIVIDE(active_logical_gib, active_no_tt_physical_gib), 2) AS active_compression_ratio,
     ROUND(SAFE_DIVIDE(long_term_logical_gib, long_term_physical_gib), 2) AS long_term_compression_ratio,
     -- Forecast costs logical
     ROUND(active_logical_gib * active_logical_gib_price, 2) AS forecast_active_logical_cost,
     ROUND(long_term_logical_gib * long_term_logical_gib_price, 2) AS forecast_long_term_logical_cost,
     -- Forecast costs physical
     ROUND((active_no_tt_physical_gib + time_travel_physical_gib + fail_safe_physical_gib) * active_physical_gib_price, 2) AS forecast_active_physical_cost,
     ROUND(long_term_physical_gib * long_term_physical_gib_price, 2) AS forecast_long_term_physical_cost,
     -- Forecast costs total
     ROUND(((active_logical_gib * active_logical_gib_price) + (long_term_logical_gib * long_term_logical_gib_price)) -
        (((active_no_tt_physical_gib + time_travel_physical_gib + fail_safe_physical_gib) * active_physical_gib_price) + (long_term_physical_gib * long_term_physical_gib_price)), 2) AS forecast_total_cost_difference
   FROM
     storage_sizes
   ORDER BY
     (forecast_active_logical_cost + forecast_active_physical_cost) DESC;
   

   참고: INFORMATION_SCHEMA 뷰 이름은 대소문자를 구분합니다.

3. 실행을 클릭합니다.

결과는 다음과 비슷합니다.

+--------------+--------------------+-----------------------+---------------------+------------------------+--------------------------+-----------------------------+------------------------------+----------------------------------+-------------------------------+----------------------------------+--------------------------------+
| dataset_name | active_logical_gib | long_term_logical_gib | active_physical_gib | long_term_physical_gib | active_compression_ratio | long_term_compression_ratio | forecast_active_logical_cost | forecaset_long_term_logical_cost | forecast_active_physical_cost | forecast_long_term_physical_cost | forecast_total_cost_difference |
+--------------+--------------------+-----------------------+---------------------+------------------------+--------------------------+-----------------------------+------------------------------+----------------------------------+-------------------------------+----------------------------------+--------------------------------+
| dataset1     |               10.0 |                  10.0 |                 1.0 |                    1.0 |                     10.0 |                        10.0 |                          0.2 |                              0.1 |                          0.04 |                             0.02 |                           0.24 |

데이터 세트의 테이블 나열

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

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

필수 권한

데이터 세트의 테이블을 나열하려면 최소한 bigquery.tables.list 권한이 부여되어 있어야 합니다. 다음과 같은 사전 정의된 IAM 역할에는 bigquery.tables.list 권한이 포함되어 있습니다.

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

BigQuery의 IAM 역할과 권한에 대한 자세한 내용은 액세스 제어를 참조하세요.

표 나열

데이터세트의 테이블을 나열하려면 다음과 같이 하세요.

콘솔

1. Google Cloud 콘솔의 탐색창에서 데이터 세트를 클릭하여 확장합니다. 그러면 데이터세트에 있는 테이블과 뷰가 표시됩니다.

2. 목록을 스크롤하여 데이터 세트의 테이블을 확인합니다. 테이블과 뷰는 서로 다른 아이콘으로 구분됩니다.

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. bq ls 명령어를 실행합니다. --format 플래그를 사용하면 출력을 제어할 수 있습니다. 기본 프로젝트가 아닌 다른 프로젝트의 테이블을 나열하는 경우 프로젝트 ID를 project_id:dataset 형식으로 데이터 세트에 추가합니다.

   추가 플래그에는 다음이 포함됩니다.

   • --max_results 또는 -n: 결과의 최대 수를 나타내는 정수입니다. 기본값은 50입니다.

   bq ls \
   --format=pretty \
   --max_results integer \
   project_id:dataset
   

   각 항목의 의미는 다음과 같습니다.

   • integer는 나열할 테이블 수를 나타내는 정수입니다.
   • project_id는 프로젝트 ID입니다.
   • dataset는 데이터 세트 이름입니다.

   명령어를 실행하면 Type 필드에 TABLE 또는 VIEW가 표시됩니다. 예를 들면 다음과 같습니다.

   +-------------------------+-------+----------------------+-------------------+
   |         tableId         | Type  |        Labels        | Time Partitioning |
   +-------------------------+-------+----------------------+-------------------+
   | mytable                 | TABLE | department:shipping  |                   |
   | myview                  | VIEW  |                      |                   |
   +-------------------------+-------+----------------------+-------------------+
   

   예:

   다음 명령어를 입력하면 기본 프로젝트의 데이터 세트 mydataset에 있는 테이블이 나열됩니다.

      bq ls --format=pretty mydataset
   

   다음 명령어를 입력하여 mydataset에서 50개의 기본 테이블 출력을 반환합니다. mydataset는 기본 프로젝트에 있습니다.

      bq ls --format=pretty --max_results 60 mydataset
   

   myotherproject의 데이터 세트 mydataset에 있는 테이블을 나열하려면 다음 명령어를 입력합니다.

      bq ls --format=pretty myotherproject:mydataset
   

API

API를 사용하여 테이블을 나열하려면 tables.list 메서드를 호출합니다.

C#

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

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

using Google.Cloud.BigQuery.V2;
using System;
using System.Collections.Generic;
using System.Linq;

public class BigQueryListTables
{
    public void ListTables(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Retrieve list of tables in the dataset
        List<BigQueryTable> tables = client.ListTables(datasetId).ToList();
        // Display the results
        if (tables.Count > 0)
        {
            Console.WriteLine($"Tables in dataset {datasetId}:");
            foreach (var table in tables)
            {
                Console.WriteLine($"\t{table.Reference.TableId}");
            }
        }
        else
        {
            Console.WriteLine($"{datasetId} does not contain any tables.");
        }
    }
}

Go

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

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

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// listTables demonstrates iterating through the collection of tables in a given dataset.
func listTables(w io.Writer, projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	ts := client.Dataset(datasetID).Tables(ctx)
	for {
		t, err := ts.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Table: %q\n", t.TableID)
	}
	return nil
}

자바

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

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

import com.google.api.gax.paging.Page;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQuery.TableListOption;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.DatasetId;
import com.google.cloud.bigquery.Table;

public class ListTables {

  public static void runListTables() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "bigquery-public-data";
    String datasetName = "samples";
    listTables(projectId, datasetName);
  }

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

      DatasetId datasetId = DatasetId.of(projectId, datasetName);
      Page<Table> tables = bigquery.listTables(datasetId, TableListOption.pageSize(100));
      tables.iterateAll().forEach(table -> System.out.print(table.getTableId().getTable() + "\n"));

      System.out.println("Tables listed successfully.");
    } catch (BigQueryException e) {
      System.out.println("Tables were not listed. Error occurred: " + e.toString());
    }
  }
}

Node.js

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

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

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function listTables() {
  // Lists tables in 'my_dataset'.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';

  // List all tables in the dataset
  const [tables] = await bigquery.dataset(datasetId).getTables();

  console.log('Tables:');
  tables.forEach(table => console.log(table.id));
}

PHP

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

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

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$tables = $dataset->tables();
foreach ($tables as $table) {
    print($table->id() . PHP_EOL);
}

Python

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

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

from google.cloud import bigquery

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

# TODO(developer): Set dataset_id to the ID of the dataset that contains
#                  the tables you are listing.
# dataset_id = 'your-project.your_dataset'

tables = client.list_tables(dataset_id)  # Make an API request.

print("Tables contained in '{}':".format(dataset_id))
for table in tables:
    print("{}.{}.{}".format(table.project, table.dataset_id, table.table_id))

Ruby

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

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

require "google/cloud/bigquery"

def list_tables dataset_id = "your_dataset_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id

  puts "Tables in dataset #{dataset_id}:"
  dataset.tables.each do |table|
    puts "\t#{table.table_id}"
  end
end

테이블 보안

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

다음 단계

• 데이터 세트에 대한 자세한 내용은 데이터 세트 소개를 참조하세요.
• 테이블 데이터 처리에 대한 자세한 내용은 테이블 데이터 관리를 참조하세요.
• 테이블 스키마 지정에 대한 자세한 내용은 스키마 지정을 참조하세요.
• 테이블 스키마 수정에 대한 자세한 내용은 테이블 스키마 수정을 참조하세요.
• 테이블 관리에 대한 자세한 내용은 테이블 관리를 참조하세요.
• BigQuery INFORMATION_SCHEMA 소개에서 INFORMATION_SCHEMA의 개요 참조

직접 사용해 보기

Google Cloud를 처음 사용하는 경우 계정을 만들어 실제 시나리오에서 BigQuery의 성능을 평가할 수 있습니다. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

BigQuery 무료로 사용해 보기