스키마 지정

BigQuery를 사용하면 테이블에 데이터 로드 시 그리고 빈 테이블 생성 시 테이블의 스키마를 지정할 수 있습니다. 또는 지원되는 데이터 형식의 스키마 자동 감지를 사용할 수 있습니다. Avro, Parquet, ORC, Cloud Firestore 내보내기 파일 또는 Cloud Datastore 내보내기 파일을 로드하면 자체 설명 소스 데이터에서 스키마가 자동으로 검색됩니다.

다음 방법 중 하나로 테이블의 스키마를 지정할 수 있습니다.

  • 스키마 수동 지정:
    • GCP Console 사용
    • 기본 BigQuery 웹 UI 사용
    • CLI를 사용한 인라인
  • JSON 형식으로 스키마 파일 만들기
  • jobs.insert 메소드 호출 및 configuration.load.schema 속성 구성
  • tables.insert 메소드 호출 및 schema 속성을 사용하여 테이블 리소스에서 스키마 구성

데이터를 로드하거나 빈 테이블을 만든 후 테이블의 스키마 정의를 수정할 수 있습니다.

스키마 구성요소

테이블 스키마를 지정하는 경우, 각 열의 이름과 데이터 유형을 제공해야 합니다. 선택적으로 열의 설명과 모드를 제공할 수도 있습니다.

열 이름

열 이름은 문자(a-z, A-Z), 숫자(0-9) 또는 밑줄(_)만 포함해야 하며 문자 또는 밑줄로 시작해야 합니다. 최대 열 이름 길이는 128자입니다. 열 이름은 다음과 같은 프리픽스를 사용할 수 없습니다.

  • _TABLE_
  • _FILE_
  • _PARTITION

중복 열 이름은 대소문자가 다른 경우라도 허용되지 않습니다. 예를 들어, Column1 이름의 열과 column1 이름의 열은 동일한 열로 간주됩니다.

열 설명

각 열에는 선택적 설명이 포함될 수 있습니다. 설명은 최대 1,024자의 문자열입니다.

표준 SQL 데이터 유형

BigQuery 표준 SQL을 사용하면 스키마에서 다음 데이터 유형을 지정할 수 있습니다. 데이터 유형은 필수입니다.

데이터 유형 설명
정수 소수 구성요소가 없는 숫자 값
부동 소수점 소수 구성요소가 있는 대략적인 숫자 값
숫자 소수 구성요소가 있는 정확한 숫자 값
부울 TRUE 또는 FALSE(대소문자 구분)
문자열 가변 길이 문자(유니코드) 데이터
바이트 가변 길이 바이너리 데이터
날짜 논리적 달력 날짜
날짜/시간 연도, 월, 일, 시간, 분, 초, 초 미만
시간 특정 날짜와 무관한 시간
타임스탬프 마이크로초 정밀도의 절대 시점
구조(레코드) 각각 유형(필수)과 필드 이름(선택사항)이 있는 정렬된 필드의 컨테이너
지역 지구 표면의 점 집합(WGS84 참조 회전 타원체상의 점, 선, 다각형으로 구성된 집합, 측지 에지 포함)

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

데이터 쿼리 시 배열 유형을 선언할 수도 있습니다. 자세한 내용은 배열을 사용한 작업을 참조하세요.

모드

BigQuery는 열에 대해 다음 모드를 지원합니다. 모드는 선택사항입니다. 모드가 지정되지 않으면 열은 기본적으로 NULLABLE로 설정됩니다.

모드 설명
Nullable 열에서 NULL 값 허용(기본값)
Required NULL 값이 허용되지 않음
Repeated 열에 지정된 유형의 값 배열 포함

모드에 대한 자세한 내용은 API 참조에서 schema.fields.mode를 참조하세요.

스키마 수동 지정

데이터를 로드하거나 빈 테이블을 만드는 경우, GCP Console, 기본 BigQuery 웹 UI 또는 명령줄 도구를 사용하여 수동으로 테이블의 스키마를 지정할 수 있습니다. CSV 및 JSON(줄바꿈으로 구분됨) 파일을 로드하면 스키마를 수동으로 지정할 수 있습니다. Avro, Parquet, ORC, Cloud Firestore 내보내기 데이터 또는 Cloud Datastore 내보내기 데이터를 로드하면 자체 설명 소스 데이터에서 스키마가 자동으로 검색됩니다.

테이블 스키마를 수동으로 지정하려면 다음 단계를 따르세요.

기본 UI

기본 BigQuery 웹 UI에서 필드 추가 옵션 또는 텍스트로 편집 옵션을 사용하여 스키마를 지정할 수 있습니다.

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

    BigQuery 웹 UI로 이동

  2. 탐색창에서 데이터세트 이름 옆에 있는 아래쪽 화살표 아이콘 아래쪽 화살표 아이콘을 클릭하고 새 테이블 만들기를 클릭합니다. 데이터를 로드하는 프로세스는 빈 테이블을 만드는 프로세스와 동일합니다.

  3. 테이블 만들기 페이지에서 다음을 수행합니다.

    • 소스 데이터에서 소스로부터 만들기를 클릭하거나(데이터를 로드하는 경우) 빈 테이블 만들기를 클릭합니다.
    • 대상 테이블에서 데이터세트를 선택하고 대상 테이블 이름 필드에 테이블 이름을 입력합니다.

    • 스키마에서 다음 옵션 중 하나를 선택하여 스키마를 수동으로 지정합니다.

      • 옵션 1: 필드 추가를 사용하여 각 필드의 이름, 유형, 모드를 지정합니다. BigQuery 웹 UI에서 필드 추가 옵션을 사용하면 필드 설명을 추가할 수 없지만 데이터를 로드한 후 UI에서 필드 설명을 수동으로 추가할 수 있습니다.

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

      • 옵션 2: 텍스트로 편집을 클릭하고 JSON 배열 형식으로 스키마를 붙여 넣습니다. JSON 배열을 사용하는 경우, JSON 스키마 파일 만들기와 같은 프로세스로 스키마를 생성합니다.

        JSON 배열로 스키마 추가

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

명령줄

다음을 사용하여 [FIELD]:[DATA_TYPE],[FIELD]:[DATA_TYPE] 형식으로 스키마 인라인을 수동으로 입력합니다.

  • 데이터를 로드하는 경우, load 명령어
  • 빈 테이블을 만드는 경우, mk 명령어

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

인라인 스키마 정의를 사용하여 테이블에 데이터를 로드하려면 load 명령어를 입력하고 --source_format 플래그를 사용하여 데이터 형식을 지정합니다. 기본 프로젝트가 아닌 프로젝트에서 테이블로 데이터를 로드하는 경우, 프로젝트 ID를 [PROJECT_ID]:[DATASET].[TABLE_NAME] 형식으로 포함합니다.

--location 플래그를 제공하고 값을 사용자 위치로 설정합니다.

bq --location=[LOCATION] load --source_format=[FORMAT] [PROJECT_ID]:[DATASET].[TABLE_NAME] [PATH_TO_SOURCE] [SCHEMA]

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

  • [LOCATION]은 사용자 위치의 이름입니다. --location 플래그는 선택사항입니다. 예를 들어 도쿄 지역에서 BigQuery를 사용하는 경우 플래그 값을 asia-northeast1로 설정할 수 있습니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.
  • [FORMAT]은 NEWLINE_DELIMITED_JSON 또는 CSV입니다.
  • [PROJECT_ID]는 프로젝트 ID입니다.
  • [DATASET]는 데이터를 로드하는 테이블이 포함된 데이터세트입니다.
  • [TABLE]은 데이터를 로드하는 테이블 이름입니다.
  • [PATH_TO_SOURCE]는 로컬 머신 또는 Cloud Storage에서 CSV 또는 JSON 데이터 파일의 위치입니다.
  • [SCHEMA]는 인라인 스키마 정의입니다.

예:

다음 명령어를 입력하여 myfile.csv 이름의 로컬 CSV 파일에서 기본 프로젝트의 mydataset.mytable로 데이터를 로드합니다. 스키마는 인라인으로 수동 지정됩니다. mydataset는 US 다중 지역 위치에서 생성되었습니다.

bq --location=US load --source_format=CSV mydataset.mytable ./myfile.csv qtr:STRING,sales:FLOAT,year:STRING

다음 명령어를 입력하여 myfile.csv 이름의 로컬 CSV 파일에서 기본 프로젝트의 mydataset.mytable로 데이터를 로드합니다. mydataset는 asia-northeast1 지역에서 생성되었습니다. 스키마는 인라인으로 수동 지정됩니다.

bq --location=asia-northeast1 load --source_format=CSV mydataset.mytable ./myfile.csv qtr:STRING,sales:FLOAT,year:STRING

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

빈 테이블 생성 시 인라인 스키마 정의를 지정하려면 --table 또는 -t 플래그와 함께 mk 명령어를 입력합니다. 기본 프로젝트가 아닌 다른 프로젝트에서 테이블을 만드는 경우, 프로젝트 ID를 [PROJECT_ID]:[DATASET].[TABLE] 형식으로 명령어에 추가합니다.

bq mk --table [PROJECT_ID]:[DATASET].[TABLE] [SCHEMA]

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

  • [PROJECT_ID]는 프로젝트 ID입니다.
  • [DATASET]는 프로젝트의 데이터세트입니다.
  • [TABLE]은 만드는 테이블의 이름입니다.
  • [SCHEMA]는 인라인 스키마 정의입니다.

예를 들어, 다음 명령어는 기본 프로젝트에 mytable이라는 이름의 빈 테이블을 만듭니다. 스키마는 인라인으로 수동 지정됩니다.

bq mk --table mydataset.mytable qtr:STRING,sales:FLOAT,year:STRING

빈 테이블 만들기에 대한 자세한 내용은 스키마 정의를 사용하여 빈 테이블 만들기를 참조하세요.

C#

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

데이터를 테이블로 로드 시 테이블의 스키마를 지정하려면 다음 내용을 따르세요. 
using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsJson
{
    public void LoadTableGcsJson(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
        var dataset = client.GetDataset(datasetId);
        var schema = new TableSchemaBuilder {
            { "name", BigQueryDbType.String },
            { "post_abbr", BigQueryDbType.String }
        }.Build();
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.NewlineDelimitedJson
        };
        // Create and run job
        BigQueryJob loadJob = client.CreateLoadJob(
            sourceUri: gcsURI, destination: destinationTableRef,
            schema: schema, options: jobOptions);
        loadJob.PollUntilCompleted();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

빈 테이블 생성 시 스키마를 지정하려면 다음을 따르세요. 

using Google.Cloud.BigQuery.V2;
using System;

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

데이터를 테이블에 로드 시 테이블의 스키마를 지정하려면 다음 내용을 따르세요. 
// 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")
gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.json")
gcsRef.SourceFormat = bigquery.JSON
gcsRef.Schema = bigquery.Schema{
	{Name: "name", Type: bigquery.StringFieldType},
	{Name: "post_abbr", Type: bigquery.StringFieldType},
}
loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
loader.WriteDisposition = bigquery.WriteEmpty

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

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

빈 테이블 생성 시 스키마를 지정하려면 다음을 따르세요. 

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

Python

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

데이터를 테이블에 로드할 때 테이블의 스키마를 지정하려면 LoadJobConfig.schema 속성을 구성합니다. 
# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.schema = [
    bigquery.SchemaField('name', 'STRING'),
    bigquery.SchemaField('post_abbr', 'STRING')
]
job_config.source_format = bigquery.SourceFormat.NEWLINE_DELIMITED_JSON
uri = 'gs://cloud-samples-data/bigquery/us-states/us-states.json'

load_job = client.load_table_from_uri(
    uri,
    dataset_ref.table('us_states'),
    location='US',  # Location must match that of the destination dataset.
    job_config=job_config)  # API request
print('Starting job {}'.format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print('Job finished.')

destination_table = client.get_table(dataset_ref.table('us_states'))
print('Loaded {} rows.'.format(destination_table.num_rows))

빈 테이블을 생성할 때 스키마를 지정하려면 Table.schema 속성을 구성합니다. 

# 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'

JSON 스키마 파일 지정

스키마를 수동으로 지정하지 않으려면 CLI로 사용할 JSON 스키마 파일을 만들 수 있습니다. JSON 스키마 파일은 다음을 포함하는 JSON 배열로 구성됩니다.

JSON 스키마 파일 만들기

JSON 스키마 파일을 만들려면 해당 텍스트 편집기를 사용해 다음 내용을 입력합니다.

[
 {
   "description": "[DESCRIPTION]",
   "name": "[NAME]",
   "type": "[TYPE]",
   "mode": "[MODE]"
 },
 {
   "description": "[DESCRIPTION]",
   "name": "[NAME]",
   "type": "[TYPE]",
   "mode": "[MODE]"
 }
]

JSON 배열은 시작 및 끝 괄호 []로 나타냅니다. 각 열 항목은 쉼표 },로 구분해야 합니다.

다음 명령어를 입력하여 기존 테이블 스키마를 로컬 파일에 작성할 수 있습니다.

bq show --schema --format=prettyjson [PROJECT_ID]:[DATASET].[TABLE] > [PATH_TO_FILE]

출력 파일을 고유 JSON 스키마 파일에 대한 시작점으로 사용할 수 있습니다. 이 방식을 사용하는 경우, 파일에 테이블의 스키마를 나타내는 JSON 배열만 포함되도록 해야 합니다.

예를 들어, 다음 JSON 배열은 기본 테이블 스키마를 나타냅니다. 이 스키마에는 qtr (REQUIRED STRING), rep (NULLABLE STRING), sales (NULLABLE FLOAT) 등 세 개의 열이 있습니다.

[
  {
    "description": "quarter",
    "mode": "REQUIRED",
    "name": "qtr",
    "type": "STRING"
  },
  {
    "description": "sales representative",
    "mode": "NULLABLE",
    "name": "rep",
    "type": "STRING"
  },
  {
    "description": "total sales",
    "mode": "NULLABLE",
    "name": "sales",
    "type": "FLOAT"
  }
]

JSON 스키마 파일 사용

JSON 스키마 파일을 만든 후 명령줄에서 이를 지정할 수 있습니다. GCP Console, 기본 BigQuery 웹 UI 또는 API를 통해서는 스키마 파일을 사용할 수 없습니다.

다음을 사용하여 스키마 파일을 수동으로 제공합니다.

  • 데이터를 로드하는 경우, load 명령어
  • 빈 테이블을 만드는 경우, mk 명령어

JSON 스키마 파일 제공 시 로컬에서 읽을 수 있는 위치에 파일을 저장해야 합니다. Cloud Storage 또는 Google 드라이브에 저장된 JSON 스키마 파일을 지정할 수 없습니다.

데이터 로드 시 스키마 파일 지정

다음 명령어는 JSON 파일의 스키마 정의를 사용하여 데이터를 테이블에 로드합니다.

bq --location=[LOCATION] load --source_format=[FORMAT] [PROJECT_ID]:[DATASET].[TABLE] [PATH_TO_DATA_FILE] [PATH_TO_SCHEMA_FILE]

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

  • [LOCATION]은 사용자 위치의 이름입니다. --location 플래그는 선택사항입니다. 예를 들어 도쿄 지역에서 BigQuery를 사용하는 경우 플래그 값을 asia-northeast1로 설정할 수 있습니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.
  • [FORMAT]은 NEWLINE_DELIMITED_JSON 또는 CSV입니다.
  • [PROJECT_ID]는 프로젝트 ID입니다.
  • [DATASET]는 데이터를 로드하는 테이블이 포함된 데이터세트입니다.
  • [TABLE]은 데이터를 로드하는 테이블 이름입니다.
  • [PATH_TO_DATA_FILE]은 로컬 머신 또는 Google Cloud Storage에서 CSV 또는 JSON 데이터 파일의 위치입니다.
  • [SCHEMA_FILE]은 로컬 머신에 있는 스키마 파일에 대한 경로입니다.

예:

다음 명령어를 입력하여 myfile.csv 이름의 로컬 CSV 파일에서 기본 프로젝트의 mydataset.mytable로 데이터를 로드합니다. mydataset는 US 다중 지역 위치에서 생성되었습니다. 스키마는 myschema.json에 지정됩니다.

bq --location=US load --source_format=CSV mydataset.mytable ./myfile.csv ./myschema.json

다음 명령어를 입력하여 myfile.csv 이름의 로컬 CSV 파일에서 기본 프로젝트의 mydataset.mytable로 데이터를 로드합니다. mydataset는 asia-northeast1 지역에서 생성되었습니다. 스키마는 myschema.json에 지정됩니다.

bq --location=asia-northeast1 load --source_format=CSV mydataset.mytable ./myfile.csv ./myschema.json

테이블 생성 시 스키마 파일 지정

다음 명령어는 JSON 파일의 스키마 정의를 사용하여 기존 데이터세트에 빈 테이블을 만듭니다.

bq mk --table [PROJECT_ID]:[DATASET].[TABLE] [PATH_TO_SCHEMA_FILE]

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

  • [PROJECT_ID]는 프로젝트 ID입니다.
  • [DATASET]는 프로젝트의 데이터세트입니다.
  • [TABLE]은 만드는 테이블의 이름입니다.
  • [PATH_TO_SCHEMA_FILE]은 로컬 머신에 있는 스키마 파일의 경로입니다.

예를 들어, 다음 명령어는 기본 프로젝트의 mydataset에 mytable이라는 테이블을 만듭니다. 스키마는 myschema.json에 지정됩니다.

bq mk --table mydataset.mytable ./myschema.json

API에서 스키마 지정

API를 사용하여 테이블 스키마를 지정하려면 다음 내용을 따르세요.

  • 데이터 로드 시 스키마를 지정하려면 jobs.insert 메소드를 호출하고 configuration.load.schema 속성을 구성합니다. jobReference 섹션의 location 속성에 사용자 지역을 지정합니다.
  • 테이블 생성 시 스키마를 지정하려면 tables.insert 메소드를 호출하고 schema 속성을 사용하여 테이블 리소스에서 스키마를 구성합니다.

API를 사용하여 스키마를 지정하는 프로세스는 JSON 스키마 파일 만들기와 유사합니다.

다음 단계

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

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

이 페이지
문서에 대한 의견
BigQuery
제품에 대한 의견
도움이 필요하시나요? 지원 페이지를 방문하세요.