Cloud Storage에서 ORC 데이터 로드

이 페이지에서는 Cloud Storage에서 BigQuery로 ORC 데이터를 로드하는 방법에 대해 간략하게 설명합니다.

ORC은 Apache Hadoop 생태계에서 널리 사용하는 오픈소스 열 기반 데이터 형식입니다.

Cloud Storage에서 ORC 데이터를 로드할 때는 새 테이블 또는 파티션에 데이터를 로드하거나 기존 테이블 또는 파티션에 추가하거나 덮어쓸 수 있습니다. BigQuery에 로드한 데이터는 Capacitor용 열 형식(BigQuery의 스토리지 형식)으로 변환됩니다.

Cloud Storage에서 BigQuery 테이블로 데이터를 로드하는 경우 테이블을 포함한 데이터 세트는 Cloud Storage 버킷과 같은 리전이나 멀티 리전 위치에 있어야 합니다.

로컬 파일에서 ORC 데이터를 로드하는 방법에 대한 자세한 내용은 로컬 데이터 소스에서 BigQuery로 데이터 로드를 참조하세요.

제한사항

Cloud Storage 버킷에서 BigQuery로 데이터를 로드할 때는 다음과 같은 제한사항이 적용됩니다.

• 데이터 세트 위치가 US 멀티 리전 이외의 값으로 설정되면 Cloud Storage 버킷은 데이터 세트와 동일한 리전에 있거나 동일한 멀티 리전에 포함되어 있어야 합니다.
• BigQuery는 외부 데이터 소스의 데이터 일관성을 보장하지 않습니다. 쿼리가 실행되는 동안 기본 데이터가 변경되면 예상치 못한 동작이 발생할 수 있습니다.
• BigQuery는 Cloud Storage 객체 버전 관리를 지원하지 않습니다. Cloud Storage URI에 세대 번호를 포함하면 로드 작업이 실패합니다.

시작하기 전에

이 문서의 각 태스크를 수행하는 데 필요한 권한을 사용자에게 제공하는 Identity and Access Management(IAM) 역할을 부여하고 데이터를 저장할 데이터 세트를 만듭니다.

필수 권한

데이터를 BigQuery로 로드하려면 로드 작업을 실행하고 데이터를 BigQuery 테이블과 파티션으로 로드할 수 있는 IAM 권한이 필요합니다. Cloud Storage에서 데이터를 로드할 경우 데이터가 포함된 버킷에 액세스할 수 있는 IAM 권한도 필요합니다.

데이터를 BigQuery로 로드할 수 있는 권한

데이터를 새 BigQuery 테이블이나 파티션으로 로드하거나 기존 테이블 또는 파티션을 추가하거나 덮어쓰려면 다음 IAM 권한이 필요합니다.

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

다음과 같이 사전 정의된 각 IAM 역할에는 데이터를 BigQuery 테이블이나 파티션에 로드하기 위해 필요한 권한이 포함되어 있습니다.

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

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

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

Cloud Storage에서 데이터를 로드할 수 있는 권한

Cloud Storage 버킷에서 데이터를 로드하는 데 필요한 권한을 얻으려면 관리자에게 버킷의 스토리지 관리자(roles/storage.admin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 Cloud Storage 버킷에서 데이터를 로드하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 확장하세요.

필수 권한

Cloud Storage 버킷에서 데이터를 로드하려면 다음 권한이 필요합니다.

• storage.buckets.get
• storage.objects.get
• storage.objects.list (required if you are using a URI wildcard)

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

데이터 세트 만들기

데이터를 저장할 BigQuery 데이터 세트를 만듭니다.

ORC 스키마

ORC 파일을 BigQuery로 로드하면 테이블 스키마는 자기 기술 소스 데이터에서 자동으로 검색됩니다. BigQuery가 소스 데이터에서 스키마를 검색할 때는 알파벳순으로 마지막 파일이 사용됩니다.

예를 들어 Cloud Storage에 다음 ORC 파일이 있다고 가정해 보겠습니다.

gs://mybucket/00/
  a.orc
  z.orc
gs://mybucket/01/
  b.orc

bq 명령줄 도구로 이 명령어를 실행하면 모든 파일(쉼표로 구분된 목록)이 로드되고 스키마가 mybucket/01/b.orc에서 파생됩니다.

bq load \
--source_format=ORC \
dataset.table \
"gs://mybucket/00/*.orc","gs://mybucket/01/*.orc"

BigQuery가 스키마를 감지하면 일부 ORC 데이터 유형은 GoogleSQL 구문과 호환되도록 BigQuery 데이터 유형으로 변환됩니다. 감지한 스키마에 있는 모든 필드는 NULLABLE입니다. 자세한 내용은 ORC 변환을 참조하세요.

스키마가 서로 다른 ORC 파일을 로드할 때 여러 스키마에 지정된 동일 필드(이름과 중첩 수준이 같음)는 각 스키마 정의에서 변환된 같은 BigQuery 데이터 유형으로 매핑되어야 합니다.

외부 테이블을 만들기 위한 테이블 스키마를 제공하려면 BigQuery API의 referenceFileSchemaUri 속성을 설정하거나 bq 명령줄 도구의
--reference_file_schema_uri 매개변수를 참조 파일의 URL로 설정합니다.

예를 들면 --reference_file_schema_uri="gs://mybucket/schema.orc"입니다.

ORC 압축

BigQuery는 ORC 파일 콘텐츠에 대해 다음과 같은 압축 코덱을 지원합니다.

• Zlib
• Snappy
• LZO
• LZ4

ORC 파일의 데이터는 BigQuery에 업로드된 후 압축된 상태로 유지되지 않습니다. 데이터 스토리지는 데이터 세트 스토리지 청구 모델에 따라 논리적 바이트 또는 물리적 바이트로 보고됩니다. 스토리지 사용량에 대한 정보를 가져오려면 INFORMATION_SCHEMA.TABLE_STORAGE 뷰를 쿼리합니다.

ORC 데이터를 새 테이블에 로드

다음과 같은 방법으로 새 테이블에 ORC 데이터를 로드할 수 있습니다.

• Google Cloud 콘솔 사용
• bq 명령줄 도구의 bq load 명령어 사용
• jobs.insert API 메서드 호출 및 load 작업 구성
• 클라이언트 라이브러리 사용

Cloud Storage에서 새 BigQuery 테이블로 ORC 데이터를 로드하려면 다음 안내를 따르세요.

콘솔

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

   BigQuery로 이동

2. 탐색기 창에서 프로젝트를 펼친 후 데이터 세트를 선택합니다.
3. 데이터 세트 정보 섹션에서 테이블 만들기를 클릭합니다.
4. 테이블 만들기 패널에서 다음 세부정보를 지정합니다.
1. 소스 섹션의 다음 항목으로 테이블 만들기 목록에서 Google Cloud Storage를 선택합니다. 그런 후 다음 작업을 수행합니다.
   1. Cloud Storage 버킷에서 파일을 선택하거나 Cloud Storage URI를 입력합니다. Google Cloud 콘솔에서는 URI를 여러 개 포함할 수 없지만 와일드 카드는 지원됩니다. Cloud Storage 버킷은 생성, 추가 또는 덮어쓰려는 테이블이 포함된 데이터 세트와 동일한 위치에 있어야 합니다.
   2. 파일 형식으로 ORC를 선택합니다.
2. 대상 섹션에서 다음 세부정보를 지정합니다.
   1. 데이터 세트에서 테이블을 만들 데이터 세트를 선택합니다.
   2. 테이블 필드에 만들려는 테이블의 이름을 입력합니다.
   3. 테이블 유형 필드가 기본 테이블로 설정되어 있는지 확인합니다.
3. 스키마 섹션은 그대로 놔둡니다. 스키마는 ORC 파일에 자체 기술됩니다.
4. 선택사항: 파티션 및 클러스터 설정을 지정합니다. 자세한 내용은 파티션을 나눈 테이블 만들기 및 클러스터링된 테이블 만들기 및 사용을 참조하세요.
5. 고급 옵션을 클릭하고 다음을 수행합니다.
   • 쓰기 환경설정에서 비어 있으면 쓰기를 선택한 상태로 둡니다. 이 옵션은 새 테이블을 만들어 데이터를 로드합니다.
   • 테이블 스키마에 없는 행의 값을 무시하려면 알 수 없는 값을 선택합니다.
   • Cloud Key Management Service 키를 사용하려면 암호화에서 고객 관리 키를 클릭합니다. Google 관리 키 설정을 그대로 두면 BigQuery는 저장 데이터를 암호화합니다.
6. 테이블 만들기를 클릭합니다.

참고: Google Cloud 콘솔을 사용하여 빈 테이블에 데이터를 로드하면 라벨, 설명, 테이블 만료 시간 또는 파티션 만료 시간을 추가할 수 없습니다.

테이블을 만든 후에 테이블의 만료 시간, 설명, 라벨을 업데이트할 수 있지만, Google Cloud 콘솔을 사용하여 테이블을 만든 후에 파티션 만료 시간을 추가할 수는 없습니다. 자세한 내용은 테이블 관리를 참조하세요.

SQL

LOAD DATA DDL 문을 사용합니다. 다음 예시는 ORC 파일을 새 테이블인 mytable에 로드합니다.

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

   BigQuery로 이동

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

   LOAD DATA OVERWRITE mydataset.mytable
   FROM FILES (
     format = 'ORC',
     uris = ['gs://bucket/path/file.orc']);

3. 실행을 클릭합니다.

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

bq

bq load 명령어를 사용하고, source_format으로 ORC를 지정하고, Cloud Storage URI를 포함합니다. 단일 URI, 쉼표로 구분된 URI 목록 또는 와일드 카드가 포함된 URI를 포함할 수 있습니다.

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

이 외에 다음과 같은 선택적 플래그가 있습니다.

• --time_partitioning_type: 테이블에 시간 기준 파티션 나누기를 사용 설정하고 파티션 유형을 설정합니다. 가능한 값은 HOUR, DAY, MONTH, YEAR입니다. DATE, DATETIME, TIMESTAMP 열을 기준으로 파티션을 나눈 테이블을 만드는 경우 이 플래그는 선택사항입니다. 시간 기준 파티션 나누기의 기본 파티션 유형은 DAY입니다. 기존 테이블의 파티션 나누기 사양을 변경할 수 없습니다.
• --time_partitioning_expiration: 시간 기준 파티션을 삭제할 시간을 초 단위로 지정하는 정수입니다. 만료 시간은 파티션의 UTC 날짜에 정수 값을 더한 값입니다.
• --time_partitioning_field: 파티션을 나눈 테이블을 만드는 데 사용되는 DATE 또는 TIMESTAMP 열입니다. 이 값 없이 시간 기준 파티션 나누기를 사용 설정하면 수집 시간으로 파티션을 나눈 테이블이 생성됩니다.
• --require_partition_filter: 이 옵션을 사용 설정하면 사용자는 쿼리할 파티션을 지정하는 WHERE 절을 포함해야 합니다. 파티션 필터를 필수항목으로 설정하면 비용을 줄이고 성능을 높일 수 있습니다. 자세한 내용은 파티션을 나눈 테이블 쿼리를 참조하세요.
• --clustering_fields: 클러스터링된 테이블을 만드는 데 사용된 쉼표로 구분된 열 이름(최대 4개) 목록입니다.

• --destination_kms_key: 테이블 데이터 암호화에 사용되는 Cloud KMS 키입니다.

  파티션을 나눈 테이블에 대한 자세한 내용은 다음을 참조하세요.

  • 파티션을 나눈 테이블 만들기

  클러스터링된 테이블에 대한 자세한 내용은 다음을 참조하세요.

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

  테이블 암호화에 대한 자세한 내용은 다음을 참조하세요.

  • Cloud KMS 키로 데이터 보호

BigQuery에 ORC 데이터를 로드하려면 다음 명령어를 입력하세요.

bq --location=location load \
--source_format=format \
dataset.table \
path_to_source

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

• location은 사용자의 위치입니다. --location 플래그는 선택사항입니다. 예를 들어 도쿄 리전에서 BigQuery를 사용하는 경우 플래그 값을 asia-northeast1로 설정하면 됩니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.
• format은 ORC입니다.
• dataset는 기존 데이터 세트입니다.
• table은 데이터를 로드하는 테이블 이름입니다.
• path_to_source는 정규화된 Cloud Storage URI 또는 쉼표로 구분된 URI 목록이며 와일드 카드도 지원됩니다.

예시:

다음 명령어는 gs://mybucket/mydata.orc에서 mydataset에 있는 mytable이라는 이름의 테이블로 데이터를 로드합니다.

    bq load \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

다음 명령어는 gs://mybucket/mydata.orc에서 mydataset에 있는 mytable이라는 새로운 수집 시간으로 파티션을 나눈 테이블로 데이터를 로드합니다.

    bq load \
    --source_format=ORC \
    --time_partitioning_type=DAY \
    mydataset.mytable \
    gs://mybucket/mydata.orc

다음 명령어는 gs://mybucket/mydata.orc에서 mydataset에 있는 mytable이라는 이름의 파티션을 나눈 테이블로 데이터를 로드합니다. 테이블의 파티션은 mytimestamp 열을 기준으로 나뉩니다.

    bq load \
    --source_format=ORC \
    --time_partitioning_field mytimestamp \
    mydataset.mytable \
    gs://mybucket/mydata.orc

다음 명령어는 gs://mybucket/에 있는 여러 파일에서 mydataset에 있는 mytable이라는 테이블로 데이터를 로드합니다. Cloud Storage URI는 와일드 카드를 사용합니다.

    bq load \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata*.orc

다음 명령어는 gs://mybucket/에 있는 여러 파일에서 mydataset에 있는 mytable이라는 테이블로 데이터를 로드합니다. 명령어에는 와일드 카드를 사용하는 쉼표로 구분된 Cloud Storage URI 목록이 포함됩니다.

    bq load --autodetect \
    --source_format=ORC \
    mydataset.mytable \
    "gs://mybucket/00/*.orc","gs://mybucket/01/*.orc"

API

1. Cloud Storage의 소스 데이터를 가리키는 load 작업을 만듭니다.

2. (선택사항) 작업 리소스의 jobReference 섹션에 있는 location 속성에 사용자 위치를 지정합니다.

3. source URIs 속성은 gs://bucket/object 형식으로 정규화되어야 합니다. 각 URI는 '*' 와일드 카드 문자 하나를 포함할 수 있습니다.

4. sourceFormat 속성을 ORC으로 설정하여 ORC 데이터 형식을 지정합니다.

5. 작업 상태를 확인하려면 jobs.get(job_id*)를 호출합니다. 여기서 job_id는 초기 요청에서 반환 된 작업의 ID입니다.

   • status.state = DONE이면 작업이 성공적으로 완료된 것입니다.
   • status.errorResult 속성이 있으면 요청이 실패한 것이며, 해당 객체에 무엇이 잘못되었는지 설명하는 정보가 포함됩니다. 요청이 실패하면 테이블이 생성되지 않고 데이터가 로드되지 않습니다.
   • status.errorResult가 없으면 작업은 성공적으로 완료되었지만 일부 행 가져오기 문제와 같은 심각하지 않은 오류가 발생했을 수 있다는 의미입니다. 심각하지 않은 오류는 반환된 작업 객체의 status.errors 속성에 나열됩니다.

API 참고:

• 로드 작업은 원자적이며 일관적입니다. 로드 작업이 실패하면 어떤 데이터도 사용할 수 없으며, 로드 작업이 성공하면 모든 데이터를 사용할 수 있습니다.

• jobs.insert를 호출하여 로드 작업을 만들 때는 고유 ID를 생성하여 jobReference.jobId로 전달하는 것이 가장 좋습니다. 클라이언트가 알려진 작업 ID로 폴링하거나 재시도할 수 있으므로 이 방법은 네트워크 장애 시에 더욱 안정적입니다.

• 특정 작업 ID에 대한 jobs.insert 호출은 멱등성을 가집니다. 동일한 작업 ID에 대해 원하는 만큼 재시도할 수 있으며 이러한 작업 중 최대 하나가 성공하게 됩니다.

C#

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

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

using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsOrc
{
    public void LoadTableGcsOrc(
        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.orc";
        var dataset = client.GetDataset(datasetId);
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.Orc
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI,
            destination: destinationTableRef,
            // Pass null as the schema because the schema is inferred when
            // loading Orc data
            schema: null,
            options: jobOptions
        );
        loadJob = loadJob.PollUntilCompleted().ThrowOnAnyError();  // 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}");
    }
}

Go

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

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

import (
	"context"
	"fmt"

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

// importORCTruncate demonstrates loading Apache ORC data from Cloud Storage into a table.
func importORC(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()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.orc")
	gcsRef.SourceFormat = bigquery.ORC
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)

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

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

Java

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.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;

// Sample to load ORC data from Cloud Storage into a new BigQuery table
public class LoadOrcFromGCS {

  public static void runLoadOrcFromGCS() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    loadOrcFromGCS(datasetName, tableName, sourceUri, schema);
  }

  public static void loadOrcFromGCS(
      String datasetName, String tableName, String sourceUri, 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);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri, FormatOptions.orc())
              .setSchema(schema)
              .build();

      // Load data from a GCS ORC file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone() && job.getStatus().getError() == null) {
        System.out.println("ORC from GCS successfully added during load append job");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

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

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

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

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the ORC file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.orc
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.orc';

async function loadTableGCSORC() {
  // Imports a GCS file into a table with ORC source format.

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

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'ORC',
    location: 'US',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);

  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

PHP

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

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

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

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

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table('us_states');

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.orc';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('ORC');
$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . 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 table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

job_config = bigquery.LoadJobConfig(source_format=bigquery.SourceFormat.ORC)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

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

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

Ruby

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

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

require "google/cloud/bigquery"

def load_table_gcs_orc dataset_id = "your_dataset_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"
  table_id = "us_states"

  load_job = dataset.load_job table_id, gcs_uri, format: "orc"
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done! # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table table_id
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

ORC 데이터로 테이블 데이터 추가 또는 덮어쓰기

소스 파일에서 또는 쿼리 결과를 추가하여 테이블에 추가 데이터를 로드할 수 있습니다.

Google Cloud 콘솔에서 쓰기 환경설정 옵션을 사용하여 소스 파일 또는 쿼리 결과에서 데이터를 로드할 때 수행할 작업을 지정합니다.

추가 데이터를 테이블에 로드할 때 다음 옵션을 사용할 수 있습니다.

콘솔 옵션	bq 도구 플래그	BigQuery API 속성	설명
비어 있으면 쓰기	지원되지 않음	WRITE_EMPTY	테이블이 비어 있는 경우에만 데이터를 씁니다.
테이블에 추가	--noreplace 또는 --replace=false. --[no]replace를 지정하지 않으면 기본값은 추가임	WRITE_APPEND	(기본값) 데이터를 테이블 끝에 추가합니다.
테이블 덮어쓰기	--replace 또는 --replace=true	WRITE_TRUNCATE	새 데이터를 쓰기 전에 테이블의 기존 데이터를 모두 지웁니다. 이 작업은 테이블 스키마, 행 수준 보안을 삭제하고 Cloud KMS 키도 삭제합니다.

기존 테이블에 데이터를 로드하는 경우 로드 작업에서 데이터를 추가하거나 테이블을 덮어쓸 수 있습니다.

다음을 통해 테이블을 추가하거나 덮어쓸 수 있습니다.

• Google Cloud 콘솔 사용
• bq 명령줄 도구의 bq load 명령어 사용
• jobs.insert API 메서드 호출 및 load 작업 구성
• 클라이언트 라이브러리 사용

참고: 이 페이지에서는 파티션을 나눈 테이블 추가 또는 덮어쓰기에 대해서는 다루지 않습니다. 파티션을 나눈 테이블을 추가하고 덮어쓰는 방법은 파티션을 나눈 테이블 데이터 추가 및 덮어쓰기를 참조하세요.

ORC 데이터가 있는 테이블을 추가하거나 덮어쓰려면 다음 안내를 따르세요.

콘솔

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

   BigQuery로 이동

2. 탐색기 창에서 프로젝트를 펼친 후 데이터 세트를 선택합니다.
3. 데이터 세트 정보 섹션에서 테이블 만들기를 클릭합니다.
4. 테이블 만들기 패널에서 다음 세부정보를 지정합니다.
1. 소스 섹션의 다음 항목으로 테이블 만들기 목록에서 Google Cloud Storage를 선택합니다. 그런 후 다음 작업을 수행합니다.
   1. Cloud Storage 버킷에서 파일을 선택하거나 Cloud Storage URI를 입력합니다. Google Cloud 콘솔에서는 URI를 여러 개 포함할 수 없지만 와일드 카드는 지원됩니다. Cloud Storage 버킷은 생성, 추가 또는 덮어쓰려는 테이블이 포함된 데이터 세트와 동일한 위치에 있어야 합니다.
   2. 파일 형식으로 ORC를 선택합니다.
참고: 테이블을 추가하거나 덮어쓸 때 해당 테이블 스키마를 수정할 수 있습니다. 로드 작업 시 지원되는 스키마 변경에 대한 자세한 내용은 테이블 스키마 수정을 참조하세요.
2. 대상 섹션에서 다음 세부정보를 지정합니다.
   1. 데이터 세트에서 테이블을 만들 데이터 세트를 선택합니다.
   2. 테이블 필드에 만들려는 테이블의 이름을 입력합니다.
   3. 테이블 유형 필드가 기본 테이블로 설정되어 있는지 확인합니다.
3. 스키마 섹션은 그대로 놔둡니다. 스키마는 ORC 파일에 자체 기술됩니다.
참고: 테이블을 추가하거나 덮어쓸 때 해당 테이블 스키마를 수정할 수 있습니다. 로드 작업 시 지원되는 스키마 변경에 대한 자세한 내용은 테이블 스키마 수정을 참조하세요.
4. 선택사항: 파티션 및 클러스터 설정을 지정합니다. 자세한 내용은 파티션을 나눈 테이블 만들기 및 클러스터링된 테이블 만들기 및 사용을 참조하세요. 추가하거나 덮어쓰는 방법으로 파티션을 나눈 테이블 또는 클러스터링된 테이블로 변환할 수 없습니다. Google Cloud 콘솔은 로드 작업에서 파티션을 나눈 테이블 또는 클러스터링된 테이블 추가 또는 덮어쓰기를 지원하지 않습니다.
5. 고급 옵션을 클릭하고 다음을 수행합니다.
   • 쓰기 환경설정에서 테이블에 추가 또는 테이블 덮어쓰기를 선택합니다.
   • 테이블 스키마에 없는 행의 값을 무시하려면 알 수 없는 값을 선택합니다.
   • Cloud Key Management Service 키를 사용하려면 암호화에서 고객 관리 키를 클릭합니다. Google 관리 키 설정을 그대로 두면 BigQuery는 저장 데이터를 암호화합니다.
6. 테이블 만들기를 클릭합니다.

SQL

LOAD DATA DDL 문을 사용합니다. 다음 예시에서는 ORC 파일을 mytable 테이블에 추가합니다.

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

   BigQuery로 이동

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

   LOAD DATA INTO mydataset.mytable
   FROM FILES (
     format = 'ORC',
     uris = ['gs://bucket/path/file.orc']);

3. 실행을 클릭합니다.

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

bq

bq load 명령어를 --replace 플래그와 함께 입력하여 테이블을 덮어씁니다. --noreplace 플래그를 사용하여 데이터를 테이블에 추가합니다. 플래그를 지정하지 않으면 기본값은 데이터 추가입니다. --source_format 플래그를 입력하고 ORC로 설정합니다. ORC 스키마는 자체 설명적 소스 데이터로부터 자동으로 가져오므로 스키마 정의를 제공할 필요가 없습니다.

참고: 추가하거나 덮어쓸 때 테이블 스키마를 수정할 수 있습니다. 로드 작업 시 지원되는 스키마 변경에 대한 자세한 내용은 테이블 스키마 수정을 참조하세요.

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

이 외에 다음과 같은 선택적 플래그가 있습니다.

• --destination_kms_key: 테이블 데이터 암호화에 사용되는 Cloud KMS 키입니다.

bq --location=location load \
--[no]replace \
--source_format=format \
dataset.table \
path_to_source

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

• location은 사용자의 위치입니다. --location 플래그는 선택사항입니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.
• format은 ORC입니다.
• dataset는 기존 데이터 세트입니다.
• table은 데이터를 로드하는 테이블 이름입니다.
• path_to_source는 정규화된 Cloud Storage URI 또는 쉼표로 구분된 URI 목록이며 와일드 카드도 지원됩니다.

예시:

다음 명령어는 gs://mybucket/mydata.orc에서 데이터를 로드하고 mydataset에 있는 mytable이라는 테이블을 덮어씁니다.

    bq load \
    --replace \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

다음 명령어는 gs://mybucket/mydata.orc에서 데이터를 로드하고 mydataset에 있는 mytable이라는 테이블에 데이터를 추가합니다.

    bq load \
    --noreplace \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

bq 명령줄 도구를 사용하여 파티션을 나눈 테이블을 추가하고 덮어쓰는 방법에 대한 자세한 내용은 파티션을 나눈 테이블 데이터 추가 및 덮어쓰기를 참조하세요.

API

1. Cloud Storage의 소스 데이터를 가리키는 load 작업을 만듭니다.

2. (선택사항) 작업 리소스의 jobReference 섹션에 있는 location 속성에 사용자 위치를 지정합니다.

3. source URIs 속성은 gs://bucket/object 형식으로 정규화되어야 합니다. 여러 URI를 쉼표로 구분된 목록으로 포함할 수 있습니다. 와일드 카드도 지원됩니다.

4. configuration.load.sourceFormat 속성을 ORC로 설정하여 데이터 형식을 지정합니다.

5. configuration.load.writeDisposition 속성을 WRITE_TRUNCATE 또는 WRITE_APPEND로 설정하여 쓰기 환경설정을 지정합니다.

C#

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

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

using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsOrcTruncate
{
    public void LoadTableGcsOrcTruncate(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id",
        string tableId = "your_table_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.orc";
        var dataset = client.GetDataset(datasetId);
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.Orc,
            WriteDisposition = WriteDisposition.WriteTruncate
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI,
            destination: destinationTableRef,
            // Pass null as the schema because the schema is inferred when
            // loading Orc data
            schema: null, options: jobOptions);
        loadJob = loadJob.PollUntilCompleted().ThrowOnAnyError();  // 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}");
    }
}

Go

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

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

import (
	"context"
	"fmt"

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

// importORCTruncate demonstrates loading Apache ORC data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importORCTruncate(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()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.orc")
	gcsRef.SourceFormat = bigquery.ORC
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	// Default for import jobs is to append data to a table.  WriteTruncate
	// specifies that existing data should instead be replaced/overwritten.
	loader.WriteDisposition = bigquery.WriteTruncate

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

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

Java

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to overwrite the BigQuery table data by loading a ORC file from GCS
public class LoadOrcFromGcsTruncate {

  public static void runLoadOrcFromGcsTruncate() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc";
    loadOrcFromGcsTruncate(datasetName, tableName, sourceUri);
  }

  public static void loadOrcFromGcsTruncate(
      String datasetName, String tableName, String sourceUri) {
    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);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.orc())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(JobInfo.WriteDisposition.WRITE_TRUNCATE)
              .build();

      // Load data from a GCS ORC file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone() && job.getStatus().getError() == null) {
        System.out.println("Table is successfully overwritten by ORC file loaded from GCS");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

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

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

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

// Instantiate the clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.orc';

async function loadORCFromGCSTruncate() {
  /**
   * Imports a GCS file into a table and overwrites
   * table data if table already exists.
   */

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

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'ORC',
    // Set the write disposition to overwrite existing table data.
    writeDisposition: 'WRITE_TRUNCATE',
    location: 'US',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);
  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

PHP

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

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

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

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

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$table = $bigQuery->dataset($datasetId)->table($tableId);

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.orc';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('ORC')->writeDisposition('WRITE_TRUNCATE');
$job = $table->runJob($loadConfig);

// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});

// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

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

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

기존 테이블의 행을 바꾸려면 LoadJobConfig.write_disposition 속성을 WRITE_TRUNCATE로 설정합니다.

import io

from google.cloud import bigquery

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

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

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
)

body = io.BytesIO(b"Washington,WA")
client.load_table_from_file(body, table_id, job_config=job_config).result()
previous_rows = client.get_table(table_id).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig(
    write_disposition=bigquery.WriteDisposition.WRITE_TRUNCATE,
    source_format=bigquery.SourceFormat.ORC,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"
load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

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

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

Ruby

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

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

require "google/cloud/bigquery"

def load_table_gcs_orc_truncate dataset_id = "your_dataset_id",
                                table_id   = "your_table_id"

  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"

  load_job = dataset.load_job table_id,
                              gcs_uri,
                              format: "orc",
                              write:  "truncate"
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done! # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table table_id
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

Hive 파티션을 나눈 ORC 데이터 로드

BigQuery는 Cloud Storage에 저장되는 Hive 파티션을 나눈 ORC 데이터 로드를 지원하고, Hive 파티션 열을 대상 BigQuery 관리 테이블의 열로 채웁니다. 자세한 내용은 외부에서 파티션을 나눈 Cloud Storage 데이터 로드를 참조하세요.

ORC 변환

BigQuery는 ORC 데이터 유형을 다음 BigQuery 데이터 유형으로 변환합니다.

기본 유형

ORC 데이터 유형	BigQuery 데이터 유형	참고
boolean	BOOLEAN
byte	INTEGER
short	INTEGER
int	INTEGER
long	INTEGER
float	FLOAT
double	FLOAT
string	STRING	UTF-8 전용
varchar	STRING	UTF-8 전용
char	STRING	UTF-8 전용
binary	BYTES
date	DATE	ORC 데이터에서 -719162일 미만이거나 2932896일보다 큰 값을 변환하려고 하면 invalid date value 오류가 반환됩니다. 이에 영향을 받는 경우 지원팀에 문의하여 지원되지 않는 값을 BigQuery 최솟값 0001-01-01 또는 최댓값 9999-12-31로 적절하게 변환하세요.
timestamp	TIMESTAMP	ORC는 나노초 정밀도를 지원하지만 BigQuery는 데이터를 읽을 때 1마이크로초 미만의 값을 마이크로초로 변환합니다. ORC 데이터에서 -719162일 미만이거나 2932896일보다 큰 값을 변환하려고 하면 invalid date value 오류가 반환됩니다. 이에 영향을 받는 경우 지원팀에 문의하여 지원되지 않는 값을 BigQuery 최솟값 0001-01-01 또는 최댓값 9999-12-31로 적절하게 변환합니다.
decimal	NUMERIC, BIGNUMERIC, STRING	십진수 유형을 참조하세요.

십진수 유형

Decimal 논리 유형은 NUMERIC, BIGNUMERIC, STRING 유형으로 변환할 수 있습니다. 변환된 유형은 decimal 논리 유형 및 지정된 십진수 대상 유형의 정밀도 및 확장 매개변수에 따라 다릅니다. 십진수 대상 유형을 다음과 같이 지정합니다.

• jobs.insert API를 사용하는 로드 작업의 경우: JobConfigurationLoad.decimalTargetTypes 필드를 사용합니다.
• bq 명령줄 도구의 bq load 명령어를 사용하는 로드 작업의 경우: --decimal_target_types 플래그를 사용합니다.
• 외부 소스가 있는 테이블에 대한 쿼리의 경우: ExternalDataConfiguration.decimalTargetTypes 필드를 사용합니다.
• DDL로 생성된 영구 외부 테이블의 경우: decimal_target_types 옵션을 사용합니다.

복합 유형

ORC 데이터 유형	BigQuery 데이터 유형	참고
struct	RECORD	모든 필드는 NULLABLE입니다. 필드의 순서는 무시됩니다. 필드 이름은 유효한 열 이름이어야 합니다.
map<K,V>	RECORD	ORC map<K,V> 필드는 K와 V의 두 가지 필드를 포함하는 반복 RECORD 변환됩니다. K는 동일한 데이터 유형의 키이고 V는 동일한 데이터 유형의 값입니다. 두 필드 모두 NULLABLE입니다.
list	반복 필드	중첩 목록과 map 목록은 지원되지 않습니다.
union	RECORD	union에 변형이 하나뿐이라면 NULLABLE 필드로 변환됩니다. 그렇지 않으면 union은 NULLABLE 필드의 목록이 있는 RECORD로 변환됩니다. NULLABLE 필드에는 field_0, field_1 등과 같은 서픽스가 있습니다. 데이터를 읽을 때는 이러한 필드 중 하나에만 값이 할당됩니다.

열 이름

열 이름은 문자(a~z, A~Z), 숫자(0~9) 또는 밑줄(_)을 포함할 수 있으며 문자나 밑줄로 시작해야 합니다. 유연한 열 이름을 사용하는 경우 BigQuery는 숫자로 열 이름을 시작할 수 있습니다. BigQuery Storage Read API 또는 BigQuery Storage Write API에서 유연한 열 이름을 사용하면 특별한 처리가 필요하므로 숫자로 열을 시작할 때 주의해야 합니다. 유연한 열 이름 지원에 대한 자세한 내용은 유연한 열 이름을 참조하세요.

열 이름 최대 길이는 300자(영문 기준)입니다. 열 이름에 다음과 같은 프리픽스를 사용할 수 없습니다.

• _TABLE_
• _FILE_
• _PARTITION
• _ROW_TIMESTAMP
• __ROOT__
• _COLIDENTIFIER

중복 열 이름은 대소문자가 다르더라도 허용되지 않습니다. 예를 들어 Column1 열과 column1 열은 동일하다고 간주됩니다. 열 이름 지정 규칙에 대한 자세한 내용은 GoogleSQL 참조의 열 이름을 참조하세요.

테이블 이름(예: test)이 열 이름 중 하나와 동일한 경우(예: test) SELECT 표현식은 test 열을 다른 모든 테이블 열이 포함된 STRUCT로 해석합니다. 이러한 충돌을 방지하려면 다음 방법 중 하나를 사용합니다.

• 테이블과 테이블 열에 동일한 이름을 사용해서는 안 됩니다.

• 테이블에 다른 별칭을 할당합니다. 예를 들어 다음 쿼리는 테이블 별칭 t를 project1.dataset.test 테이블에 할당합니다.

  SELECT test FROM project1.dataset.test AS t;
  

• 열을 참조할 때 테이블 이름을 포함합니다. 예를 들면 다음과 같습니다.

  SELECT test.test FROM project1.dataset.test;
  

유연한 열 이름

미리보기

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

영어 외 언어의 문자와 추가 기호에 대한 확장된 액세스를 포함하여 더욱 유연하게 열 이름을 지정할 수 있습니다.

유연한 열 이름은 다음 문자를 지원합니다.

• 유니코드 정규 표현식 \p{L}로 표현되는 모든 언어의 문자
• 유니코드 정규 표현식 \p{N}로 표현되는 모든 언어의 숫자
• 유니코드 정규 표현식 \p{Pc}로 표현되는 밑줄을 포함한 모든 커넥터 구두점 문자
• 유니코드 정규 표현식 \p{Pd}로 표현되는 하이픈 또는 대시
• 유니코드 정규 표현식 \p{M}로 표현되는 다른 문자를 포함하기 위한 표시 (예: 악센트, 움라우트 또는 바깥쪽 상자)
• 다음과 같은 특수문자가 지원됩니다.
  • 유니코드 정규 표현식 \u0026으로 표현되는 앰퍼샌드(&)
  • 유니코드 정규 표현식 \u0025로 표현되는 퍼센트 기호(%)
  • 유니코드 정규 표현식 \u003D로 표현되는 등호(=)
  • 유니코드 정규 표현식 \u002B로 표현되는 더하기 기호(+)
  • 유니코드 정규 표현식 \u003A로 표현되는 콜론(:)
  • 유니코드 정규 표현식 \u0027로 표현되는 아포스트로피(')
  • 유니코드 정규 표현식 \u003C로 표현되는 미만 기호(<)
  • 유니코드 정규 표현식 \u003E로 표현되는 초과 기호(>)
  • 유니코드 정규 표현식 \u0023으로 표현되는 숫자 기호(#)
  • 유니코드 정규 표현식 \u007c로 표현되는 세로 선(|)
  • 공백.

유연한 열 이름은 다음과 같은 특수문자를 지원하지 않습니다.

• 유니코드 정규 표현식 \u0021로 표현되는 느낌표(!)
• 유니코드 정규 표현식 \u0022로 표현되는 따옴표(")
• 유니코드 정규 표현식 \u0024로 표현되는 달러 기호($)
• 유니코드 정규 표현식 \u0028로 표현되는 왼쪽 괄호(()
• 유니코드 정규 표현식 \u0029로 표현되는 오른쪽 괄호())
• 유니코드 정규 표현식 \u002A로 표현되는 별표(*)
• 유니코드 정규 표현식 \u002C로 표현되는 쉼표(,)
• 유니코드 정규 표현식 \u002E로 표현되는 마침표(.)
• 유니코드 정규 표현식 \u002F로 표현되는 슬래시(/)
• 유니코드 정규 표현식 \u003B로 표현되는 세미콜론(;)
• 유니코드 정규 표현식 \u003F로 표현되는 물음표(?)
• 유니코드 정규 표현식 \u0040으로 표현되는 at 기호(@)
• 유니코드 정규 표현식 \u005B로 표현되는 왼쪽 대괄호([)
• 유니코드 정규 표현식 \u005C로 표현되는 백슬래시(\)
• 유니코드 정규 표현식 \u005D로 표현되는 오른쪽 대괄호(])
• 유니코드 정규 표현식 \u005E로 표현되는 곡절 악센트(^)
• 유니코드 정규 표현식 \u0060으로 표현되는 강세 부호(`)
• 유니코드 정규 표현식 \u007B로 표현되는 왼쪽 중괄호({)
• 유니코드 정규 표현식 \u007D로 표현되는 오른쪽 중괄호(})
• 유니코드 정규 표현식 \u007E로 표현되는 물결표(~)

추가 가이드라인은 열 이름을 참조하세요.

확장된 열 문자는 BigQuery Storage Read API와 BigQuery Storage Write API 모두에서 지원됩니다. BigQuery Storage Read API에서 확장된 유니코드 문자 목록을 사용하려면 플래그를 설정해야 합니다. displayName 속성을 사용하여 열 이름을 가져올 수 있습니다. 다음 예시에서는 Python 클라이언트에서 플래그를 설정하는 방법을 보여줍니다.

from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()

#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options

BigQuery Storage Write API에서 확장된 유니코드 문자 목록을 사용하려면 JsonStreamWriter 작성자 객체를 사용하지 않는 한 column_name 표기법으로 스키마를 제공해야 합니다. 다음 예시에서는 스키마를 제공하는 방법을 보여줍니다.

syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";

message FlexibleSchema {
  optional string item_name_column = 1
  [(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
  optional string item_description_column = 2
  [(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}

이 예시에서 item_name_column 및 item_description_column은 프로토콜 버퍼의 이름 지정 규칙을 준수해야 하는 자리표시자 이름입니다. column_name 주석은 항상 자리표시자 이름보다 우선 적용됩니다.

• Parquet 데이터 로드는 기본적으로 유연한 열 이름을 지원하지 않습니다. 이 미리보기에 등록하려면 등록 양식을 작성하세요. 미리보기에 등록한 후 잘못된 열 이름(예: 열 이름 콜레이션)이 있으면 오류가 반환됩니다. 등록되지 않은 프로젝트의 경우 로드 요청에서 오류를 반환하는 대신 잘못된 문자를 밑줄로 바꿉니다.
• 스키마 자동 감지를 사용한 CSV 데이터 로드에서는 기본적으로 유연한 열 이름을 지원하지 않습니다. 이 미리보기에 등록하려면 등록 양식을 작성하세요. 미리보기에 등록한 후 잘못된 열 이름(예: 열 이름 콜레이션)이 있으면 오류가 반환됩니다. 등록되지 않은 프로젝트의 경우 로드 요청에서 오류를 반환하는 대신 잘못된 문자를 밑줄로 바꿉니다.

외부 테이블에서는 유연한 열 이름이 지원되지 않습니다.

NULL 값

로드 작업에서 BigQuery는 list 복합 유형의 NULL 요소를 무시합니다. 그렇지 않으면 이러한 요소가 테이블로 지속될 수 없는 NULL ARRAY 요소로 변환되기 때문입니다. 자세한 내용은 데이터 유형을 참조하세요.

ORC 데이터 유형에 대한 자세한 내용은 Apache ORC™ 사양 v1을 참조하세요.