데이터 일괄 로드

Cloud Storage 또는 로컬 파일에서 BigQuery에 데이터를 일괄 작업으로 로드할 수 있습니다. 소스 데이터는 다음 형식 중 하나일 수 있습니다.

  • Avro
  • 쉼표로 구분된 값(CSV)
  • JSON(줄바꿈으로 구분)
  • ORC
  • Parquet
  • Cloud Storage에 저장된 Firestore 내보내기

BigQuery Data Transfer Service를 사용하여 Cloud Storage에서 BigQuery로 반복되는 로드를 설정할 수도 있습니다.

직접 사용해 보기

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

BigQuery 무료로 사용해 보기

시작하기 전에

이 문서의 각 태스크를 수행하는 데 필요한 권한을 사용자에게 제공하는 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 데이터세트를 만듭니다.

Cloud Storage에서 데이터 로드

BigQuery는 다음 Cloud Storage 저장소 등급에서 데이터 로드를 지원합니다.

  • Standard
  • Nearline
  • Coldline
  • Archive

BigQuery에 데이터를 로드하는 방법은 다음 데이터 형식 페이지를 참조하세요.

Cloud Storage에서 BigQuery로 로드를 반복하는 방법을 알아보려면 Cloud Storage 전송을 참조하세요.

위치 고려사항

BigLake 또는 BigLake 외의 외부 테이블을 사용하여 Cloud Storage에서 데이터를 로드할 때 로드하는 데이터는 BigQuery 데이터 세트와 같은 위치에 있어야 합니다.

  • BigQuery 데이터 세트가 US 멀티 리전에 있으면 모든 위치에 있는 Cloud Storage 버킷에서 데이터를 로드할 수 있습니다.'

  • 멀티 리전 버킷: 로드하려는 Cloud Storage 버킷이 멀티 리전 버킷에 있으면 BigQuery 데이터 세트는 같은 멀티 리전이나 같은 멀티 리전 버킷에 포함된 단일 리전 버킷에 있을 수 있습니다. 예를 들어 Cloud Storage 버킷이 EU 리전에 있으면 BigQuery 데이터 세트는 EU 멀티 리전이나 EU의 단일 리전에 있을 수 있습니다.

  • 이중 리전 버킷: 로드하려는 Cloud Storage 버킷이 이중 리전 버킷에 있으면 BigQuery 데이터 세트는 이중 리전 버킷에 포함된 리전이나 이중 리전이 포함된 멀티 리전에 있을 수 있습니다. 예를 들어 Cloud Storage 버킷이 EUR4 리전에 있으면 BigQuery 데이터 세트는 핀란드(europe-north1) 단일 리전, 네덜란드(europe-west4) 단일 리전 또는 EU 멀티 리전 중 하나에 있을 수 있습니다.

    자세한 내용은 이중 리전 버킷 만들기를 참조하세요.

  • 단일 리전 버킷: 로드하려는 Cloud Storage 버킷이 단일 리전에 있으면 BigQuery 데이터 세트는 같은 단일 리전이나 단일 리전이 포함된 멀티 리전에 있을 수 있습니다. 예를 들어 Cloud Storage 버킷이 핀란드(europe-north1) 리전에 있으면 BigQuery 데이터 세트는 핀란드 또는 EU 멀티 리전에 있을 수 있습니다.

  • 한 가지 예외는 BigQuery 데이터 세트가 asia-northeast1 리전에 있는 경우 Cloud Storage 버킷이 EU 멀티 리전에 있을 수 있다는 점입니다.

Cloud Storage 위치에 대한 자세한 내용은 Cloud Storage 문서의 버킷 위치를 참조하세요.

데이터 세트가 생성된 후에는 데이터 세트 위치를 변경할 수 없지만 데이터 세트를 복사하거나 수동으로 이동할 수 있습니다. 자세한 내용은 다음을 참조하세요.

Cloud Storage URI 검색

Cloud Storage 데이터 소스에서 데이터를 로드하려면 Cloud Storage URI를 제공해야 합니다.

Cloud Storage 리소스 경로에는 버킷 이름과 객체(파일 이름)가 포함됩니다. 예를 들어 Cloud Storage 버킷 이름이 mybucket이고 데이터 파일 이름이 myfile.csv라면 리소스 경로는 gs://mybucket/myfile.csv가 됩니다.

BigQuery는 처음 이중 슬래시 다음에 슬래시 여러 개가 연속으로 포함된 Cloud Storage 리소스 경로를 지원하지 않습니다. Cloud Storage 객체 이름에는 연속된 슬래시('/') 문자 여러 개가 포함될 수 있습니다. 하지만 BigQuery는 연속된 슬래시 여러 개를 단일 슬래시로 변환합니다. 예를 들어 gs://bucket/my//object//name 리소스 경로는 Cloud Storage에서는 유효하지만 BigQuery에서는 작동하지 않습니다.

Cloud Storage 리소스 경로를 검색하려면 다음 안내를 따르세요.

  1. Cloud Storage 콘솔을 엽니다.

    Cloud Storage 콘솔

  2. 소스 데이터가 포함된 객체(파일) 위치로 이동합니다.

  3. 객체의 이름을 클릭합니다.

    객체 세부정보 페이지가 열립니다.

  4. gsutil URI 필드에 제공된 값(gs://로 시작)을 복사합니다.

Google Datastore 내보내기의 경우 URI를 하나만 지정할 수 있으며 .backup_info 또는 .export_metadata로 끝나야 합니다.

Cloud Storage URI의 와일드 카드 지원

데이터가 여러 개의 파일로 분리되어 있는 경우 별표(*) 와일드 카드를 사용하여 여러 파일을 선택할 수 있습니다. 별표 와일드 카드를 사용하려면 다음 규칙을 따라야 합니다.

  • 와일드 카드는 객체 이름 중간이나 끝에 입력할 수 있습니다.
  • 별표 여러 개를 사용하는 것은 지원되지 않습니다. 예를 들어 gs://mybucket/fed-*/temp/*.csv 경로는 유효하지 않습니다.
  • 버킷 이름에 별표를 사용하는 것은 지원되지 않습니다.

예시:

  • 다음 예시에서는 프리픽스 gs://mybucket/fed-samples/fed-sample로 시작하는 모든 폴더의 모든 파일을 선택하는 방법을 보여줍니다.

    gs://mybucket/fed-samples/fed-sample*

  • 다음 예시에서는 fed-samples라는 폴더와 fed-samples의 모든 하위 폴더에 있는 .csv 확장자가 있는 파일만 선택하는 방법을 보여줍니다.

    gs://mybucket/fed-samples/*.csv

  • 다음 예시에서는 fed-samples라는 폴더에 있는 이름 지정 패턴이 fed-sample*.csv인 파일을 선택하는 방법을 보여줍니다. 이 예시에서는 fed-samples 하위 폴더에 있는 파일을 선택하지 않습니다.

    gs://mybucket/fed-samples/fed-sample*.csv

bq 명령줄 도구를 사용할 때 일부 플랫폼에서 별표를 이스케이프 처리해야 할 수도 있습니다.

Cloud Storage에서 Datastore 또는 Firestore 내보내기 데이터를 로드할 때는 별표 와일드 카드를 사용할 수 없습니다.

제한사항

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

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

Cloud Storage 소스 데이터의 형식에 따라 추가 제한사항이 적용될 수 있습니다. 자세한 내용은 다음을 참조하세요.

로컬 파일에서 데이터 로드

다음 중 하나를 사용하여 읽을 수 있는 데이터 소스(예: 로컬 머신)에서 데이터를 로드할 수 있습니다.

  • Google Cloud 콘솔
  • bq 명령줄 도구의 bq load 명령어
  • API
  • 클라이언트 라이브러리

Google Cloud 콘솔 또는 bq 명령줄 도구를 사용하여 데이터를 로드하면 로드 작업이 자동으로 생성됩니다.

로컬 데이터 소스에서 데이터를 로드하는 방법:

Console

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

    BigQuery 페이지로 이동

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

  3. 작업 옵션을 펼치고 열기를 클릭합니다.

  4. 세부정보 패널에서 테이블 만들기를 클릭합니다.

  5. 테이블 만들기 페이지의 소스 섹션에서 다음을 수행합니다.

    • 다음 항목으로 테이블 만들기에서 업로드를 선택합니다.
    • 파일 선택에서 찾아보기를 클릭합니다.
    • 파일을 찾은 후 열기를 클릭합니다. 로컬 파일에서는 와일드 카드와 쉼표로 구분된 목록이 지원되지 않습니다.
    • 파일 형식에서 CSV, JSON(줄바꿈으로 구분), Avro, Parquet 또는 ORC를 선택합니다.

  6. 테이블 만들기 페이지의 대상 섹션에서 다음을 수행합니다.

    • 프로젝트에서 적절한 프로젝트를 선택합니다.
    • 데이터 세트에서 적절한 데이터 세트를 선택합니다.
    • 테이블 필드에 BigQuery에 만들려는 테이블의 이름을 입력합니다.
    • 테이블 유형이 기본 테이블로 설정되어 있는지 확인합니다.

  7. 스키마 섹션에 스키마 정의를 입력합니다.

    • CSV 및 JSON 파일의 경우 자동 감지 옵션을 선택하여 스키마 자동 감지를 사용 설정할 수 있습니다. 다른 지원되는 파일 유형의 경우 스키마 정보는 소스 데이터에서 자체 기술됩니다.

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

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

      • 필드 추가를 사용하여 스키마를 직접 입력합니다.

  8. 고급 옵션 섹션에서 해당 항목을 선택합니다. 사용 가능한 옵션에 대한 자세한 내용은 CSV 옵션과 JSON 옵션을 참조하세요.

  9. 선택사항: 고급 옵션에서 쓰기 처리를 선택합니다.

    • 비어 있으면 쓰기: 테이블이 비어 있는 경우에만 데이터를 씁니다.
    • 테이블에 추가: 데이터를 테이블 끝에 추가합니다. 이 설정은 기본값입니다.
    • 테이블 덮어쓰기: 새 데이터를 쓰기 전에 테이블의 모든 기존 데이터를 삭제합니다.

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

bq

bq load 명령어를 사용하고 source_format을 지정하고 로컬 파일 경로를 포함합니다.

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

기본 프로젝트가 아닌 다른 프로젝트에 데이터를 로드하려면 프로젝트 ID를 PROJECT_ID:DATASET 형식으로 데이터 세트에 추가합니다.

bq --location=LOCATION load \
--source_format=FORMAT \
PROJECT_ID:DATASET.TABLE \
PATH_TO_SOURCE \
SCHEMA

다음을 바꿉니다.

  • LOCATION: 사용자 위치입니다. --location 플래그는 선택사항입니다. 예를 들어 도쿄 리전에서 BigQuery를 사용하는 경우 플래그 값을 asia-northeast1로 설정합니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.
  • FORMAT: CSV, AVRO, PARQUET, ORC, 또는 NEWLINE_DELIMITED_JSON.
  • project_id: 프로젝트 ID입니다.
  • dataset: 기존 데이터 세트입니다.
  • table: 데이터를 로드할 테이블의 이름입니다.
  • path_to_source: 로컬 파일의 경로입니다.
  • schema: 유효한 스키마입니다. 스키마는 로컬 JSON 파일일 수 있고 명령어의 일부로 인라인으로 입력할 수도 있습니다. 스키마 정의를 제공하는 대신 --autodetect 플래그를 사용해도 됩니다.

또한 BigQuery가 데이터를 파싱하는 방법을 제어할 수 있는 옵션에 플래그를 추가할 수 있습니다. 예를 들어 --skip_leading_rows 플래그를 사용하면 CSV 파일의 헤더 행을 무시할 수 있습니다. 자세한 내용은 CSV 옵션과 JSON 옵션을 참조하세요.

예시:

다음 명령어는 줄바꿈으로 구분된 JSON 파일(mydata.json)을 기본 프로젝트의 mydataset에 있는 mytable이라는 테이블에 로드합니다. 스키마는 myschema.json이라는 로컬 스키마 파일에 정의됩니다.

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    ./mydata.json \
    ./myschema.json

다음 명령어는 로컬 CSV 파일(mydata.csv)을 myotherproject의 mydataset에 있는 mytable이라는 테이블에 로드합니다. 스키마는 FIELD:DATA_TYPE, FIELD:DATA_TYPE 형식으로 인라인으로 정의됩니다.

    bq load \
    --source_format=CSV \
    myotherproject:mydataset.mytable \
    ./mydata.csv \
    qtr:STRING,sales:FLOAT,year:STRING

다음 명령어는 로컬 CSV 파일(mydata.csv)을 기본 프로젝트의 mydataset에 있는 mytable이라는 테이블에 로드합니다. 스키마는 스키마 자동 감지를 통해 정의됩니다.

    bq load \
    --autodetect \
    --source_format=CSV \
    mydataset.mytable \
    ./mydata.csv

C#

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

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

다음 코드는 로컬 CSV 파일을 새로운 BigQuery 테이블로 로드하는 방법을 보여줍니다. 다른 형식의 로컬 파일을 로드하려면 UploadCsvOptions 대신 JobCreationOptions 기본 클래스에서 적절한 형식의 업데이트 옵션 클래스를 사용합니다.


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

public class BigQueryLoadFromFile
{
    public void LoadFromFile(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id",
        string tableId = "your_table_id",
        string filePath = "path/to/file.csv"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Create job configuration
        var uploadCsvOptions = new UploadCsvOptions()
        {
            SkipLeadingRows = 1,  // Skips the file headers
            Autodetect = true
        };
        using (FileStream stream = File.Open(filePath, FileMode.Open))
        {
            // Create and run job
            // Note that there are methods available for formats other than CSV
            BigQueryJob job = client.UploadCsv(
                datasetId, tableId, null, stream, uploadCsvOptions);
            job = job.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.

            // Display the number of rows uploaded
            BigQueryTable table = client.GetTable(datasetId, tableId);
            Console.WriteLine(
                $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
        }
    }
}

Go

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

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

다음 코드는 로컬 CSV 파일을 새로운 BigQuery 테이블로 로드하는 방법을 보여줍니다. 다른 형식의 로컬 파일을 로드하려면 NewReaderSource의 DataFormat 속성을 적절한 형식으로 설정합니다.

import (
	"context"
	"fmt"
	"os"

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

// importCSVFromFile demonstrates loading data into a BigQuery table using a file on the local filesystem.
func importCSVFromFile(projectID, datasetID, tableID, filename 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()

	f, err := os.Open(filename)
	if err != nil {
		return err
	}
	source := bigquery.NewReaderSource(f)
	source.AutoDetect = true   // Allow BigQuery to determine schema.
	source.SkipLeadingRows = 1 // CSV has a single header line.

	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(source)

	job, err := loader.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
	}
	return nil
}

Java

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

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

다음 코드는 로컬 CSV 파일을 새로운 BigQuery 테이블로 로드하는 방법을 보여줍니다. 다른 형식의 로컬 파일을 로드하려면 FormatOptions를 적절한 형식으로 설정합니다.

TableId tableId = TableId.of(datasetName, tableName);
WriteChannelConfiguration writeChannelConfiguration =
    WriteChannelConfiguration.newBuilder(tableId).setFormatOptions(FormatOptions.csv()).build();
// The location must be specified; other fields can be auto-detected.
JobId jobId = JobId.newBuilder().setLocation(location).build();
TableDataWriteChannel writer = bigquery.writer(jobId, writeChannelConfiguration);
// Write data to writer
try (OutputStream stream = Channels.newOutputStream(writer)) {
  Files.copy(csvPath, stream);
}
// Get load job
Job job = writer.getJob();
job = job.waitFor();
LoadStatistics stats = job.getStatistics();
return stats.getOutputRows();

Node.js

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

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

다음 코드는 로컬 CSV 파일을 새로운 BigQuery 테이블로 로드하는 방법을 보여줍니다. 다른 형식의 로컬 파일을 로드하려면 load 함수의 metadata 매개변수를 적절한 형식으로 설정합니다.

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

async function loadLocalFile() {
  // Imports a local file into a table.

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

  // Load data from a local file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(filename);

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

다음 코드는 로컬 CSV 파일을 새로운 BigQuery 테이블로 로드하는 방법을 보여줍니다. 다른 형식의 로컬 파일을 로드하려면 sourceFormat을 적절한 형식으로 설정합니다.

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';
// $source     = 'The path to the CSV source file to import';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
// create the import job
$loadConfig = $table->load(fopen($source, 'r'))->sourceFormat('CSV');

$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    printf('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에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

다음 코드는 로컬 CSV 파일을 새로운 BigQuery 테이블로 로드하는 방법을 보여줍니다. 다른 형식의 로컬 파일을 로드하려면 LoadJobConfig.source_forma 속성을 적절한 형식으로 설정합니다.

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.CSV, skip_leading_rows=1, autodetect=True,
)

with open(file_path, "rb") as source_file:
    job = client.load_table_from_file(source_file, table_id, job_config=job_config)

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

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

Ruby

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

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

다음 코드는 로컬 CSV 파일을 새로운 BigQuery 테이블로 로드하는 방법을 보여줍니다. 다른 형식의 로컬 파일을 로드하려면 Table#load_job 메서드의 format 매개변수를 적절한 형식으로 설정합니다.

require "google/cloud/bigquery"

def load_from_file dataset_id = "your_dataset_id",
                   file_path  = "path/to/file.csv"

  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table_id = "new_table_id"

  # Infer the config.location based on the location of the referenced dataset.
  load_job = dataset.load_job table_id, file_path do |config|
    config.skip_leading = 1
    config.autodetect   = true
  end
  load_job.wait_until_done! # Waits for table load to complete.

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

제한사항

로컬 데이터 소스에서 데이터 로드 시 다음과 같은 제한사항이 적용됩니다.

  • 로컬 데이터 소스에서 파일 로드 시 와일드 카드와 쉼표로 구분된 목록이 지원되지 않습니다. 파일을 개별적으로 로드해야 합니다.
  • Google Cloud 콘솔을 사용할 때 로컬 데이터 소스에서 로드된 파일은 100MB를 초과할 수 없습니다. 더 큰 파일의 경우 Cloud Storage에서 파일을 로드합니다.

압축 및 비압축 데이터 로드

Avro, Parquet, ORC 형식의 경우 BigQuery는 지원되는 코덱을 사용하여 파일 데이터가 압축된 파일 로드를 지원합니다. 그러나 BigQuery는 예를 들어 gzip 유틸리티를 사용하여 자동으로 압축된 형식의 파일을 로드하는 것을 지원하지 않습니다.

압축 및 비압축 데이터를 로드하는 데 권장되는 형식은 Avro 바이너리 형식입니다. Avro 데이터는 데이터 블록이 압축된 경우에도 데이터를 병렬로 읽을 수 있으므로 더 빠르게 로드됩니다. 지원되는 압축 코덱 목록은 Avro 압축을 참조하세요.

또한 Parquet의 효율적인 열 단위 인코딩은 일반적으로 더 높은 압축 비율과 더 작은 파일 크기로 이어지므로 Parquet 바이너리 형식은 좋은 선택입니다. 또한 Parquet 파일은 파일을 병렬로 로드할 수 있는 압축 기술을 활용합니다. 지원되는 압축 코덱 목록은 Parquet 압축을 참조하세요.

ORC 바이너리 형식은 Parquet 형식과 비슷한 이점을 제공합니다. ORC 파일의 데이터는 데이터 스트라이프를 병렬로 읽을 수 있으므로 로드 속도가 빠릅니다. 각 데이터 스트라이프의 행은 순차적으로 로드됩니다. 로드 시간을 최적화하려면 약 256MB 이하의 데이터 스트라이프를 사용하세요. 지원되는 압축 코덱 목록은 ORC 압축을 참조하세요.

비압축 파일은 병렬로 읽을 수 있으므로 CSV 및 JSON과 같은 다른 데이터 형식의 경우 BigQuery는 압축 파일보다 비압축 파일을 훨씬 더 빠르게 로드할 수 있습니다. 비압축 파일은 용량이 더 크므로 비압축 파일 사용 시 대역폭 제한이 발생하거나 Cloud Storage에 준비된 데이터의 경우 BigQuery로 로드되기 전에 Cloud Storage 비용 상승을 유발할 수 있습니다. 압축된 파일이나 압축되지 않은 파일의 라인 정렬은 보장되지 않습니다. 사용 사례에 따라 이러한 장단점을 고려하는 것이 중요합니다.

일반적으로 대역폭이 제한된 경우 gzip을 사용하여 CSV 및 JSON 파일을 압축한 후 Cloud Storage에 업로드하세요. gzip은 BigQuery에 데이터를 로드할 때 CSV 및 JSON 파일에 지원되는 유일한 파일 압축 유형입니다. 앱의 로딩 속도가 중요하고 데이터를 로드할 대역폭이 풍부하다면 파일을 압축되지 않은 상태로 유지하세요.

테이블에 추가 또는 덮어쓰기

소스 파일에서 또는 쿼리 결과를 추가하여 테이블에 추가 데이터를 로드할 수 있습니다. 데이터의 스키마가 대상 테이블 또는 파티션의 스키마와 일치하지 않는다면 추가하거나 덮어쓸 때 스키마를 업데이트하면 됩니다.

데이터를 추가할 때 스키마를 업데이트하면 BigQuery에서 다음 작업을 처리할 수 있습니다.

  • 새 필드 추가
  • REQUIRED 필드를 NULLABLE로 완화

테이블을 덮어쓰면 스키마를 항상 덮어쓰게 됩니다. 테이블을 덮어쓸 때는 스키마 업데이트가 제한되지 않습니다.

Google Cloud 콘솔에서 쓰기 환경설정 옵션을 사용하여 소스 파일 또는 쿼리 결과에서 데이터를 로드할 때 수행할 작업을 지정합니다. bq 명령줄 도구와 API에는 다음 옵션이 포함되어 있습니다.

Console 옵션 bq 도구 플래그 BigQuery API 속성 설명
비어 있으면 쓰기 없음 WRITE_EMPTY 테이블이 비어 있는 경우에만 데이터를 씁니다.
테이블에 추가 --noreplace 또는 --replace=false. --replace를 지정하지 않으면 기본값은 추가임 WRITE_APPEND (기본값) 데이터를 테이블 끝에 추가합니다.
테이블 덮어쓰기 --replace 또는 --replace=true WRITE_TRUNCATE 새 데이터를 쓰기 전에 테이블의 기존 데이터를 모두 지웁니다.

할당량 정책

데이터 일괄 로드의 할당량 정책에 대한 자세한 내용은 할당량 및 한도 페이지의 로드 작업을 참조하세요.

현재 할당량 사용량 보기

INFORMATION_SCHEMA 쿼리를 실행하여 지정된 기간 동안 실행된 작업에 대한 메타데이터를 확인하여 쿼리, 로드, 추출, 복사 작업의 현재 사용량을 볼 수 있습니다. 현재 사용량을 할당량 한도와 비교하여 특정 유형 작업의 할당량 사용량을 결정할 수 있습니다. 다음 예시 쿼리는 INFORMATION_SCHEMA.JOBS 뷰를 사용하여 프로젝트별로 쿼리, 로드, 추출, 복사 작업 수를 나열합니다.

SELECT
  sum(case  when job_type="QUERY" then 1 else 0 end) as QRY_CNT,
  sum(case  when job_type="LOAD" then 1 else 0 end) as LOAD_CNT,
  sum(case  when job_type="EXTRACT" then 1 else 0 end) as EXT_CNT,
  sum(case  when job_type="COPY" then 1 else 0 end) as CPY_CNT
FROM `region-eu`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE date(creation_time)= CURRENT_DATE()

가격 책정

BigQuery로 데이터를 일괄 로드하는 데는 비용이 청구되지 않습니다. 자세한 내용은 BigQuery 데이터 수집 가격 책정을 참조하세요.

사용 사례

고정된 기한 내에 야간 일괄 처리 파이프라인을 완료해야 한다고 가정해 보겠습니다. 규제 기관에 전송할 보고서를 생성하려면 다른 일괄 프로세스에서의 추가 처리를 위해 이 기한까지 데이터를 사용할 수 있어야 합니다. 이 사용 사례는 금융과 같은 규제 대상 업계에서 일반적입니다.

기한을 충족할 수 있다면 지연 시간이 문제가 되지 않으므로 로드 작업을 사용한 데이터 일괄 로드가 이 사용 사례에 적합한 접근 방법입니다. Cloud Storage 버킷이 BigQuery 데이터 세트로 데이터를 로드하는 데 필요한 위치 요구사항을 충족하는지 확인합니다.

BigQuery 로드 작업 결과는 원자적입니다. 모든 레코드가 삽입되거나 아무것도 삽입되지 않습니다. 모든 데이터를 단일 로드 작업에 삽입할 때 JobConfigurationLoad 리소스의 WRITE_TRUNCATE 처리를 사용하여 새 테이블을 만드는 것이 좋습니다. 이는 실패한 로드 작업을 재시도할 때 중요합니다. 작업이 실패한 것인지 아니면 성공 상태를 클라이언트에 다시 전달하는 데 실패했는지 클라이언트에서 구분하지 못할 수 있기 때문입니다.

수집될 데이터가 Cloud Storage에 이미 복사되었다고 가정하면 지수 백오프를 재시도해도 수집 실패를 해결하는 데 충분합니다.

야간 일괄 작업은 재시도까지 포함하여 기본 할당량(테이블당 일일 로드 1,500회)에 도달하지 않는 것이 좋습니다. 데이터를 증분식으로 로드하는 경우 기본 할당량은 5분마다 로드 작업을 실행하기에 충분하며 작업당 평균 최소 한 번 이상 재시도할 수 있는 소비하지 않은 할당량이 여전히 존재합니다.