테이블 데이터 내보내기

이 페이지에서는 BigQuery 테이블에서 데이터를 내보내거나 추출하는 방법을 설명합니다.

데이터를 BigQuery에 로드한 후에 여러 가지 형식으로 데이터를 내보낼 수 있습니다. BigQuery는 최대 1GB의 데이터를 하나의 파일로 내보낼 수 있습니다. 1GB가 넘는 데이터를 내보내려면 데이터를 여러 파일로 내보내야 합니다. 데이터를 여러 파일로 내보내면 파일 크기가 달라집니다.

Dataflow와 같은 서비스를 사용하면 데이터를 수동으로 내보내지 않고 BigQuery에서 읽을 수 있습니다. Dataflow를 사용하여 BigQuery에서 데이터를 읽고 쓰는 방법에 대한 자세한 내용은 Apache Beam 문서의 BigQuery I/O를 참조하세요.

필수 권한

Cloud Storage에 데이터를 내보내려면 데이터가 포함된 BigQuery 테이블에 액세스할 권한, 내보내기 작업을 실행할 권한, Cloud Storage 버킷에 데이터를 쓸 권한이 있어야 합니다.

BigQuery 권한

  • 데이터를 내보내려면 최소한 bigquery.tables.export 권한이 부여되어 있어야 합니다. 사전 정의된 다음 Cloud IAM 역할에 bigquery.tables.export 권한이 부여됩니다.

    • bigquery.dataViewer
    • bigquery.dataOwner
    • bigquery.dataEditor
    • bigquery.admin
  • 내보내기 작업을 실행하려면 최소한 bigquery.jobs.create 권한이 부여되어 있어야 합니다. 사전 정의된 다음 Cloud IAM 역할에 bigquery.jobs.create 권한이 부여됩니다.

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

Cloud Storage 권한

  • 기존 Cloud Storage 버킷에 데이터를 쓰려면 storage.objects.createstorage.objects.delete 권한이 부여되어 있어야 합니다. 다음과 같은 사전 정의된 Cloud IAM 역할에는 두 권한이 모두 포함됩니다.

    • storage.objectAdmin
    • storage.admin

내보내기 제한

BigQuery에서 데이터를 내보낼 때 다음 사항에 유의하세요.

  • 테이블 데이터를 로컬 파일, Google 스프레드시트 또는 Google 드라이브로 내보낼 수 없습니다. 유일하게 지원되는 내보내기 위치는 Cloud Storage입니다. 쿼리 결과 저장에 대한 정보는 쿼리 결과 다운로드 및 저장을 참조하세요.
  • 최대 1GB의 테이블 데이터를 단일 파일로 내보낼 수 있습니다. 1GB가 넘는 데이터를 내보내려면 와일드 카드를 사용하여 데이터를 여러 파일로 내보내세요. 데이터를 여러 파일로 내보내면 파일 크기가 달라집니다.
  • 중첩되거나 반복되는 데이터는 CSV 형식으로 내보낼 수 없습니다. 중첩 및 반복되는 데이터는 Avro 및 JSON 내보내기가 지원됩니다.
  • 데이터를 JSON 형식으로 내보내는 경우 다른 시스템에서 데이터를 읽을 때 64비트 정밀도를 유지하기 위해서 INT64(정수) 데이터 유형이 JSON 문자열로 인코딩됩니다.
  • 여러 테이블의 데이터를 단일 내보내기 작업으로 내보낼 수 없습니다.
  • Cloud Console 또는 기본 BigQuery 웹 UI를 사용하여 데이터를 내보내는 경우에는 GZIP 이외의 압축 유형을 선택할 수 없습니다.

위치 고려사항

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

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

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

다른 위치 간 BigQuery 데이터 이동

데이터세트가 생성된 후에는 데이터세트 위치를 변경할 수 없지만 데이터세트를 복사할 수 있습니다. 한 위치에서 다른 위치로 데이터세트를 옮길 수 없지만 수동으로 데이터세트를 이동(재생성)할 수는 있습니다.

데이터세트 복사

리전 간 복사를 비롯해 데이터세트를 복사하는 단계를 알아보려면 데이터세트 복사를 참조하세요.

데이터세트 이동

데이터세트를 수동으로 한 위치에서 다른 위치로 옮기려면 다음 절차를 따르세요.

  1. 데이터세트와 같은 위치 내 리전 또는 멀티 리전 Cloud Storage 버킷으로 BigQuery 테이블의 데이터를 내보냅니다. 예를 들어 데이터세트가 EU 멀티 리전 위치에 있는 경우 EU 내 리전 또는 멀티 리전 버킷으로 데이터를 내보냅니다.

    BigQuery에서 데이터를 내보내는 경우에는 요금이 청구되지 않지만 Cloud Storage에 내보낸 데이터를 저장하는 경우에는 요금이 청구됩니다. BigQuery 내보내기를 사용하는 경우 내보내기 작업의 제한사항이 적용됩니다.

  2. Cloud Storage 버킷의 데이터를 새 위치 내 리전 또는 멀티 리전 버킷으로 복사하거나 옮깁니다. 예를 들어 US 멀티 리전 위치의 데이터를 도쿄 리전 위치로 이동하는 경우 데이터를 도쿄 내 리전 버킷으로 전송합니다. Cloud Storage 객체 전송에 대한 자세한 내용은 Cloud Storage 문서의 객체 이름 변경, 복사, 이동을 참조하세요.

    리전 간에 데이터를 전송하면 Cloud Storage에 네트워크 이그레스 요금이 청구됩니다.

  3. 새 위치의 Cloud Storage 버킷으로 데이터를 전송한 후 새 위치에서 새로운 BigQuery 데이터세트를 만듭니다. 그런 다음 Cloud Storage 버킷의 데이터를 BigQuery로 로드합니다.

    BigQuery로 데이터를 로드하는 경우에는 요금이 청구되지 않지만 데이터 또는 버킷을 삭제하기 전에 데이터를 Cloud Storage에 저장하면 요금이 청구됩니다. 데이터를 로드한 후 BigQuery에 데이터를 저장하는 경우에도 요금이 청구됩니다. BigQuery로 데이터를 로드하는 경우 로드 작업의 제한사항이 적용됩니다.

Cloud Storage를 사용하여 대규모 데이터세트를 저장 및 이동하는 방법에 대한 자세한 내용은 빅데이터에 Cloud Storage 사용을 참조하세요.

내보내기 형식 및 압축 유형

BigQuery는 내보낸 데이터에 대해 다음과 같은 데이터 형식 및 압축 유형을 지원합니다.

데이터 형식 지원되는 압축 유형 세부정보
CSV GZIP

내보낸 데이터에서 --field_delimiter CLI 플래그 또는 configuration.extract.fieldDelimiter를 사용하여 CSV 구분 기호를 제어할 수 있습니다. 추출 작업 속성을 사용하여 내보낸 데이터의 CSV 구분 기호를 제어할 수 있습니다.

중첩 및 반복 데이터가 지원되지 않습니다.

JSON GZIP 중첩 및 반복 데이터가 지원됩니다.
Avro DEFLATE, SNAPPY

Avro 내보내기에는 GZIP 압축이 지원되지 않습니다.

중첩 및 반복 데이터가 지원됩니다.

BigQuery에 저장된 데이터 내보내기

테이블 데이터를 내보내는 방법은 다음과 같습니다.

  • Cloud Console 또는 기본 BigQuery 웹 UI 사용
  • bq extract CLI 명령어 사용
  • API 또는 클라이언트 라이브러리를 통해 extract 작업 제출

테이블 데이터 내보내기

BigQuery 테이블에서 데이터를 내보내는 방법은 다음과 같습니다.

Console

  1. Cloud Console에서 BigQuery 웹 UI를 엽니다.
    Cloud Console로 이동

  2. 탐색 패널의 리소스 섹션에서 프로젝트를 펼치고 데이터세트를 클릭하여 펼칩니다. 내보낼 데이터가 포함된 테이블을 찾아서 클릭합니다.

  3. 창 오른쪽에 있는 내보내기를 클릭한 후 Google Cloud Storage로 내보내기를 선택합니다.

    데이터 내보내기

  4. 테이블을 Google Cloud Storage로 내보내기 대화상자에서

    • Google Cloud Storage 위치 선택에서 데이터를 내보낼 버킷, 폴더 또는 파일을 찾습니다.
    • 내보내기 형식에 내보낸 데이터 형식, CSV, JSON(줄바꿈으로 구분) 또는 Avro를 선택합니다.
    • 압축에서 기본값 None을 그대로 사용하거나 GZIP을 선택합니다. Avro 형식은 GZIP 압축과 함께 사용할 수 없습니다. Avro 데이터를 압축하려면 bq 명령줄 도구 또는 API를 사용하고 Avro 데이터에 지원되는 압축 유형인 DEFLATE 또는 SNAPPY 중 하나를 지정합니다.
    • 내보내기를 클릭하여 테이블을 내보냅니다.

작업의 진행 상황을 확인하려면 내보내기 작업의 작업 기록 탐색 창에서 맨 위쪽을 확인하세요.

기본 UI

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

  2. 탐색 패널에서 데이터세트를 클릭하여 펼칩니다.

  3. 내보낼 데이터가 포함된 테이블 옆에 있는 아래쪽 화살표 아이콘(아래쪽 화살표 아이콘 이미지)을 찾아서 클릭합니다.

  4. 테이블 내보내기를 선택하여 Google Cloud Storage로 내보내기 대화상자를 표시합니다.

  5. Google Cloud Storage로 내보내기 대화상자에서

    • 내보내기 형식에 내보낸 데이터 형식, CSV, JSON(줄바꿈으로 구분) 또는 Avro를 선택합니다.
    • 압축에서 기본값 None을 그대로 사용하거나 GZIP을 선택합니다. Avro 형식은 GZIP 압축과 함께 사용할 수 없습니다. Avro 데이터를 압축하려면 bq 명령줄 도구 또는 API를 사용하고 Avro 데이터에 지원되는 압축 유형인 DEFLATE 또는 SNAPPY 중 하나를 지정합니다.
    • Google Cloud Storage URI 텍스트 상자에 유효한 URI를 gs://bucket_name/filename.ext 형식으로 입력합니다. 여기서 bucket_name은 Cloud Storage 버킷 이름이고 filename.ext는 대상 파일 이름과 확장자입니다. BigQuery 데이터세트와 Cloud Storage 버킷은 같은 위치에 있어야 합니다.
    • 확인을 클릭하여 테이블을 내보냅니다.

작업이 실행 중일 때는 탐색의 테이블 이름 옆에 (추출 중)이 나타납니다. 작업의 진행 상태를 확인하려면 추출 작업의 작업 기록 탐색 창에서 맨 위쪽을 확인하세요.

CLI

bq extract 명령어를 --destination_format 플래그와 함께 사용합니다.

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

다른 선택적 플래그에는 다음이 포함됩니다.

  • --compression: 내보내는 파일에 사용할 압축 유형입니다.
  • --field_delimiter: CSV 내보내기의 출력 파일에서 열 사이의 경계를 나타내는 문자입니다. \ttab 모두 탭 구분 기호로 사용할 수 있습니다.
  • --print_header: 이 플래그를 지정하면 헤더가 있는 형식(예: CSV)의 헤더 행이 인쇄됩니다.
bq --location=location extract \
--destination_format format \
--compression compression_type \
--field_delimiter delimiter \
--print_header=boolean \
project_id:dataset.table \
gs://bucket/filename.ext

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

  • location은 사용자 위치의 이름입니다. --location 플래그는 선택사항입니다. 예를 들어 도쿄 리전에서 BigQuery를 사용한다면 플래그 값을 asia-northeast1로 설정할 수 있습니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.
  • format은 내보낸 데이터 형식(CSV, NEWLINE_DELIMITED_JSON 또는 AVRO)입니다.
  • compression_type은 데이터 형식에 지원되는 압축 유형입니다. CSVNEWLINE_DELIMITED_JSONGZIP을 지원합니다. AVRODEFLATESNAPPY를 지원합니다.
  • delimiter는 CSV 내보내기에서 열 사이의 경계를 나타내는 문자입니다. \ttab은 탭에 허용되는 이름입니다.
  • booleantrue 또는 false입니다. true로 설정하면 헤더 행은 데이터 형식이 헤더를 지원하는 경우 내보낸 데이터에 인쇄됩니다. 기본값은 true입니다.
  • project_id는 프로젝트 ID입니다.
  • dataset는 소스 데이터세트의 이름입니다.
  • table은 내보내려는 테이블입니다.
  • bucket은 데이터를 내보내려는 Cloud Storage 버킷의 이름입니다. BigQuery 데이터세트와 Cloud Storage 버킷은 같은 위치에 있어야 합니다.
  • filename.ext는 내보낸 데이터 파일의 이름과 확장자입니다. 와일드 카드를 사용하여 여러 파일로 내보낼 수 있습니다.

예:

예를 들어 다음 명령어는 mydataset.mytablemyfile.csv라는 gzip 압축 파일로 내보냅니다. myfile.csvexample-bucket이라는 Cloud Storage 버킷에 저장됩니다.

bq extract \
--compression GZIP \
'mydataset.mytable' \
gs://example-bucket/myfile.csv

기본 대상 형식은 CSV입니다. JSON 또는 Avro로 내보내려면 destination_format 플래그를 사용하고 형식을 NEWLINE_DELIMITED_JSON 또는 AVRO로 설정합니다. 예를 들면 다음과 같습니다.

bq extract \
--destination_format NEWLINE_DELIMITED_JSON \
'mydataset.mytable' \
gs://example-bucket/myfile.json

다음 명령어는 mydataset.mytable을 Snappy를 사용하여 압축된 Avro 파일로 내보냅니다. 파일 이름은 myfile.avro입니다. myfile.avroexample-bucket라는 Cloud Storage 버킷으로 내보내집니다.

bq extract \
--destination_format AVRO \
--compression SNAPPY \
'mydataset.mytable' \
gs://example-bucket/myfile.avro

API

데이터를 내보내려면 extract 작업을 만들고 작업 구성을 게재합니다.

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

  1. BigQuery 소스 데이터와 Cloud Storage 대상을 가리키는 추출 작업을 만듭니다.

  2. 프로젝트 ID, 데이터세트 ID, 테이블 ID를 포함하는 sourceTable 구성 객체를 사용하여 소스 테이블을 지정합니다.

  3. destination URI(s) 속성은 gs://bucket/filename.ext 형식으로 정규화되어야 합니다. 각 URI에 와일드 카드 문자 '*' 하나가 포함될 수 있으며 이 문자는 버킷 이름 다음에 있어야 합니다.

  4. configuration.extract.destinationFormat 속성을 설정하여 데이터 형식을 지정합니다. 예를 들어 JSON 파일을 내보내려면 이 속성을 NEWLINE_DELIMITED_JSON 값으로 설정합니다.

  5. 작업 상태를 확인하려면 초기 요청이 반환한 작업 ID를 사용하여 jobs.get(job_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 참조 문서를 확인하세요.


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

public class BigQueryExtractTable
{
    public void ExtractTable(
        string projectId = "your-project-id",
        string bucketName = "your-bucket-name")
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Define a destination URI. Use a single wildcard URI if you think
        // your exported data will be larger than the 1 GB maximum value.
        string destinationUri = $"gs://{bucketName}/shakespeare-*.csv";
        BigQueryJob job = client.CreateExtractJob(
            projectId: "bigquery-public-data",
            datasetId: "samples",
            tableId: "shakespeare",
            destinationUri: destinationUri
        );
        job = job.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.
        Console.Write($"Exported table to {destinationUri}.");
    }
}

Go

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

import (
	"context"
	"fmt"

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

// exportTableAsCompressedCSV demonstrates using an export job to
// write the contents of a table into Cloud Storage as CSV.
func exportTableAsCSV(projectID, gcsURI string) error {
	// projectID := "my-project-id"
	// gcsUri := "gs://mybucket/shakespeare.csv"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	srcProject := "bigquery-public-data"
	srcDataset := "samples"
	srcTable := "shakespeare"

	gcsRef := bigquery.NewGCSReference(gcsURI)
	gcsRef.FieldDelimiter = ","

	extractor := client.DatasetInProject(srcProject, srcDataset).Table(srcTable).ExtractorTo(gcsRef)
	extractor.DisableHeader = true
	// You can choose to run the job in a specific location for more complex data locality scenarios.
	// Ex: In this example, source dataset and GCS bucket are in the US.
	extractor.Location = "US"

	job, err := extractor.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 참조 문서를 확인하세요.

import com.google.cloud.RetryOption;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;
import org.threeten.bp.Duration;

public class ExtractTableToJson {

  public static void runExtractTableToJson() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "bigquery-public-data";
    String datasetName = "samples";
    String tableName = "shakespeare";
    String bucketName = "my-bucket";
    String destinationUri = "gs://" + bucketName + "/path/to/file";
    extractTableToJson(projectId, datasetName, tableName, destinationUri);
  }

  // Exports datasetName:tableName to destinationUri as raw CSV
  public static void extractTableToJson(
      String projectId, String datasetName, String tableName, String destinationUri) {
    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(projectId, datasetName, tableName);
      Table table = bigquery.getTable(tableId);

      // For more information on export formats available see:
      // https://cloud.google.com/bigquery/docs/exporting-data#export_formats_and_compression_types
      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      Job job = table.extract("CSV", destinationUri);

      // Blocks until this job completes its execution, either failing or succeeding.
      Job completedJob =
          job.waitFor(
              RetryOption.initialRetryDelay(Duration.ofSeconds(1)),
              RetryOption.totalTimeout(Duration.ofMinutes(3)));
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to extract due to an error: \n" + job.getStatus().getError());
        return;
      }
      System.out.println("Table export successful. Check in GCS bucket for the CSV file.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table extraction job was interrupted. \n" + e.toString());
    }
  }
}

Node.js

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

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

const bigquery = new BigQuery();
const storage = new Storage();

async function extractTableToGCS() {
  // Exports my_dataset:my_table to gcs://my-bucket/my-file as raw CSV.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";
  // const bucketName = "my-bucket";
  // const filename = "file.csv";

  // Location must match that of the source table.
  const options = {
    location: 'US',
  };

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

  console.log(`Job ${job.id} created.`);

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

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';
// $bucketName = 'The Cloud Storage bucket Name';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
$destinationUri = "gs://{$bucketName}/{$tableId}.json";
// Define the format to use. If the format is not specified, 'CSV' will be used.
$format = 'NEWLINE_DELIMITED_JSON';
// Create the extract job
$extractConfig = $table->extract($destinationUri)->destinationFormat($format);
// Run the job
$job = $table->runJob($extractConfig);  // Waits for the job to complete
printf('Exported %s to %s' . PHP_EOL, $table->id(), $destinationUri);

Python

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

# from google.cloud import bigquery
# client = bigquery.Client()
# bucket_name = 'my-bucket'
project = "bigquery-public-data"
dataset_id = "samples"
table_id = "shakespeare"

destination_uri = "gs://{}/{}".format(bucket_name, "shakespeare.csv")
dataset_ref = client.dataset(dataset_id, project=project)
table_ref = dataset_ref.table(table_id)

extract_job = client.extract_table(
    table_ref,
    destination_uri,
    # Location must match that of the source table.
    location="US",
)  # API request
extract_job.result()  # Waits for job to complete.

print(
    "Exported {}:{}.{} to {}".format(project, dataset_id, table_id, destination_uri)
)

Ruby

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

require "google/cloud/bigquery"

def extract_table(bucket_name = "my-bucket",
                  dataset_id  = "my_dataset_id",
                  table_id    = "my_table_id")

  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table    = dataset.table    table_id

  # Define a destination URI. Use a single wildcard URI if you think
  # your exported data will be larger than the 1 GB maximum value.
  destination_uri = "gs://#{bucket_name}/output-*.csv"

  extract_job = table.extract_job destination_uri do |config|
    # Location must match that of the source table.
    config.location = "US"
  end
  extract_job.wait_until_done! # Waits for the job to complete

  puts "Exported #{table.id} to #{destination_uri}"
end

Avro 내보내기 세부정보

BigQuery는 Avro 형식의 데이터를 다음과 같은 방식으로 표현합니다.

  • 결과 내보내기 파일은 Avro 컨테이너 파일입니다.
  • 각 BigQuery 행은 Avro 레코드로 표시됩니다. 중첩된 데이터는 중첩된 레코드 객체로 표현됩니다.
  • REQUIRED 필드는 해당 Avro 유형으로 표현됩니다. 예를 들어 BigQuery INTEGER 유형은 Avro LONG 유형에 매핑됩니다.
  • NULLABLE 필드는 해당 유형과 'null'의 Avro 통합으로 표현됩니다.
  • REPEATED 필드는 Avro 배열로 표현됩니다.
  • TIMESTAMP 데이터 유형은 Avro timestamp-micros 논리적 유형으로 표시됩니다.
  • DATE 데이터 유형은 기본적으로 Avro INT 유형으로 표시되며 --use_avro_logical_types 플래그가 지정되는 경우 Avro date 논리적 유형으로 표시됩니다.
  • TIME 데이터 유형은 기본적으로 Avro LONG 유형으로 표시되며 --use_avro_logical_types 플래그가 지정되는 경우 Avro time-micros 논리적 유형으로 표시됩니다.
  • DATETIME 데이터 유형은 Avro STRING 유형으로 표시됩니다. Internet Engineering Task Force(IETF)RFC 3339 사양에 따라 인코딩이 진행됩니다.

Avro 형식은 GZIP 압축과 함께 사용할 수 없습니다. Avro 데이터를 압축하려면 bq 명령줄 도구 또는 API를 사용하고 Avro 데이터에 지원되는 압축 유형인 DEFLATE 또는 SNAPPY 중 하나를 지정합니다.

데이터를 하나 이상의 파일로 내보내기

destinationUris 속성은 BigQuery가 파일을 내보내는 위치와 파일 이름을 나타냅니다.

BigQuery는 각 URI에서 와일드 카드 연산자 하나(*)를 지원합니다. 와일드 카드는 버킷 이름의 일부인 경우를 제외하고 URI의 아무 곳에나 나타날 수 있습니다. 와일드 카드 연산자를 사용하면 BigQuery에 제공된 패턴을 기반으로 분할된 파일을 여러 개 만들도록 지시합니다. 와일드 카드 연산자는 숫자(0에서 시작)로 대체되고 왼쪽으로 12자리까지 채워집니다. 예를 들어, 파일 이름 끝에 와일드 카드가 있는 URI는 첫 번째 파일에 000000000000을 추가하고 두 번째 파일에 000000000001을 추가하는 식으로 파일을 만듭니다.

다음 테이블에서는 destinationUris 속성에 사용 가능한 몇 가지 옵션을 설명합니다.

'destinationUris' 옵션
단일 URI

1GB 이하인 테이블 데이터를 내보내는 경우 단일 URI를 사용합니다. 내보낸 데이터는 일반적으로 최댓값인 1GB보다 작기 때문에 이 옵션은 가장 일반적인 사용 사례입니다.

속성 정의:

['gs://my-bucket/file-name.json']

생성:


gs://my-bucket/file-name.json
단일 와일드 카드 URI

내보내는 데이터가 최댓값인 1GB보다 크다고 생각되면 단일 와일드 카드 URI를 사용합니다. BigQuery는 제공된 패턴을 기반으로 데이터를 여러 파일로 샤딩합니다. 내보낸 파일 크기는 다양합니다.

파일 이름이 아닌 URI 구성요소에 와일드 카드를 사용하는 경우 데이터를 내보내기 전에 경로 구성요소가 존재하지 않는지 확인하세요.

속성 정의:

['gs://my-bucket/file-name-*.json']

생성:


gs://my-bucket/file-name-000000000000.json
gs://my-bucket/file-name-000000000001.json
gs://my-bucket/file-name-000000000002.json
...
여러 와일드 카드 URI

내보내기 출력을 여러 파티션으로 나누려면 여러 개의 와일드 카드 URI를 사용합니다. Dataproc과 같은 서비스로 병렬 처리 작업을 실행하는 경우 이 옵션을 사용합니다. 작업을 처리할 수 있는 작업자의 수를 결정하고 작업자당 하나의 URI를 만듭니다. BigQuery는 각 URI 위치를 파티션으로 취급하고, 병렬 처리를 사용하여 데이터를 각 위치의 여러 파일로 샤딩합니다. 각 URI마다 하나의 와일드 카드 연산자가 있고 각 URI가 고유하며 URI의 수가 할당량 정책을 초과하지 않는다고 가정할 경우, 파일 이름에 원하는 패턴을 사용할 수 있습니다.

2개 이상의 와일드 카드 URI를 전달하면 BigQuery에서 각 파티션의 끝에 세트의 '최종' 파일을 나타내는 특수한 파일을 만듭니다. 이 파일 이름은 BigQuery가 만든 샤드 수를 나타냅니다.

예를 들어 와일드 카드 URI가 gs://my-bucket/file- name-<worker number>-*.json이고 BigQuery가 샤딩된 파일 80개를 만드는 경우 제로 레코드 파일 이름은 gs://my-bucket/file-name-<worker number>-000000000080.json입니다. 이 파일 이름을 사용하여 BigQuery가 이름이 000000000000-000000000079인 샤딩된 파일 80개를 만들었는지 확인할 수 있습니다.

데이터 형식에 따라 제로 레코드 파일에 0바이트가 넘게 포함될 수 있습니다. 예를 들면 데이터를 열 헤더가 있는 CSV 형식으로 내보내는 경우가 있습니다.

문자열 패턴:

gs://my-bucket/file-name-<worker number>-*.json

속성 정의:


['gs://my-bucket/file-name-1-*.json',
'gs://my-bucket/file-name-2-*.json',
'gs://my-bucket/file-name-3-*.json']

생성:

이 예시에서는 BigQuery가 각 파티션에 샤딩된 파일 80개를 만든다고 가정합니다.


gs://my-bucket/file-name-1-000000000000.json
gs://my-bucket/file-name-1-000000000001.json
...
gs://my-bucket/file-name-1-000000000080.json
gs://my-bucket/file-name-2-000000000000.json
gs://my-bucket/file-name-2-000000000001.json
...
gs://my-bucket/file-name-2-000000000080.json
gs://my-bucket/file-name-3-000000000000.json
gs://my-bucket/file-name-3-000000000001.json
...
gs://my-bucket/file-name-3-000000000080.json

할당량 정책

내보내기 작업 할당량에 대한 자세한 내용은 할당량 및 한도 페이지의 내보내기 작업을 참조하세요.

가격 책정

현재 BigQuery에서 데이터를 내보내는 경우에는 요금이 청구되지 않지만 내보내기에는 BigQuery의 할당량 및 한도가 적용됩니다. BigQuery 가격에 대한 자세한 내용은 가격 책정 페이지를 참조하세요.

데이터를 내보낸 후 Cloud Storage에 데이터를 저장하면 요금이 청구됩니다. Cloud Storage 가격에 대한 자세한 내용은 Cloud Storage 가격 책정 페이지를 참조하세요.

다음 단계