테이블 만들기 및 사용

이 문서에서는 BigQuery에서 테이블을 만들고 사용하는 방법을 설명합니다. 테이블을 만든 후에는 다음과 같은 작업을 수행할 수 있습니다.

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

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

테이블 제한사항

BigQuery 테이블에는 다음 제한사항이 적용됩니다.

  • 데이터세트마다 테이블 이름이 고유해야 합니다.
  • BigQuery 웹 UI에서는 테이블을 한 번에 하나만 복사할 수 있습니다.
  • 테이블을 복사할 때는 대상 데이터세트가 복사 중인 테이블과 동일한 위치에 있어야 합니다. 예를 들어 EU 기반 데이터세트의 테이블을 US 기반 데이터세트에 복사할 수 없습니다.
  • CLI나 API를 이용해 여러 원본 테이블을 단일 대상 테이블로 복사할 때는 모든 원본 테이블의 스키마가 같아야 합니다.
  • BigQuery 웹 UI, 명령줄 도구, API를 사용하여 테이블을 한 번에 하나만 삭제할 수 있습니다.
  • 테이블 데이터를 내보낼 때는 Google Cloud Storage만 대상으로 지원됩니다.
  • 데이터세트의 테이블이 50,000개 이상이 되면 이를 열거하는 속도가 느려집니다. API 호출, BigQuery 웹 UI 또는 __TABLES_SUMMARY__ 메타 테이블을 사용하는지 여부에 관계없이 열거 성능이 저하됩니다. UI 성능을 향상시키기 위해서는 ?minimal 매개변수를 사용하여 로드 작업을 프로젝트당 30,000개 테이블로 제한할 수 있습니다. BigQuery 웹 UI URL에 매개변수를 https://bigquery.cloud.google.com/queries/[PROJECT_NAME]?minimal 형식으로 추가합니다.

테이블 만들기

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

  • BigQuery 웹 UI 또는 명령줄 도구의 bq mk 명령어를 사용하여 수동으로
  • tables.insert API 메소드를 호출하여 프로그래매틱 방식으로
  • 쿼리 결과에서
  • 외부 데이터 소스를 참조하는 테이블을 정의하여
  • 데이터를 로드할 때

BigQuery에서 테이블을 만들 때 테이블 이름은 데이터세트별로 고유해야 합니다. 다음과 같은 테이블 이름을 사용할 수 있습니다.

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

필수 권한

테이블을 만들려면 데이터세트 수준에서 WRITER 액세스 권한이 있거나 bigquery.tables.create 권한을 포함하는 프로젝트 수준의 IAM 역할을 할당받아야 합니다. 다음 사전 정의된 프로젝트 수준 IAM 역할에는 bigquery.tables.create 권한이 있습니다.

또한 bigquery.user 역할에는 bigquery.datasets.create 권한이 있기 때문에 bigquery.user 역할에 할당된 사용자는 자신이 만든 모든 데이터세트에서 테이블을 만들 수 있습니다. bigquery.user 역할이 할당된 사용자가 데이터세트를 만들면 해당 사용자에게 데이터세트에 대한 OWNER 액세스 권한이 부여됩니다. 데이터세트에 대한 OWNER 액세스 권한은 사용자에게 전체 제어 권한을 부여합니다.

BigQuery의 IAM 역할 및 권한에 대한 자세한 내용은 액세스 제어를 참조하세요. 데이터세트 수준 역할에 대한 자세한 내용은 데이터세트의 기본 역할을 참조하세요.

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

스키마 정의가 있는 빈 테이블을 만들 때는 다음과 같은 작업을 수행할 수 있습니다.

  • 웹 UI를 사용하여 스키마 입력
  • 명령줄 도구를 사용하여 스키마를 인라인으로 제공
  • 명령줄 도구를 사용하여 JSON 스키마 파일 제출
  • API의 tables.insert 메소드를 호출할 때 테이블 리소스에 스키마 제공

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

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

스키마 정의가 있는 빈 테이블을 만들려면 다음과 같이 하세요.

웹 UI

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

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

  3. Create Table 페이지의 Destination Table(대상 테이블) 섹션에서 다음 안내를 따릅니다.

    • Table name(테이블 이름)으로 적당한 데이터세트를 선택하고 테이블 이름 필드에 BigQuery에서 생성 중인 테이블의 이름을 입력합니다.
    • Table Type(테이블 유형)Native table(네이티브 테이블)로 설정되어 있는지 확인합니다.
  4. 스키마 섹션에서 수동으로 스키마 정의를 입력합니다.

    • 스키마 정보를 수동으로 입력하는 방법은 다음과 같습니다.

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

        스키마를 JSON 배열로 추가

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

        필드 추가를 사용하여 스키마 추가

  5. Options 섹션에서 기본값을 그대로 둡니다.

  6. Create Table을 클릭합니다.

명령줄

mk 명령어와 --table 또는 -t 플래그를 사용합니다. 테이블 스키마 정보는 인라인으로 제공하거나 JSON 스키마 파일로 제공할 수 있습니다. 선택적 매개변수로는 --expiration, --description, --time_partitioning_type, --destination_kms_key, --label이 있습니다. 기본 프로젝트가 아닌 다른 프로젝트에서 테이블을 생성하는 경우 프로젝트 ID를 [PROJECT_ID]:[DATASET] 형식으로 데이터세트에 추가합니다.

--time_partitioning_type--destination_kms_key는 여기서 설명하지 않습니다. --time_partitioning_type에 대한 자세한 내용은 내부 데이터화 시간별로 파티션을 나눈 테이블 또는 파티션을 나눈 테이블을 참조하세요. --destination_kms_key에 대한 자세한 내용은 고객 관리 암호화 키를 참조하세요.

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

bq mk --table --expiration [INTEGER] --description [DESCRIPTION] --label [KEY:VALUE, KEY:VALUE] [PROJECT_ID]:[DATASET].[TABLE] [SCHEMA]

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

  • [INTEGER]는 테이블의 기본 수명(단위: 초)입니다. 최소값은 3,600초(1시간)입니다. 만료 시간은 현재 시간과 정수 값을 더한 값으로 계산됩니다. 테이블을 만들 때 만료 시간을 설정하면 데이터세트의 기본 테이블 만료 시간 설정은 무시됩니다.
  • [DESCRIPTION]은 따옴표로 묶은 테이블 설명입니다.
  • [KEY:VALUE]라벨을 나타내는 키:값 쌍입니다. 쉼표로 구분된 목록을 사용하여 여러 라벨을 입력할 수도 있습니다.
  • [PROJECT_ID]는 프로젝트 ID입니다.
  • [DATASET]는 프로젝트의 데이터세트입니다.
  • [TABLE]은 만드는 테이블의 이름입니다.
  • [SCHEMA][FIELD]:[DATA_TYPE],[FIELD]:[DATA_TYPE] 형식의 인라인 스키마 정의이거나 로컬 머신에 있는 JSON 스키마 파일의 경로입니다.

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

예:

인라인 스키마 정의를 사용하여 테이블을 만들려면 다음 명령어를 입력합니다. 이 명령어는 기본 프로젝트의 mydatasetmytable이라는 테이블을 만듭니다. 여기에서 테이블 만료 시간은 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 스키마 파일을 사용하여 테이블을 만들려면 다음 명령어를 입력합니다. 이 명령어는 기본 프로젝트의 mydatasetmytable이라는 테이블을 만듭니다. 여기에서 테이블 만료 시간은 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 스키마 파일을 사용하여 테이블을 만들려면 다음 명령어를 입력합니다. 이 명령어는 myotherprojectmydatasetmytable이라는 테이블을 만듭니다. 여기에서 테이블 만료 시간은 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

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

API

정의된 테이블 리소스를 사용하여 tables.insert 메소드를 호출합니다.

C#

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

public void CreateTable(string datasetId, string tableId, BigQueryClient client)
{
    var dataset = client.GetDataset(datasetId);
    // Create schema for new table.
    var schema = new TableSchemaBuilder
    {
        { "title", BigQueryDbType.String },
        { "unique_words", BigQueryDbType.Int64 }
    }.Build();
    // Create the table if it doesn't exist.
    BigQueryTable table = dataset.GetOrCreateTable(tableId, schema);
}

Go

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

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
}

자바

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

TableId tableId = TableId.of(datasetName, tableName);
// Table field definition
Field field = Field.of(fieldName, LegacySQLTypeName.STRING);
// Table schema definition
Schema schema = Schema.of(field);
TableDefinition tableDefinition = StandardTableDefinition.of(schema);
TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();
Table table = bigquery.create(tableInfo);

Node.js

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

// Imports the Google Cloud client library
const BigQuery = require('@google-cloud/bigquery');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = "your-project-id";
// const datasetId = "my_new_dataset";
// const tableId = "my_new_table";
// const schema = "Name:string, Age:integer, Weight:float, IsMagic:boolean";

// Creates a client
const bigquery = new BigQuery({
  projectId: projectId,
});

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

// Create a new table in the dataset
bigquery
  .dataset(datasetId)
  .createTable(tableId, options)
  .then(results => {
    const table = results[0];
    console.log(`Table ${table.id} created.`);
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

PHP

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

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 참조 문서를 확인하세요.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')

schema = [
    bigquery.SchemaField('full_name', 'STRING', mode='REQUIRED'),
    bigquery.SchemaField('age', 'INTEGER', mode='REQUIRED'),
]
table_ref = dataset_ref.table('my_table')
table = bigquery.Table(table_ref, schema=schema)
table = client.create_table(table)  # API request

assert table.table_id == 'my_table'

Ruby

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

# project_id = "Your Google Cloud project ID"
# dataset_id = "ID of the dataset to create table in"
# table_id   = "ID of the table to create"

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new project: project_id
dataset  = bigquery.dataset dataset_id

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}"

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

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

웹 UI

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

  2. Compose query(쿼리 작성) 버튼을 클릭합니다.

  3. New Query(새 쿼리) 텍스트 영역에 유효한 BigQuery SQL 쿼리를 입력합니다.

  4. Show Options(옵션 표시)를 클릭합니다.

  5. 대상 테이블 섹션에서 테이블 선택을 클릭합니다.

  6. Select Destination Table(대상 테이블 선택) 대화상자에서 다음 안내를 따릅니다.

    1. Project에서 대상 테이블을 만들 프로젝트를 선택합니다.

    2. Dataset에서 테이블을 저장할 데이터세트를 선택합니다.

    3. Table ID(테이블 ID) 필드에 테이블 이름을 입력합니다. 이름은 대상 데이터세트에서 고유해야 합니다. 테이블 이름의 길이는 최대 1,024자이며, a-z, A-Z, 0-9 또는 _(밑줄 문자)만 포함할 수 있습니다.

    4. OK(확인)를 클릭합니다.

  7. Destination Table(대상 테이블) 섹션의 Write Preference(쓰기 환경설정)에서 다음 중 하나를 선택합니다.

    • Write if empty(비어 있으면 쓰기) — 테이블이 비어 있는 경우에만 쿼리 결과를 테이블에 씁니다.
    • Append to table(테이블에 추가) — 쿼리 결과를 기존 테이블에 추가합니다.
    • Overwrite table(테이블 덮어쓰기) — 쿼리 결과를 사용하여 기존 테이블을 같은 이름으로 덮어씁니다.
  8. 처리 위치에서 미지정을 클릭하고 데이터의 위치를 선택합니다. 데이터가 US 또는 EU 다중 지역 위치에 있는 경우 처리 위치를 지정하지 않은 상태로 두어도 됩니다. 데이터가 USEU에 있으면 처리 위치가 자동으로 감지됩니다.

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

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

CLI

bq query 명령어를 입력하고 --destination_table 플래그를 지정해 쿼리 결과에 기반한 영구 테이블을 만듭니다. 표준 SQL 구문을 사용하려면 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]은 쿼리 처리에 사용되는 위치의 이름입니다. 데이터가 US 또는 EU 다중 위치 지역에 있는 경우, --location 플래그는 선택사항입니다. 예를 들어 도쿄 지역에서 BigQuery를 사용한다면 플래그 값은 asia-northeast1으로 지정해야 합니다. .bigqueryrc file을 사용하여 위치의 기본값을 설정할 수 있습니다.
  • [PROJECT_ID]는 프로젝트 ID입니다.
  • [DATASET]는 쿼리 결과를 쓰는 테이블이 포함된 데이터세트의 이름입니다.
  • [TABLE]은 쿼리 결과를 쓰는 테이블의 이름입니다.
  • [QUERY]는 표준 SQL 구문의 쿼리입니다.

쓰기 처리 플래그를 지정하지 않으면 비어 있는 경우에만 테이블에 결과를 쓰는 것이 기본 동작입니다. 테이블이 존재하고 비어 있지 않으면 다음 오류가 반환됩니다. 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 --location=US 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 --location=US 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이라는 이름의 대상 테이블에 쿼리 결과를 추가하려면 다음 명령어를 입력합니다. 데이터세트는 기본 프로젝트가 아닌 myotherproject에 있습니다. 명령어는 --append 플래그를 사용하여 쿼리 결과를 대상 테이블에 추가합니다.

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

API

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

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

Go

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

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")

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)
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.Println(row)
}

자바

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

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

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
// String destinationDataset = 'my_destination_dataset';
// String destinationTable = 'my_destination_table';
String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
QueryJobConfiguration queryConfig =
    // Note that setUseLegacySql is set to false by default
    QueryJobConfiguration.newBuilder(query)
        // Save the results of the query to a permanent table.
        .setDestinationTable(TableId.of(destinationDataset, destinationTable))
        .build();

// Print the results.
for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
  for (FieldValue val : row) {
    System.out.printf("%s,", val.toString());
  }
  System.out.printf("\n");
}

Python

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

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

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'your_dataset_id'

job_config = bigquery.QueryJobConfig()
# Set the destination table
table_ref = client.dataset(dataset_id).table('your_table_id')
job_config.destination = table_ref
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,
    # Location must match that of the dataset(s) referenced in the query
    # and of the destination table.
    location='US',
    job_config=job_config)  # API request - starts the query

query_job.result()  # Waits for the query to finish
print('Query results loaded to table {}'.format(table_ref.path))

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

외부 데이터 소스(제휴 데이터 소스라고도 함)는 데이터가 BigQuery에 저장되어 있지는 않지만 직접 쿼리할 수 있는 데이터 소스입니다. 데이터를 로드하거나 스트리밍하는 대신 외부 데이터 소스를 참조하는 테이블을 만들 수 있습니다.

BigQuery에서 직접적인 데이터 쿼리를 지원하는 외부 소스는 다음과 같습니다.

지원되는 외부 데이터 소스에 저장된 데이터를 참조하는 임시 또는 영구 테이블을 만들어 외부 데이터 소스의 데이터를 쿼리할 수 있습니다. 외부 데이터 소스 작업에 대한 자세한 내용은 다음 항목을 참조하세요.

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

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

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

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

테이블 액세스 권한 제어

테이블에 직접 액세스 제어를 할당할 수는 없습니다. 데이터세트 수준이나 프로젝트 수준에서 액세스 제어를 구성하는 방법으로 테이블 액세스 권한을 제어할 수 있습니다.

데이터세트 수준의 액세스 제어는 사용자, 그룹, 서비스 계정이 해당 데이터세트의 테이블에서 수행할 수 있는 작업을 지정합니다. 데이터세트 수준 권한만 할당할 경우, 프로젝트에 대한 액세스를 제공하는 기본 또는 사전 정의된 프로젝트 수준 역할(예: bigquery.user)도 할당해야 합니다.

개별 데이터세트에 액세스를 부여하는 대신, 프로젝트의 모든 데이터세트에 포함된 모든 테이블 데이터에 대한 권한을 부여하는 사전 정의된 프로젝트 수준 IAM 역할을 할당할 수 있습니다.

IAM 커스텀 역할을 만들 수도 있습니다. 커스텀 역할을 만들 때 부여하는 권한은 사용자, 그룹 또는 서비스 계정이 수행할 수 있게 허용하려는 테이블 작업에 따라 달라집니다.

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

테이블 데이터 작업에 대한 자세한 내용은 테이블 데이터 관리를 참조하세요.

테이블 사용

테이블에 대한 정보 가져오기

BigQuery 웹 UI 또는 bq show CLI 명령어를 사용하거나 tables.get API 메소드를 호출하여 테이블에 대한 정보를 가져올 수 있습니다.

필수 권한

테이블 정보를 가져오려면 데이터세트에 대해 READER 역할을 할당받거나 bigquery.tables.get 권한이 포함된 프로젝트 수준의 IAM 역할을 할당받아야 합니다. 프로젝트 수준에서 bigquery.tables.get 권한을 할당받으면 프로젝트의 모든 테이블 정보를 가져올 수 있습니다. 아래의 사전 정의된 프로젝트 수준 IAM 역할에는 bigquery.tables.get 권한이 있습니다.

또한 bigquery.user 역할을 할당받은 사용자에게는 bigquery.datasets.create 권한이 있습니다. 따라서 bigquery.user 역할을 할당받은 사용자는 자신이 생성한 모든 데이터세트의 테이블에 관한 정보를 가져올 수 있습니다. bigquery.user 역할에 할당된 사용자가 데이터세트를 만들면 이 사용자에게 해당 데이터세트에 대한 OWNER 액세스 권한이 부여됩니다. 데이터세트에 대한 OWNER 액세스 권한이 있는 사용자는 해당 데이터세트와 데이터세트에 포함된 모든 테이블을 완벽하게 제어할 수 있습니다.

BigQuery의 IAM 역할 및 권한에 대한 자세한 내용은 액세스 제어를 참조하세요. 데이터세트 수준 역할에 대한 자세한 내용은 데이터세트의 기본 역할을 참조하세요.

테이블 정보 가져오기

테이블에 대한 정보를 가져오려면 다음과 같이 하세요.

웹 UI

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

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

  3. Details(세부정보)를 클릭하면, 테이블 세부정보 페이지에 테이블 설명과 테이블 정보가 표시됩니다.

    테이블 세부정보 보기

  4. Schema 탭을 클릭하여 테이블의 스키마 정의를 확인합니다.

CLI

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

mydatasetmytable에 대해 스키마 정보만 표시하려면 다음 명령어를 입력합니다. mydataset은 기본 프로젝트가 아니라 myotherproject에 있습니다.

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

API

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

Go

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

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

자바

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

TableId tableId = TableId.of(projectId, datasetName, tableName);
Table table = bigquery.getTable(tableId);

Python

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

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'
# table_id = 'my_table'

dataset_ref = client.dataset(dataset_id)
table_ref = dataset_ref.table(table_id)
table = client.get_table(table_ref)  # API Request

# View table properties
print(table.schema)
print(table.description)
print(table.num_rows)

데이터세트의 테이블 나열

BigQuery 웹 UI 또는 bq ls CLI 명령어를 사용하거나 tables.list API 메소드를 호출하여 데이터세트의 테이블을 나열할 수 있습니다.

필수 권한

데이터세트의 테이블을 나열하려면 데이터세트에 대한 READER 역할을 할당받거나, bigquery.tables.list 권한을 포함하는 프로젝트 수준의 IAM 역할을 할당받아야 합니다. 프로젝트 수준에서 bigquery.tables.list 권한을 할당받으면 프로젝트에 있는 모든 데이터세트의 테이블을 나열할 수 있습니다. 사전 정의된 프로젝트 수준 IAM 역할은 bigquery.jobUser를 제외하고 모두 bigquery.tables.list 권한을 포함합니다.

BigQuery의 IAM 역할 및 권한에 대한 자세한 내용은 액세스 제어를 참조하세요. 데이터세트 수준 역할에 대한 자세한 내용은 데이터세트의 기본 역할을 참조하세요.

테이블 나열

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

웹 UI

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

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

    테이블 보기

명령줄

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

bq ls --format=pretty [PROJECT_ID]:[DATASET]

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

  • [PROJECT_ID]는 프로젝트 ID입니다.
  • [DATASET]는 데이터세트 이름입니다.

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

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

예:

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

bq ls --format=pretty mydataset

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

bq ls --format=pretty myotherproject:mydataset

API

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

C#

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

public List<BigQueryTable> ListTables(BigQueryClient client, string datasetId)
{
    var tables = client.ListTables(datasetId).ToList();
    return tables;
}

Go

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

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

자바

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

DatasetId datasetId = DatasetId.of(projectId, datasetName);
Page<Table> tables = bigquery.listTables(datasetId, TableListOption.pageSize(100));
for (Table table : tables.iterateAll()) {
  // do something with the table
}

Node.js

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

// Imports the Google Cloud client library
const BigQuery = require('@google-cloud/bigquery');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = "your-project-id";
// const datasetId = "my_dataset";

// Creates a client
const bigquery = new BigQuery({
  projectId: projectId,
});

// Lists all tables in the dataset
bigquery
  .dataset(datasetId)
  .getTables()
  .then(results => {
    const tables = results[0];
    console.log('Tables:');
    tables.forEach(table => console.log(table.id));
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

PHP

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

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 참조 문서를 확인하세요.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')

tables = list(client.list_tables(dataset_ref))  # API request(s)
assert len(tables) == 0

table_ref = dataset.table('my_table')
table = bigquery.Table(table_ref)
client.create_table(table)                  # API request
tables = list(client.list_tables(dataset))  # API request(s)

assert len(tables) == 1
assert tables[0].table_id == 'my_table'

Ruby

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

# project_id = "Your Google Cloud project ID"
# dataset_id = "ID of the dataset to create table in"

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new project: project_id
dataset  = bigquery.dataset dataset_id

dataset.tables.each do |table|
  puts table.table_id
end

메타테이블을 사용하여 테이블 메타데이터 가져오기

BigQuery는 메타데이터(예: 데이터세트에 있는 테이블 및 뷰의 목록)를 나타내는 콘텐츠가 포함된 특수한 테이블을 제공합니다. 이 '메타 테이블'은 읽기 전용입니다. 데이터세트에 있는 테이블과 뷰에 대한 메타데이터에 액세스하려면 쿼리의 SELECT 문에 __TABLES_SUMMARY__ 메타 테이블을 사용합니다. BigQuery 웹 UI를 사용하거나, 명령줄 도구의 bq query 명령어를 사용하거나, jobs.insert API 메소드를 호출하고 쿼리 작업을 구성하여 쿼리를 실행할 수 있습니다.

__TABLES_SUMMARY__ 메타 테이블을 사용하는 쿼리는 다음과 같습니다.

    SELECT [FIELD] FROM [DATASET].__TABLES_SUMMARY__

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

  • DATASET는 데이터세트 이름입니다.
  • FIELD는 다음 중 하나입니다.
설명
project_id 프로젝트 이름입니다.
dataset_id 데이터세트 이름입니다.
table_id 테이블 또는 뷰의 이름입니다.
creation_time 1970년 1월 1일(UTC)부터 테이블 또는 보기가 생성된 시간까지의 경과 시간(밀리초)입니다.
type 테이블 유형을 나타내는 정수입니다. 일반 테이블은 1이고 보기는 2입니다.

필수 권한

__TABLES_SUMMARY__ 메타 테이블을 사용하는 쿼리 작업을 실행하려면 bigquery.jobs.create 권한이 있어야 합니다. 아래의 사전 정의된 프로젝트 수준 IAM 역할에는 bigquery.jobs.create 권한이 있습니다.

또한 데이터세트 수준에서 READER 역할을 할당받거나 bigquery.tables.getData 권한이 있는 프로젝트 수준의 IAM 역할을 할당받아야 합니다. 사전 정의된 프로젝트 수준 IAM 역할은 bigquery.userbigquery.jobUser를 제외하고 모두 bigquery.tables.getData 권한이 있습니다.

메타 테이블 제한사항

메타 테이블에는 다음과 같은 제한사항이 적용됩니다.

  • 일반적으로 __TABLES_SUMMARY__는 최대 수천 개의 테이블을 포함하는 데이터세트에서 적정 속도를 지원합니다. 데이터세트가 커질수록 __TABLES_SUMMARY__가 점점 느려지고 사용할 수 있는 리소스를 초과할 수 있습니다.
  • tables.insert 메소드에서는 메타 테이블을 사용할 수 없습니다.
  • 메타 테이블을 대상 테이블로 사용할 수 없습니다.
  • 메타 테이블은 이전 SQL의 테이블 데코레이터를 지원하지 않습니다.
  • 데이터세트의 테이블 나열 시 메타 테이블은 나타나지 않습니다.

메타 테이블 예

다음 쿼리는 bigquery-public-data.samples 데이터세트의 모든 메타데이터를 가져옵니다.

웹 UI

#standardSQL
SELECT
  *
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`

명령줄

bq --location=US query --use_legacy_sql=false '
SELECT
  *
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`'

출력은 다음과 같이 표시됩니다.

+----------------------+------------+-----------------+---------------+------+
| project_id           | dataset_id |    table_id     | creation_time | type |
+----------------------+------------+-----------------+---------------+------+
| bigquery-public-data | samples    | github_nested   | 1348782587310 |    1 |
| bigquery-public-data | samples    | github_timeline | 1335915950690 |    1 |
| bigquery-public-data | samples    | gsod            | 1335916040125 |    1 |
| bigquery-public-data | samples    | natality        | 1335916045005 |    1 |
| bigquery-public-data | samples    | shakespeare     | 1335916045099 |    1 |
| bigquery-public-data | samples    | trigrams        | 1335916127449 |    1 |
| bigquery-public-data | samples    | wikipedia       | 1335916132870 |    1 |
+----------------------+------------+-----------------+---------------+------+

다음 쿼리는 bigquery-public-data.samples 데이터세트에 있는 모든 테이블과 보기를 나열합니다.

웹 UI

#standardSQL
SELECT
  table_id
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`

명령줄

bq --location=US query --use_legacy_sql=false '
SELECT
  table_id
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`'

출력은 다음과 같이 표시됩니다.

+-----------------+
|    table_id     |
+-----------------+
| github_nested   |
| github_timeline |
| gsod            |
| natality        |
| shakespeare     |
| trigrams        |
| wikipedia       |
+-----------------+

다음 쿼리는 bigquery-public-data.samples 데이터세트에 있는 각 테이블의 유형을 나열합니다.

웹 UI

#standardSQL
SELECT
  table_id, type
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`

명령줄

bq --location=US query --use_legacy_sql=false '
SELECT
  table_id, type
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`'

출력은 다음과 같은 형식으로 표시됩니다.

+-----------------+------+
|    table_id     | type |
+-----------------+------+
| github_nested   |   1  |
| github_timeline |   1  |
| gsod            |   1  |
| natality        |   1  |
| shakespeare     |   1  |
| trigrams        |   1  |
| wikipedia       |   1  |
+-----------------+------+

다음 단계

이 페이지가 도움이 되었나요? 평가를 부탁드립니다.

다음에 대한 의견 보내기...

도움이 필요하시나요? 지원 페이지를 방문하세요.