테이블 데이터를 Cloud Storage로 내보내기

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

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

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

EXPORT DATA 문을 사용하여 쿼리 결과를 내보낼 수도 있습니다. EXPORT DATA OPTIONS를 사용하여 뷰를 Cloud Storage로 내보낼 수 있습니다.

내보내기 제한

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

• 테이블 데이터를 로컬 파일, Google Sheets 또는 Google Drive로 내보낼 수 없습니다. 유일하게 지원되는 내보내기 위치는 Cloud Storage입니다. 쿼리 결과 저장에 대한 정보는 쿼리 결과 다운로드 및 저장을 참조하세요.
• 최대 1GB의 테이블 데이터를 단일 파일로 내보낼 수 있습니다. 1GB가 넘는 데이터를 내보내려면 와일드 카드를 사용하여 데이터를 여러 파일로 내보내세요. 데이터를 여러 파일로 내보내면 파일 크기가 달라집니다. 내보낸 파일 크기를 제한하려면 데이터를 파티션으로 나누고 각 파티션을 내보내면 됩니다.
• EXPORT DATA 문을 사용할 때 생성되는 파일 크기는 보장되지 않습니다.
• 내보내기 작업에서 생성되는 파일 수는 다를 수 있습니다.
• 중첩되거나 반복되는 데이터는 CSV 형식으로 내보낼 수 없습니다. Avro, JSON, Parquet 내보내기에는 중첩 및 반복되는 데이터가 지원됩니다.
• 데이터를 JSON 형식으로 내보내는 경우 다른 시스템에서 데이터를 읽을 때 64비트 정밀도를 유지하기 위해서 INT64(정수) 데이터 유형이 JSON 문자열로 인코딩됩니다.
• 여러 테이블의 데이터를 단일 내보내기 작업으로 내보낼 수 없습니다.
• Google Cloud 콘솔을 사용하여 데이터를 내보내는 경우에는 GZIP 이외의 압축 유형을 선택할 수 없습니다.
• 보관 정책이 사용 설정된 Cloud Storage 버킷으로 데이터를 내보내지 않는 것이 좋습니다. BigQuery는 버킷에 파일을 쓰는 작업을 다시 시도할 수 있으며, 버킷의 보관 정책으로 인해 파일이 덮어쓰기되지 않는 경우 이러한 재시도가 실패할 수 있습니다. 보관 정책이 있는 Cloud Storage 버킷으로 데이터를 내보내야 하는 경우 내보내기를 시작하기 전에 정책을 사용 중지합니다.
• JSON 형식으로 테이블을 내보낼 때 <, >, & 기호는 유니코드 표기법 \uNNNN을 사용하여 변환됩니다. 여기서 N은 16진수입니다. 예를 들어 profit&loss는 profit\u0026loss가 됩니다. 이 유니코드 변환은 보안 취약점을 방지하기 위해 수행됩니다.
• 내보낸 테이블 데이터의 순서는 EXPORT DATA 문을 사용하고 query_statement에서 ORDER BY 절을 지정하지 않는 한 보장되지 않습니다.
• BigQuery는 처음 이중 슬래시 다음에 슬래시 여러 개가 연속으로 포함된 Cloud Storage 리소스 경로를 지원하지 않습니다. Cloud Storage 객체 이름에는 연속된 슬래시('/') 문자 여러 개가 포함될 수 있습니다. 하지만 BigQuery는 연속된 슬래시 여러 개를 단일 슬래시로 변환합니다. 예를 들어 gs://bucket/my//object//name 리소스 경로는 Cloud Storage에서는 유효하지만 BigQuery에서는 작동하지 않습니다.
• 내보내기 작업이 진행 중일 때 BigQuery에 로드되는 모든 새 데이터는 해당 내보내기 작업에 포함되지 않습니다 새 데이터를 내보내려면 새 내보내기 작업을 만들어야 합니다.

시작하기 전에

사용자에게 이 문서의 각 태스크를 수행하는 데 필요한 권한을 부여하는 Identity and Access Management(IAM) 역할을 부여합니다.

필수 권한

이 문서의 태스크를 수행하려면 다음 권한이 필요합니다.

BigQuery 테이블에서 데이터를 내보내는 권한

BigQuery 테이블에서 데이터를 내보내려면 bigquery.tables.export IAM 권한이 필요합니다.

사전 정의된 다음 각 IAM 역할에는 bigquery.tables.export 권한이 포함되어 있습니다.

• roles/bigquery.dataViewer
• roles/bigquery.dataOwner
• roles/bigquery.dataEditor
• roles/bigquery.admin

내보내기 작업을 실행할 수 있는 권한

내보내기 작업을 실행하려면 bigquery.jobs.create IAM 권한이 필요합니다.

다음과 같은 사전 정의된 각 IAM 역할에는 내보내기 작업을 실행하는 데 필요한 권한이 포함되어 있습니다.

• roles/bigquery.user
• roles/bigquery.jobUser
• roles/bigquery.admin

데이터를 Cloud Storage 버킷에 쓸 수 있는 권한

데이터를 기존 Cloud Storage 버킷에 쓰려면 다음과 같은 IAM 권한이 필요합니다.

• storage.objects.create
• storage.objects.delete

다음과 같은 사전 정의된 각 IAM 역할에는 기존 Cloud Storage 버킷에 데이터를 쓰는 데 필요한 권한이 포함되어 있습니다.

• roles/storage.objectAdmin
• roles/storage.admin

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

위치 고려사항

• BigQuery 데이터 세트가 EU 멀티 리전에 있는 경우 내보내는 데이터가 포함된 Cloud Storage 버킷이 동일한 멀티 리전이나 멀티 리전 내에 포함된 위치에 있어야 합니다. 예를 들어 BigQuery 데이터 세트가 EU 멀티 리전에 있으면 Cloud Storage 버킷은 EU 내에 있는 europe-west1 벨기에 리전에 있을 수 있습니다.

  데이터 세트가 US 멀티 리전에 있는 경우 데이터를 모든 위치의 Cloud Storage 버킷으로 내보낼 수 있습니다.

• 데이터 세트가 한 리전에 있으면 Cloud Storage 버킷은 같은 리전에 있어야 합니다. 예를 들어 데이터 세트가 asia-northeast1 도쿄 리전에 있으면 Cloud Storage 버킷은 ASIA 멀티 리전에 있을 수 없습니다.

• BigQuery 데이터 세트 또는 Cloud Storage 버킷과 같은 리전 내 스토리지 리소스를 선택한 경우 데이터를 지리적으로 관리하기 위한 계획을 세웁니다.

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

다른 위치 간 BigQuery 데이터 이동

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

내보내기 형식 및 압축 유형

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

데이터 내보내기

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

• Google Cloud 콘솔 사용
• bq 명령줄 도구에서 bq extract 명령어 사용
• API 또는 클라이언트 라이브러리를 사용하여 extract 작업 제출

테이블 데이터 내보내기

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

bq extract --location=location \
--destination_format format \
--compression compression_type \
--field_delimiter delimiter \
--print_header=boolean \
project_id:dataset.table \
gs://bucket/filename.ext

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

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

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

bq extract \
--destination_format CSV \
'mydataset.my_partitioned_table$0' \
gs://example-bucket/single_partition.csv

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}.");
    }
}

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
}

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 ExtractTableToCsv {

  public static void runExtractTableToCsv() {
    // 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";
    // 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

    String dataFormat = "CSV";
    extractTableToCsv(projectId, datasetName, tableName, destinationUri, dataFormat);
  }

  // Exports datasetName:tableName to destinationUri as raw CSV
  public static void extractTableToCsv(
      String projectId,
      String datasetName,
      String tableName,
      String destinationUri,
      String dataFormat) {
    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);

      Job job = table.extract(dataFormat, 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 " + dataFormat + " file.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table extraction job was interrupted. \n" + e.toString());
    }
  }
}

// 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;
  }
}

use Google\Cloud\BigQuery\BigQueryClient;

/**
 * Extracts the given table as json to given GCS bucket.
 *
 * @param string $projectId The project Id of your Google Cloud Project.
 * @param string $datasetId The BigQuery dataset ID.
 * @param string $tableId The BigQuery table ID.
 * @param string $bucketName Bucket name in Google Cloud Storage
 */
function extract_table(
    string $projectId,
    string $datasetId,
    string $tableId,
    string $bucketName
): void {
    $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);
}

# 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 = bigquery.DatasetReference(project, dataset_id)
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)
)

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 데이터 유형은 기본적으로 추출 작업과 내보내기 데이터 SQL 모두에서 timestamp-micros 논리 유형(Avro LONG 유형 주석 처리)으로 표시됩니다. (주의: Export Data Options에 use_avro_logical_types=False를 추가하여 논리 유형을 사용 중지하여 타임스탬프 열 대신 string 유형을 사용하도록 할 수 있지만 추출 작업에서는 항상 Avro 논리 유형을 사용합니다.)
• DATE 데이터 유형은 데이터 내보내기 SQL에서 기본적으로 date 논리 유형(Avro INT 유형 주석 처리)으로 표시되지만 추출 작업에서는 기본적으로 string 유형으로 표시됩니다. (참고: Export Data Options에 use_avro_logical_types=False를 추가하여 논리 유형을 사용 중지하거나 --use_avro_logical_types=True 플래그를 사용하여 추출 작업에서 논리 유형을 사용 설정할 수 있습니다.)
• TIME 데이터 유형은 데이터 내보내기 SQL에서 기본적으로 timestamp-micro 논리 유형(Avro LONG 유형 주석 처리)으로 표시되지만 추출 작업에서는 기본적으로 string 유형으로 표시됩니다. (참고: Export Data Options에 use_avro_logical_types=False를 추가하여 논리 유형을 사용 중지하거나 --use_avro_logical_types=True 플래그를 사용하여 추출 작업에서 논리 유형을 사용 설정할 수 있습니다.)
• DATETIME 데이터 유형은 데이터 내보내기 SQL에서 기본적으로 Avro STRING 유형(논리 유형이 커스텀으로 명명된 datetime인 문자열 유형)으로 표시되지만 추출 작업에서는 기본적으로 string로 표시됩니다. (참고: Export Data Options에 use_avro_logical_types=False를 추가하여 논리 유형을 사용 중지하거나 --use_avro_logical_types=True 플래그를 사용하여 추출 작업에서 논리 유형을 사용 설정할 수 있습니다.)
• Avro 내보내기에서는 범위 유형이 지원되지 않습니다.

매개변수화된 NUMERIC(P[, S]) 및 BIGNUMERIC(P[, S]) 데이터 유형은 정밀도 및 확장 유형 매개변수를 Avro 10진수 논리 유형으로 전송합니다.

Avro 형식은 GZIP 압축에 사용될 수 없습니다. Avro 데이터를 압축하려면 bq 명령줄 도구 또는 API를 사용하고 Avro 데이터에 대해 지원되는 압축 유형(DEFLATE 또는 SNAPPY) 중 하나를 지정하세요.

Parquet 내보내기 세부정보

BigQuery는 GoogleSQL 데이터 유형을 다음과 같은 Parquet 데이터 유형으로 변환합니다.

Parquet 스키마는 중첩된 데이터를 그룹으로 나타내고 반복 레코드를 반복 그룹으로 나타냅니다. BigQuery에서 중첩 및 반복 데이터 사용에 대한 자세한 내용은 중첩 및 반복 열 지정을 참조하세요.

DATETIME 유형에 대해 다음 해결 방법을 사용할 수 있습니다.

• 파일을 스테이징 테이블에 로드합니다. 그런 다음 SQL 쿼리를 사용하여 필드를 DATETIME으로 변환하고 결과를 새 테이블에 저장합니다. 자세한 내용은 열의 데이터 유형 변경을 참조하세요.
• 로드 작업에서 --schema 플래그를 사용하여 테이블의 스키마를 제공합니다. 날짜/시간 열을 col:DATETIME으로 정의합니다.

GEOGRAPHY 논리적 유형은 내보낸 파일에 추가된 GeoParquet 메타데이터로 표시됩니다.

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

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

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

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

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
...

내보내는 파일 크기 제한

내보내기 한 번으로 1GB를 초과하는 데이터를 내보낼 때는 와일드 카드를 사용하여 데이터를 여러 파일로 내보내야 하며, 파일 크기는 다양합니다. 내보낸 각 파일의 최대 크기를 제한해야 하는 경우, 데이터를 무작위로 파티션을 나눈 후 각 파티션을 파일로 내보내는 방법이 있습니다.

1. 필요한 총 파티션 수를 결정합니다. 이는 총 데이터 크기를 선택한 내보낸 파일 크기로 나눈 값입니다. 예를 들어 8,000MB의 데이터가 있고 내보낸 각 파일이 약 20MB가 되도록 하려면 400개의 파티션이 필요합니다.

2. 무작위로 생성된 새로운 열인 export_id로 파티션을 나누고 클러스터링한 새 테이블을 만듭니다. 다음 예시에서는 선택한 파일 크기를 달성하기 위해 n 파티션이 필요한 source_table이라는 기존 테이블에서 새 processed_table을 만드는 방법을 보여줍니다.

   CREATE TABLE my_dataset.processed_table
   PARTITION BY RANGE_BUCKET(export_id, GENERATE_ARRAY(0, n, 1))
   CLUSTER BY export_id
   AS (
     SELECT *, CAST(FLOOR(n*RAND()) AS INT64) AS export_id
     FROM my_dataset.source_table
   );

3. 0에서 n-1 사이의 각 정수 i에 대해 다음 쿼리에서 EXPORT DATA 문을 실행합니다.

   SELECT * EXCEPT(export_id)
   FROM my_dataset.processed_table
   WHERE export_id = i;

압축된 테이블 추출

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 compressed CSV.
func exportTableAsCompressedCSV(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: %w", err)
	}
	defer client.Close()

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

	gcsRef := bigquery.NewGCSReference(gcsURI)
	gcsRef.Compression = bigquery.Gzip

	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
}

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

// Sample to extract a compressed table
public class ExtractTableCompressed {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectName = "MY_PROJECT_NAME";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String bucketName = "MY-BUCKET-NAME";
    String destinationUri = "gs://" + bucketName + "/path/to/file";
    // For more information on export formats available see:
    // https://cloud.google.com/bigquery/docs/exporting-data#export_formats_and_compression_types
    String compressed = "gzip";
    // For more information on Job see:
    // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
    String dataFormat = "CSV";

    extractTableCompressed(
        projectName, datasetName, tableName, destinationUri, dataFormat, compressed);
  }

  public static void extractTableCompressed(
      String projectName,
      String datasetName,
      String tableName,
      String destinationUri,
      String dataFormat,
      String compressed) {
    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(projectName, datasetName, tableName);

      ExtractJobConfiguration extractConfig =
          ExtractJobConfiguration.newBuilder(tableId, destinationUri)
              .setCompression(compressed)
              .setFormat(dataFormat)
              .build();

      Job job = bigquery.create(JobInfo.of(extractConfig));

      // Blocks until this job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      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 extract compressed successful");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table extraction job was interrupted. \n" + e.toString());
    }
  }
}

// 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 extractTableCompressed() {
  // Exports my_dataset:my_table to gcs://my-bucket/my-file as a compressed file.

  /**
   * 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',
    gzip: true,
  };

  // 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;
  }
}

# from google.cloud import bigquery
# client = bigquery.Client()
# bucket_name = 'my-bucket'

destination_uri = "gs://{}/{}".format(bucket_name, "shakespeare.csv.gz")
dataset_ref = bigquery.DatasetReference(project, dataset_id)
table_ref = dataset_ref.table("shakespeare")
job_config = bigquery.job.ExtractJobConfig()
job_config.compression = bigquery.Compression.GZIP

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

테이블 메타데이터 내보내기

BigLake 관리형 테이블에서 테이블 메타데이터를 내보내려면 다음 SQL 문을 사용합니다.

EXPORT TABLE METADATA FROM `[[PROJECT_NAME.]DATASET_NAME.]TABLE_NAME`;

다음을 바꿉니다.

• PROJECT_NAME: 테이블의 프로젝트 이름입니다. 값은 기본적으로 이 쿼리를 실행하는 프로젝트로 지정됩니다.
• DATASET_NAME: 테이블의 데이터 세트 이름입니다.
• TABLE_NAME: 테이블의 이름입니다.

내보낸 메타데이터는 STORAGE_URI/metadata 폴더에 저장되며, 여기서 STORAGE_URI는 옵션에 설정된 테이블의 스토리지 위치입니다.

사용 사례

이 예에서는 Cloud Storage로 데이터를 내보내는 방법을 보여줍니다.

엔드포인트 로그에서 Cloud Storage로 데이터를 지속적으로 스트리밍한다고 가정해 보겠습니다. 백업 및 보관처리 목적으로 일일 스냅샷을 Cloud Storage로 내보냅니다. 가장 좋은 방법은 특정 할당량 및 제한사항이 적용되는 추출 작업입니다.

API 또는 클라이언트 라이브러리로 추출 작업을 제출하여 고유 ID를 jobReference.jobId로 전달합니다. 추출 작업은 비동기식입니다. 작업을 만드는 데 사용된 고유한 작업 ID를 사용하여 작업 상태를 확인합니다. status.status가 DONE이면 작업이 성공적으로 완료된 것입니다. status.errorResult가 있으면 작업이 실패하며 다시 시도해야 합니다.

일괄 데이터 처리

야간 일괄 작업이 고정된 기한까지 데이터를 로드하는 데 사용된다고 가정해 보겠습니다. 이 로드 작업이 완료되면 이전 섹션의 설명대로 통계가 있는 테이블이 쿼리에서 구체화됩니다. 이 테이블의 데이터를 검색 후 PDF 보고서로 컴파일하여 규제 기관에 전송합니다.

읽어야 하는 데이터 양이 적으므로 tabledata.list API를 사용하여 JSON 사전 형식으로 테이블의 모든 행을 검색합니다. 1페이지를 초과하는 데이터가 있으면 결과에 pageToken 속성이 설정됩니다. 결과의 다음 페이지를 검색하려면 다른 tabledata.list를 호출하고 토큰 값을 pageToken 파라미터로 포함합니다. API 호출이 5xx 오류로 실패하면 지수 백오프로 다시 시도합니다. 대부분의 4xx 오류는 다시 시도할 수 없습니다. BigQuery 내보내기와 보고서 생성을 더욱 효과적으로 분리하려면 결과를 디스크에 유지해야 합니다.

할당량 정책

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

내보내기 작업의 사용량은 INFORMATION_SCHEMA에서 확인할 수 있습니다. 내보내기 작업의 JOBS_BY_* 시스템 테이블에 있는 작업 항목에는 일일 50TB 미만으로 유지되도록 집계 사용량을 모니터링하는 데 사용할 수 있는 total_processed_bytes 값이 포함됩니다. INFORMATION_SCHEMA.JOBS 뷰를 쿼리하여 total_processed_bytes 값을 가져오는 방법을 알아보려면 INFORMATION_SCHEMA.JOBS 스키마를 참고하세요.

현재 할당량 사용량 보기

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()

내보낸 바이트 수에 대한 알림을 제공하는 Cloud Monitoring 알림 정책을 설정할 수 있습니다.

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

   Monitoring으로 이동

2. 탐색창에서 측정항목 탐색기를 선택합니다.

3. MQL 쿼리 편집기에서 다음 예시와 같이 하루에 내보낸 바이트를 모니터링하도록 알림을 설정합니다.

   fetch consumer_quota
     | filter resource.service == 'bigquery.googleapis.com'
     | { metric serviceruntime.googleapis.com/quota/rate/net_usage
         | align delta_gauge(1m)
         | group_by [resource.project_id, metric.quota_metric, resource.location],
             sum(value.net_usage)
       ; metric serviceruntime.googleapis.com/quota/limit
         | filter metric.limit_name == 'ExtractBytesPerDay'
         | group_by [resource.project_id, metric.quota_metric, resource.location],
             sliding(1m), max(val()) }
     | ratio
     | every 1m
     | condition gt(val(), 0.01 '1')
   

4. 알림을 설정하려면 쿼리 실행을 클릭합니다.

자세한 내용은 MQL을 사용한 알림 정책을 참조하세요.

문제 해결

추출 작업 관련 문제를 진단하려면 로그 탐색기를 사용하여 특정 추출 작업의 로그를 검토하고 발생할 수 있는 오류를 식별하면 됩니다. 다음 로그 탐색기 필터는 추출 작업에 관한 정보를 반환합니다.

resource.type="bigquery_resource"
protoPayload.methodName="jobservice.insert"
(protoPayload.serviceData.jobInsertRequest.resource.jobConfiguration.query.query=~"EXPORT" OR
protoPayload.serviceData.jobCompletedEvent.eventName="extract_job_completed" OR
protoPayload.serviceData.jobCompletedEvent.job.jobConfiguration.query.query=~"EXPORT")

가격 책정

데이터 내보내기 가격 책정에 대한 자세한 내용은 BigQuery 가격 책정 페이지를 참조하세요.

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

테이블 보안

BigQuery에서 테이블에 대한 액세스를 제어하려면 테이블 액세스 제어 소개를 참조하세요.

다음 단계

• Google Cloud 콘솔에 대한 자세한 내용은 Google Cloud 콘솔 사용을 참조하세요.
• bq 명령줄 도구에 대한 자세한 내용은 bq 명령줄 도구 사용을 참고하세요.
• BigQuery API 클라이언트 라이브러리를 사용하여 애플리케이션을 만드는 방법은 클라이언트 라이브러리 빠른 시작을 참조하세요.