데이터 일괄 로드

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

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

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

직접 사용해 보기

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

BigQuery 무료로 사용해 보기

필수 권한

BigQuery에 데이터를 로드할 때는 로드 작업을 실행할 수 있는 권한과 새로 만들거나 기존에 있던 BigQuery 테이블 및 파티션에 데이터를 로드할 수 있는 권한이 필요합니다. Cloud Storage에서 데이터를 로드할 경우 데이터가 포함된 버킷에 대한 액세스 권한도 필요합니다.

BigQuery 권한

BigQuery에 데이터를 로드하려면 최소한 다음 권한이 필요합니다. 이들 권한은 새로운 테이블 또는 파티션에 데이터를 로드할 때나 테이블 또는 파티션을 추가하거나 덮어쓸 때 필요합니다.

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

다음과 같은 사전 정의된 IAM 역할에는 bigquery.tables.create 권한과 bigquery.tables.updateData 권한이 모두 포함되어 있습니다.

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

다음과 같은 사전 정의된 IAM 역할에는 bigquery.jobs.create 권한이 포함되어 있습니다.

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

또한 bigquery.datasets.create 권한이 있는 사용자는 데이터 세트를 만들 때 해당 데이터 세트에 대한 bigquery.dataOwner 액세스 권한을 부여받습니다. bigquery.dataOwner 액세스 권한이 있는 사용자는 로드 작업을 사용하여 데이터 세트에서 테이블을 만들고 업데이트할 수 있습니다.

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

Cloud Storage 권한

Cloud Storage 버킷에서 데이터를 로드하려면 storage.objects.get 권한을 부여받아야 합니다. URI 와일드 카드를 사용하는 경우에는 storage.objects.list 권한도 있어야 합니다.

사전 정의된 IAM 역할 storage.objectViewer가 부여되면 storage.objects.getstorage.objects.list 권한이 모두 제공됩니다.

Cloud Storage에서 데이터 로드

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

  • Standard
  • Nearline
  • Coldline
  • Archive

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

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

위치 고려사항

데이터 위치를 선택할 때는 다음 사항을 고려해야 합니다.

  • 데이터 로드용 Cloud Storage 버킷을 같은 위치에 배치합니다.
    • BigQuery 데이터세트가 멀티 리전 위치에 있는 경우 로드하는 데이터가 포함된 Cloud Storage 버킷은 같은 위치의 리전이나 멀티 리전 버킷에 있어야 합니다. 예를 들어 BigQuery 데이터세트가 EU에 있으면 Cloud Storage 버킷은 EU 내 리전 또는 멀티 리전 버킷에 있어야 합니다.
    • 데이터세트가 리전 위치에 있는 경우, Cloud Storage 버킷은 같은 위치의 리전 버킷에 있어야 합니다. 예를 들어 데이터세트가 도쿄 리전에 있으면 Cloud Storage 버킷은 도쿄 내 리전 버킷에 있어야 합니다.
    • 예외: 데이터세트가 US 멀티 리전 위치에 있는 경우 모든 리전 내 또는 멀티 리전 위치에 있는 Cloud Storage 버킷에서 데이터를 로드할 수 있습니다.
  • 데이터 관리 계획을 세웁니다.
    • BigQuery 데이터세트 또는 Cloud Storage 버킷과 같은 리전 내 스토리지 리소스를 선택한 경우 데이터를 지리적으로 관리하기 위한 계획을 세웁니다.

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

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

Cloud Storage URI 검색

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

Cloud Storage URI는 버킷 이름과 객체(파일 이름)로 구성됩니다. 예를 들어 Cloud Storage 버킷 이름이 mybucket이고 데이터 파일 이름이 myfile.csv라면 버킷 URI는 gs://mybucket/myfile.csv가 됩니다. 데이터가 여러 개의 파일로 분리되어 있으면 URI에 와일드 카드를 사용할 수 있습니다. 자세한 내용은 Cloud Storage 요청 URI를 참조하세요.

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

Cloud Storage URI를 가져오려면 다음 안내를 따르세요.

  1. Cloud Storage 콘솔을 엽니다.

    Cloud Storage Console

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

  3. Cloud Storage Console 맨 위에서 객체 경로를 확인합니다. URI를 만들기 위해 gs://bucket/file을 적절한 경로로 바꿉니다(예: gs://mybucket/myfile.json). bucket은 Cloud Storage 버킷 이름이고 file은 데이터가 포함된 객체(파일) 이름입니다.

Cloud Storage URI의 와일드 카드 지원

Cloud Storage 데이터가 공통된 기본 이름을 공유하는 여러 파일로 분리되어 있는 경우, 데이터를 로드할 때 URI에 와일드 카드를 사용할 수 있습니다.

Cloud Storage URI에 와일드 카드를 추가하려면 기본 이름에 별표(*)를 추가합니다. 예를 들어 fed-sample000001.csvfed-sample000002.csv라는 파일 두 개가 있다면 버킷 URI는 gs://mybucket/fed-sample*입니다. 그런 다음 Cloud Console, bq 명령줄 도구, API 또는 클라이언트 라이브러리에서 이 와일드 카드 URI를 사용할 수 있습니다.

와일드 카드는 버킷 내의 객체(파일 이름)에 하나만 사용할 수 있습니다. 와일드 카드는 객체 이름 중간이나 끝에 입력할 수 있습니다. 버킷 이름에는 와일드 카드를 추가할 수 없습니다.

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

다음과 같은 경우 별표 와일드 카드 문자가 허용되지 않습니다.

  • Datastore 또는 Firestore 내보내기에 연결된 외부 테이블을 만드는 경우
  • Cloud Storage에서 Datastore 또는 Firestore 내보내기 데이터를 로드하는 경우

제한사항

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

  • 데이터세트 위치가 US 이외의 값으로 설정된 경우 리전별 또는 멀티 리전 Cloud Storage 버킷이 데이터세트와 동일한 리전에 있어야 합니다.
  • BigQuery는 외부 데이터 소스의 데이터 일관성을 보장하지 않습니다. 쿼리가 실행되는 동안 기본 데이터가 변경되면 예상치 못한 동작이 발생할 수 있습니다.

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

로컬 파일에서 데이터 로드

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

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

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

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

Console

  1. Cloud Console에서 BigQuery 페이지를 엽니다.

    BigQuery 페이지로 이동

  2. 탐색 패널의 리소스 섹션에서 Google Cloud 프로젝트를 펼치고 데이터 세트를 선택합니다.

  3. 창의 오른쪽에 있는 세부정보 패널에서 테이블 만들기를 클릭합니다. 데이터를 로드하는 프로세스는 빈 테이블을 만드는 프로세스와 동일합니다.

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

    • 다음 항목으로 테이블 만들기에서 업로드를 선택합니다.

      테이블 업로드

    • 파일 선택 아래에 있는 찾아보기를 클릭합니다.

      파일 찾아보기

    • 파일을 찾은 후 열기를 클릭합니다. 로컬 파일에서는 와일드 카드와 쉼표로 구분된 목록이 지원되지 않습니다.

    • 파일 형식에서 CSV, JSON(줄바꿈으로 구분), Avro, Parquet 또는 ORC를 선택합니다.

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

    • 데이터 세트 이름에서 적절한 데이터 세트를 선택합니다.

      데이터 세트 보기

    • 테이블 이름 필드에 BigQuery에 만들려는 테이블의 이름을 입력합니다.

    • 테이블 유형기본 테이블로 설정되어 있는지 확인합니다.

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

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

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

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

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

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

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

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

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)을 myotherprojectmydataset에 있는 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 참조 문서를 확인하세요.

다음 코드는 로컬 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.PollUntilCompleted();  // 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 참조 문서를 확인하세요.

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

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
}

자바

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

다음 코드는 로컬 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 참조 문서를 확인하세요.

다음 코드는 로컬 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 참조 문서를 참조하세요.

다음 코드는 로컬 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 참조 문서를 확인하세요.

다음 코드는 로컬 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 참조 문서를 확인하세요.

다음 코드는 로컬 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

제한사항

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

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

압축 및 비압축 데이터 로드

압축 및 비압축 데이터를 로드하는 데 권장되는 형식은 Avro 바이너리 형식입니다. Avro 데이터는 데이터 블록이 압축된 경우에도 데이터를 병렬로 읽을 수 있으므로 더 빠르게 로드됩니다. 압축된 Avro 파일은 지원되지 않지만 압축된 데이터 블록은 지원됩니다. BigQuery는 Avro 파일의 압축된 데이터 블록에 DEFLATE 및 Snappy 코덱을 지원합니다.

또한 Parquet의 효율적인 열 단위 인코딩은 일반적으로 더 높은 압축 비율과 더 작은 파일 크기로 이어지므로 Parquet 바이너리 형식은 좋은 선택입니다. 또한 Parquet 파일은 파일을 병렬로 로드할 수 있는 압축 기술을 활용합니다. 압축된 Parquet 파일은 지원되지 않지만 압축된 데이터 블록은 지원됩니다. BigQuery는 Parquet 파일의 압축된 데이터 블록에 Snappy, GZip, and LZO_1X 코덱을 지원합니다.

ORC 바이너리 형식은 Parquet 형식과 비슷한 이점을 제공합니다. ORC 파일의 데이터는 데이터 스트라이프를 병렬로 읽을 수 있으므로 로드 속도가 빠릅니다. 각 데이터 스트라이프의 행은 순차적으로 로드됩니다. 로드 시간을 최적화하려면 약 256MB 이하의 데이터 스트라이프를 사용하세요. 압축된 ORC 파일은 지원되지 않지만 압축된 파일 바닥글과 스트라이프는 지원됩니다. BigQuery는 ORC 파일 바닥글 및 스트라이프에 Zlib, Snappy, LZO, LZ4 압축을 지원합니다.

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

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

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

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

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

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

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

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

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

할당량 정책

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

가격 책정

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