Cloud Storage에서 CSV 데이터 로드

Cloud Storage에서 CSV 파일 로드

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

Cloud Storage에서 BigQuery 테이블로 데이터를 로드할 때 테이블을 포함한 데이터세트는 Cloud Storage 버킷과 같은 지역이나 다중 지역 위치에 있어야 합니다.

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

제한사항

CSV 데이터를 Cloud Storage에서 BigQuery로 로드할 때는 다음 사항에 유의하세요.

  • CSV 파일은 중첩되거나 반복되는 데이터는 지원하지 않습니다.
  • gzip 압축을 사용하면 BigQuery는 데이터를 동시에 읽지 못합니다. 압축한 CSV 데이터를 BigQuery로 로드하는 작업은 미압축 데이터를 로드하는 작업보다 시간이 더 걸립니다.
  • CSV 또는 JSON 데이터를 로드할 때 DATE 열의 값은 대시(-) 구분 기호를 사용해야 하며 날짜는 YYYY-MM-DD(년-월-일) 형식이어야 합니다.
  • JSON이나 CSV 데이터를 로드할 때 TIMESTAMP 열의 값은 타임스탬프 날짜 부분에 대시 (-) 구분 기호를 사용해야 하며 날짜는 YYYY-MM-DD(년-월-일) 형식이어야 합니다. 타임스탬프의 hh:mm:ss(시간-분-초) 부분은 콜론(:) 구분 기호를 사용해야 합니다.

CSV 인코딩

BigQuery는 CSV 데이터가 UTF-8로 인코딩된다고 가정합니다. CSV 파일에 ISO-8859-1(Latin-1이라고도 함) 형식으로 인코딩한 데이터가 있다면 데이터를 로드할 때 인코딩을 명시적으로 지정해야 UTF-8로 변환할 수 있습니다.

CSV 파일의 구분 기호는 ISO-8859-1 단일 바이트의 어떤 문자도 될 수 있습니다. 128~255 범위의 문자를 사용하려면 문자를 UTF-8으로 인코딩해야 합니다. BigQuery는 문자열을 ISO-8859-1 인코딩으로 변환하고 인코딩된 문자열의 첫 번째 바이트를 사용해 데이터를 원시 바이너리 상태로 분할합니다.

필수 권한

BigQuery로 데이터를 로드할 때는 데이터를 신규 또는 기존 BigQuery 테이블과 파티션에 로드할 수 있는 프로젝트 또는 데이터세트 수준의 권한이 있어야 합니다. Cloud Storage에서 데이터를 로드하는 경우에는 데이터가 포함된 버킷에 대한 액세스 권한도 필요합니다.

BigQuery 권한

Cloud Storage에서 BigQuery로 데이터를 로드할 때는 프로젝트 수준이나 데이터세트 수준에서 bigquery.dataOwner 또는 bigquery.dataEditor 역할을 부여 받아야 합니다. 두 역할 모두 사용자와 그룹에게 데이터를 새로운 테이블에 로드하거나 기존 테이블에 추가 또는 덮어쓸 수 있는 권한을 부여합니다.

사용자나 그룹이 프로젝트 수준의 역할을 부여 받으면 프로젝트 내의 모든 데이터세트에 있는 테이블에 데이터를 로드할 수 있는 권한이 제공됩니다. 사용자나 그룹이 데이터세트 수준의 역할을 부여 받으면 데이터를 해당 데이터세트의 테이블에만 로드할 수 있습니다.

데이터세트 액세스 권한 구성에 대한 자세한 내용은 데이터세트에 대한 액세스 제어를 참조하세요. BigQuery의 IAM 역할에 대한 자세한 내용은 액세스 제어를 참조하세요.

Cloud Storage 권한

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

사전 정의된 IAM 역할 storage.objectViewer를 부여받으면 storage.objects.getstorage.objects.list 권한이 제공됩니다.

CSV 데이터를 테이블에 로드

Cloud Storage의 CSV 데이터를 새 BigQuery 테이블로 로드하거나 기존 테이블에 데이터를 추가하려면 다음 단계를 따르세요.

콘솔

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

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

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

    데이터세트 보기

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

    • 다음 항목으로 테이블 만들기에서 원하는 소스 유형을 선택합니다.

    • 소스 필드에서 파일/Cloud Storage 버킷을 찾아보거나 Cloud Storage URI를 입력합니다. BigQuery 웹 UI에서는 URI가 여러 개 포함될 수 없지만 와일드 카드는 지원됩니다. Cloud Storage 버킷은 생성 중인 테이블을 포함하는 데이터세트와 같은 위치에 있어야 합니다.

      데이터세트 보기

    • 파일 형식CSV를 선택합니다.

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

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

      데이터세트 보기

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

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

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

    • 다음과 같이 스키마 정보를 직접 입력합니다.

      • 텍스트로 수정을 사용 설정하고 테이블 스키마를 JSON 배열로 입력합니다.

      • 필드 추가를 사용하여 스키마를 수동으로 입력합니다.

  7. 고급 옵션 섹션에서 해당 항목을 선택한 다음 테이블 만들기를 클릭합니다. 사용 가능한 옵션에 대한 자세한 내용은 CSV 옵션을 참조하세요.

기본 UI

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

  2. 탐색 패널에서 마우스로 데이터세트를 가리키고 아래쪽 화살표 아이콘 아래쪽 화살표 아이콘 이미지을 클릭한 후 새 테이블 만들기를 클릭합니다. 데이터를 로드하는 프로세스는 빈 테이블을 만드는 프로세스와 동일합니다.

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

    • 위치에서 Cloud Storage를 선택하고 소스 필드에 Cloud Storage URI를 입력합니다. BigQuery 웹 UI에서는 URI가 여러 개 포함될 수 없지만 와일드 카드는 지원됩니다. Cloud Storage 버킷은 생성 중인 테이블을 포함하는 데이터세트와 같은 위치에 있어야 합니다.
    • 파일 형식에는 쉼표로 구분된 값(CSV)을 선택합니다.
  4. 테이블 만들기 페이지의 대상 테이블 섹션에서 다음을 수행합니다.

    • 테이블 이름으로 적절한 데이터세트를 선택하고 테이블 이름 필드에 BigQuery에서 만들 테이블의 이름을 입력합니다.
    • 테이블 유형기본 테이블로 설정되어 있는지 확인합니다.
  5. 스키마 섹션에 스키마 정의를 입력합니다.

    • 다음과 같이 스키마 정보를 직접 입력합니다.

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

        JSON 배열로 스키마 추가

      • 필드 추가를 사용하여 스키마를 수동으로 입력합니다.

        필드 추가를 사용하여 스키마 추가

  6. 옵션 섹션에서 관련 항목을 선택하고 테이블 만들기를 클릭합니다. 사용 가능한 옵션에 대한 자세한 내용은 CSV 옵션을 참조하세요.

명령줄

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

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

bq --location=[LOCATION] load --source_format=[FORMAT] [DATASET].[TABLE] [PATH_TO_SOURCE] [SCHEMA]

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

  • [LOCATION]은 사용자의 위치입니다. --location 플래그는 선택사항입니다. 예를 들어, 도쿄 지역에서 BigQuery를 사용하는 경우에는 플래그 값을 asia-northeast1로 설정할 수 있습니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.
  • [FORMAT]은 CSV입니다.
  • [DATASET]는 기존 데이터세트입니다.
  • [TABLE]은 데이터를 로드하는 테이블의 이름입니다.
  • [PATH_TO_SOURCE]는 정규화된 Cloud Storage URI 또는 쉼표로 구분된 URI 목록이며 와일드 카드도 지원됩니다.
  • [SCHEMA]는 유효한 스키마입니다. 스키마는 로컬 JSON 파일일 수도 있고 명령어의 일부로 인라인으로 입력해도 됩니다. 스키마 정의를 제공하는 대신 --autodetect 플래그를 사용할 수도 있습니다.

또한 BigQuery가 데이터를 파싱하는 방법을 제어할 수 있는 CSV 옵션의 플래그를 추가할 수 있습니다. 예를 들어 --skip_leading_rows 플래그를 사용하면 CSV 파일의 헤더 행을 무시하고, --encoding 플래그를 사용하면 데이터의 문자 인코딩을 확인할 수 있습니다.

예:

  • 다음 명령어는 gs://mybucket/mydata.csv에서 mydataset에 있는 mytable이라는 이름의 테이블로 데이터를 로드합니다. 스키마는 myschema.json이라는 이름의 로컬 스키마 파일에서 정의됩니다. mybucketmydatasetUS 다중 지역 위치에서 생성되었습니다.

    bq --location=US load --source_format=CSV mydataset.mytable gs://mybucket/mydata.csv ./myschema.json
    
  • 다음 명령어는 gs://mybucket/mydata.csv에서 mydataset에 있는 mytable이라는 이름의 테이블로 데이터를 로드합니다. 스키마는 [FIELD]:[DATA_TYPE], [FIELD]:[DATA_TYPE] 형식으로 인라인으로 정의되며, mybucketmydatasetUS 다중 지역 위치에서 생성되었습니다.

    bq --location=US load --source_format=CSV mydataset.mytable gs://mybucket/mydata.csv qtr:STRING,sales:FLOAT,year:STRING
    

    명령줄에서 스키마를 지정할 때는 RECORD(STRUCT) 유형을 포함할 수 없고 필드 설명을 포함할 수도 없으며 필드 모드를 지정할 수도 없습니다. 모든 필드 모드는 기본적으로 NULLABLE로 설정됩니다. 필드 설명, 모드, RECORD 유형을 포함하려면 대신 JSON 스키마 파일을 제공합니다.

  • 다음 명령어는 gs://mybucket/mydata.csv에서 mydataset에 있는 mytable이라는 이름의 테이블로 데이터를 로드합니다. 스키마는 myschema.json이라는 이름의 로컬 스키마 파일에서 정의되고, --skip_leading_rows 플래그는 CSV 파일의 처음 2개의 헤더 행을 무시하는 데 사용됩니다. mybucketmydatasetasia-northeast1 지역에서 생성되었습니다.

    bq --location=asia-northeast1 load --skip_leading_rows=2 --source_format=CSV mydataset.mytable gs://mybucket/mydata.csv ./myschema.json
    

API

API를 사용하여 CSV 데이터를 로드하려면 다음 속성을 설정하세요.

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

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

  3. 소스 URI는 gs://[BUCKET]/[OBJECT] 형식으로 정규화되어야 합니다. 각 URI는 '*' 와일드 카드 문자 하나를 포함할 수 있습니다.

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

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

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

public class BigQueryLoadTableGcsCsv
{
    public void LoadTableGcsCsv(
        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.csv";
        var dataset = client.GetDataset(datasetId);
        var schema = new TableSchemaBuilder {
            { "name", BigQueryDbType.String },
            { "post_abbr", BigQueryDbType.String }
        }.Build();
        var destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            // The source format defaults to CSV; line below is optional.
            SourceFormat = FileFormat.Csv,
            SkipLeadingRows = 1
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI, destination: destinationTableRef,
            schema: schema, options: jobOptions);
        loadJob.PollUntilCompleted();  // 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 참조 문서를 확인하세요.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.csv")
gcsRef.SkipLeadingRows = 1
gcsRef.Schema = bigquery.Schema{
	{Name: "name", Type: bigquery.StringFieldType},
	{Name: "post_abbr", Type: bigquery.StringFieldType},
}
loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
loader.WriteDisposition = bigquery.WriteEmpty

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

자바

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

Job job = table.load(FormatOptions.csv(), sourceUri);
// Wait for the job to complete
try {
  Job completedJob =
      job.waitFor(
          RetryOption.initialRetryDelay(Duration.ofSeconds(1)),
          RetryOption.totalTimeout(Duration.ofMinutes(3)));
  if (completedJob != null && completedJob.getStatus().getError() == null) {
    // Job completed successfully
  } else {
    // Handle error case
  }
} catch (InterruptedException e) {
  // Handle interrupted wait
}

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');

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

/**
 * 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.csv';

async function loadCSVFromGCS() {
  // Imports a GCS file into a table with manually defined schema.

  // Instantiate clients
  const bigqueryClient = new BigQuery();
  const storageClient = new Storage();

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.load
  const metadata = {
    sourceFormat: 'CSV',
    skipLeadingRows: 1,
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
      ],
    },
    location: 'US',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigqueryClient
    .dataset(datasetId)
    .table(tableId)
    .load(storageClient.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;
  }
}
loadCSVFromGCS();

PHP

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

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.csv';
$schema = [
    'fields' => [
        ['name' => 'name', 'type' => 'string'],
        ['name' => 'post_abbr', 'type' => 'string']
    ]
];
$loadConfig = $table->loadFromStorage($gcsUri)->schema($schema)->skipLeadingRows(1);
$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 참조 문서를 확인하세요.

Cloud Storage에 있는 CSV 파일에서 데이터를 로드하려면 Client.load_table_from_uri() 메소드를 사용합니다. LoadJobConfig.schema 속성을 SchemaField 객체 목록으로 설정하여 명시적인 스키마 정의를 제공해야 합니다.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.schema = [
    bigquery.SchemaField("name", "STRING"),
    bigquery.SchemaField("post_abbr", "STRING"),
]
job_config.skip_leading_rows = 1
# The source format defaults to CSV, so the line below is optional.
job_config.source_format = bigquery.SourceFormat.CSV
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"

load_job = client.load_table_from_uri(
    uri, dataset_ref.table("us_states"), job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

destination_table = client.get_table(dataset_ref.table("us_states"))
print("Loaded {} rows.".format(destination_table.num_rows))

Ruby

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

require "google/cloud/bigquery"

def load_table_gcs_csv 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.csv"
  table_id = "us_states"

  load_job = dataset.load_job table_id, gcs_uri, skip_leading: 1 do |schema|
    schema.string "name"
    schema.string "post_abbr"
  end
  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

스키마 자동 감지로 CSV 데이터 로드

콘솔

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

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

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

    데이터세트 보기

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

    • 다음 항목으로 테이블 만들기에서 원하는 소스 유형을 선택합니다.

    • 소스 필드에서 파일/Cloud Storage 버킷을 찾아보거나 Cloud Storage URI를 입력합니다. BigQuery 웹 UI에서는 URI가 여러 개 포함될 수 없지만 와일드 카드는 지원됩니다. Cloud Storage 버킷은 생성 중인 테이블을 포함하는 데이터세트와 같은 위치에 있어야 합니다.

      데이터세트 보기

    • 파일 형식CSV를 선택합니다.

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

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

      데이터세트 보기

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

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

  6. 스키마 섹션의 자동 감지 아래에서 스키마 및 입력 매개변수를 확인하여 스키마 자동 감지를 사용 설정합니다.

    자동 감지 링크

  7. 고급 옵션 섹션에서 해당 항목을 선택한 다음 테이블 만들기를 클릭합니다. 사용 가능한 옵션에 대한 자세한 내용은 CSV 옵션을 참조하세요.

기본 UI

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

  2. 탐색 패널에서 마우스로 데이터세트를 가리키고 아래쪽 화살표 아이콘 아래쪽 화살표 아이콘 이미지을 클릭한 후 새 테이블 만들기를 클릭합니다. 데이터를 로드하는 프로세스는 빈 테이블을 만드는 프로세스와 동일합니다.

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

    • 위치에서 Cloud Storage를 선택하고 소스 필드에 Cloud Storage URI를 입력합니다. BigQuery 웹 UI에서는 URI가 여러 개 포함될 수 없지만 와일드 카드는 지원됩니다. Cloud Storage 버킷은 생성 중인 테이블을 포함하는 데이터세트와 같은 위치에 있어야 합니다.
    • 파일 형식에는 쉼표로 구분된 값(CSV)을 선택합니다.
  4. 테이블 만들기 페이지의 대상 테이블 섹션에서 다음을 수행합니다.

    • 테이블 이름으로 적절한 데이터세트를 선택하고 테이블 이름 필드에 BigQuery에서 만들 테이블의 이름을 입력합니다.
    • 테이블 유형기본 테이블로 설정되어 있는지 확인합니다.
  5. 스키마 섹션에서 자동 감지 옵션을 선택하여 스키마 자동 감지를 사용 설정할 수 있습니다.

    자동 감지 링크

  6. 옵션 섹션에서 관련 항목을 선택하고 테이블 만들기를 클릭합니다. 사용 가능한 옵션에 대한 자세한 내용은 CSV 옵션을 참조하세요.

명령줄

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

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

bq --location=[LOCATION] load --autodetect --source_format=[FORMAT] [DATASET].[TABLE] [PATH_TO_SOURCE]

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

  • [LOCATION]은 사용자의 위치입니다. --location 플래그는 선택사항입니다. 예를 들어 도쿄 리전에서 BigQuery를 사용하는 경우에는 플래그 값을 asia-northeast1로 설정할 수 있습니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.
  • --autodetect 플래그는 스키마 자동 감지를 사용합니다.
  • [FORMAT]은 CSV입니다.
  • [DATASET]는 기존 데이터세트입니다.
  • [TABLE]은 데이터를 로드하는 테이블의 이름입니다.
  • [PATH_TO_SOURCE]는 정규화된 Cloud Storage URI이거나 쉼표로 구분된 URI 목록입니다. 와일드 카드도 지원됩니다.

또한 BigQuery가 데이터를 파싱하는 방법을 제어할 수 있는 CSV 옵션의 플래그를 추가할 수 있습니다. 예를 들어 --skip_leading_rows 플래그를 사용하면 CSV 파일의 헤더 행을 무시하고, --encoding 플래그를 사용하면 데이터의 문자 인코딩을 확인할 수 있습니다.

예:

  • 다음 명령어는 gs://mybucket/mydata.csv에서 mydataset에 있는 mytable이라는 이름의 테이블로 데이터를 로드합니다. 스키마는 스키마 자동 감지를 이용해 정의됩니다. mybucketmydatasetUS 다중 지역 위치에서 생성되었습니다.

    bq --location=US load --autodetect --source_format=CSV mydataset.mytable gs://mybucket/mydata.csv
    
  • 다음 명령어는 gs://mybucket/에 있는 여러 파일에서 mydataset에 있는 mytable이라는 이름의 테이블로 데이터를 로드합니다. Cloud Storage URI는 와일드 카드를 사용하며 스키마는 스키마 자동 감지를 이용해 정의됩니다. mybucketmydatasetasia-northeast1 지역에서 생성되었습니다.

    bq --location=asia-northeast1 load --autodetect --source_format=CSV mydataset.mytable gs://mybucket/mydata*.csv
    
  • 다음 명령어는 gs://mybucket/에 있는 여러 파일에서 mydataset에 있는 mytable이라는 이름의 테이블로 데이터를 로드합니다. 명령어는 쉼표로 구분된 Cloud Storage URI 목록을 포함하며 스키마는 스키마 자동 감지를 이용해 정의됩니다. mybucketmydatasetasia-northeast1 지역에서 생성되었습니다.

    bq --location=asia-northeast1 load --autodetect --source_format=CSV mydataset.mytable "gs://mybucket/myfile.csv,gs://mybucket/myfile2.csv"
    

API

API를 사용하여 CSV 데이터를 로드하려면 다음 속성을 설정하세요.

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

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

  3. 소스 URI는 gs://[BUCKET]/[OBJECT] 형식으로 정규화되어야 합니다. 각 URI는 '*' 와일드 카드 문자 하나를 포함할 수 있습니다.

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

  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로 원하는 횟수만큼 다시 시도할 수 있으며 최대 한 번만 성공합니다.

Go

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

gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.csv")
gcsRef.SourceFormat = bigquery.CSV
gcsRef.AutoDetect = true
gcsRef.SkipLeadingRows = 1
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())
}

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');

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

/**
 * 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.csv';

async function loadCSVFromGCSAutodetect() {
  // Imports a GCS file into a table with autodetected schema.

  // Instantiate clients
  const bigqueryClient = new BigQuery();
  const storageClient = new Storage();

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.load
  const metadata = {
    sourceFormat: 'CSV',
    skipLeadingRows: 1,
    autodetect: true,
    location: 'US',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigqueryClient
    .dataset(datasetId)
    .table(tableId)
    .load(storageClient.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;
  }
}
loadCSVFromGCSAutodetect();

PHP

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

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.csv';
$loadConfig = $table->loadFromStorage($gcsUri)->autodetect(true)->skipLeadingRows(1);
$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.autodetect 속성을 True로 설정합니다.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.autodetect = True
job_config.skip_leading_rows = 1
# The source format defaults to CSV, so the line below is optional.
job_config.source_format = bigquery.SourceFormat.CSV
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
load_job = client.load_table_from_uri(
    uri, dataset_ref.table("us_states"), job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

destination_table = client.get_table(dataset_ref.table("us_states"))
print("Loaded {} rows.".format(destination_table.num_rows))

CSV 데이터로 테이블 덮어쓰기

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

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

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

테이블을 덮어쓰는 경우, 스키마는 항상 덮어쓰기됩니다. 테이블을 덮어쓰는 경우에는 스키마 업데이트가 제한되지 않습니다.

콘솔 또는 기본 BigQuery 웹 UI에서 쓰기 환경설정 옵션을 사용하면 소스 파일 또는 쿼리 결과에서 데이터를 로드할 때 수행할 작업을 지정할 수 있습니다. CLI와 API는 다음 옵션을 제공합니다.

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

기본적으로 쓰기 처리가 변경되지 않으면 로드 작업이 테이블에 데이터를 추가합니다. 로드 작업의 데이터로 데이터를 대체하려면 BigQuery 테이블의 데이터를 덮어쓰도록 선택할 수 있습니다.

콘솔

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

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

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

    테이블 만들기

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

    • 다음 항목으로 테이블 만들기에서 원하는 소스 유형을 선택합니다.

    • 소스 필드에서 파일/Cloud Storage 버킷을 찾아보거나 Cloud Storage URI를 입력합니다. BigQuery 웹 UI에서는 URI가 여러 개 포함될 수 없지만 와일드 카드는 지원됩니다. Cloud Storage 버킷은 생성 중인 테이블을 포함하는 데이터세트와 같은 위치에 있어야 합니다.

      파일 선택

    • 파일 형식CSV를 선택합니다.

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

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

      데이터세트 선택

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

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

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

    • 다음과 같이 스키마 정보를 직접 입력합니다.

      • 텍스트로 수정을 사용 설정하고 테이블 스키마를 JSON 배열로 입력합니다.

      • 필드 추가를 사용하여 스키마를 수동으로 입력합니다.

  7. 고급 옵션 섹션에서 쓰기 환경설정비어 있으면 쓰기, 테이블에 추가 또는 테이블 덮어쓰기를 선택합니다.

    데이터세트 보기

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

기본 UI

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

  2. 탐색 패널에서 마우스로 데이터세트를 가리키고 아래쪽 화살표 아이콘 아래쪽 화살표 아이콘 이미지을 클릭한 후 새 테이블 만들기를 클릭합니다. 데이터를 로드하는 프로세스는 빈 테이블을 만드는 프로세스와 동일합니다.

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

    • 위치에서 Cloud Storage를 선택하고 소스 필드에 Cloud Storage URI를 입력합니다. UI에서는 URI가 여러 개 포함될 수 없지만 와일드 카드는 지원됩니다. Cloud Storage 버킷은 추가하거나 덮어쓰는 테이블을 포함하는 데이터세트와 같은 위치에 있어야 합니다.
    • 파일 형식에는 쉼표로 구분된 값(CSV)을 선택합니다.
  4. 테이블 만들기 페이지의 대상 테이블 섹션에서 다음을 수행합니다.

    • 테이블 이름으로 적당한 데이터세트를 선택하고 테이블 이름 필드에 추가하거나 덮어쓰는 테이블의 이름을 입력합니다.
    • 테이블 유형기본 테이블로 설정되어 있는지 확인합니다.
  5. 스키마 섹션에 스키마 정의를 입력합니다.

    • CSV 파일의 경우 자동 감지 옵션을 선택하면 스키마 자동 감지를 사용할 수 있습니다.

      자동 감지 링크

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

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

        스키마를 JSON 배열로 추가

      • 필드 추가를 사용하여 스키마를 수동으로 입력합니다.

        필드 추가를 사용하여 스키마 추가

  6. 옵션 섹션의 쓰기 환경설정에서 비어 있으면 쓰기, 테이블에 추가 또는 테이블 덮어쓰기를 선택합니다.

    필드 추가를 사용하여 스키마 추가

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

명령줄

테이블을 덮어쓰려면 bq load 명령어를 --replace 플래그와 함께 입력합니다. --location 플래그를 지정하고 값을 사용자 위치로 설정합니다. --noreplace 플래그를 사용하여 데이터를 테이블에 추가합니다. 플래그를 지정하지 않으면 기본값은 데이터 추가가 됩니다.

데이터를 추가하거나 덮어쓸 때 --schema_update_option 플래그를 이용해 새 데이터의 스키마로 대상 테이블의 스키마를 업데이트할 수 있습니다. 다음 옵션을 --schema_update_option 플래그와 함께 사용할 수 있습니다.

  • ALLOW_FIELD_ADDITION: 새 필드를 스키마에 추가합니다. 새 필드는 REQUIRED가 될 수는 없습니다.
  • ALLOW_FIELD_RELAXATION: 필수 입력란을 nullable로 완화합니다. 값 목록을 지정하려면 이 옵션을 반복하세요.
bq --location=[LOCATION] load --[no]replace [DATASET].[TABLE] [PATH_TO_SOURCE] [SCHEMA]

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

  • [LOCATION]은 사용자의 위치입니다. --location 플래그는 선택사항입니다. .bigqueryrc 파일을 사용하여 위치 기본값을 설정할 수 있습니다.
  • [DATASET]는 기존 데이터세트입니다.
  • [TABLE]은 데이터를 로드하는 테이블의 이름입니다.
  • [PATH_TO_SOURCE]는 정규화된 Cloud Storage URI 또는 쉼표로 구분된 URI 목록이며 와일드 카드도 지원됩니다.
  • [SCHEMA]는 유효한 스키마입니다. 스키마는 로컬 JSON 파일일 수도 있고 명령어의 일부로 인라인으로 입력해도 됩니다. 스키마 정의를 제공하는 대신 --autodetect 플래그를 사용할 수도 있습니다.

또한 BigQuery가 CSV 데이터를 파싱하는 방법을 제어할 수 있는 CSV 옵션의 플래그를 추가할 수 있습니다. 예를 들어 --skip_leading_rows 플래그를 사용하면 CSV 파일의 헤더 행을 무시하고, --encoding 플래그를 사용하면 데이터의 문자 인코딩을 확인할 수 있습니다.

예:

  • 다음 명령어는 gs://mybucket/mydata.csv에서 데이터를 로드하여 mydataset에 있는 mytable라는 이름의 테이블을 덮어씁니다. 스키마는 스키마 자동 감지를 이용하여 정의됩니다. mybucketmydatasetUS 다중 리전 위치에서 생성되었습니다.

    bq --location=US load --autodetect --replace --source_format=CSV mydataset.mytable gs://mybucket/mydata.csv
    
  • 다음 명령어는 gs://mybucket/mydata.csv에서 데이터를 로드하여 mydataset에 있는 mytable이라는 이름의 테이블에 데이터를 추가합니다. 스키마는 JSON 스키마 파일인 myschema.json을 이용해 정의됩니다. mybucketmydatasetUS 다중 지역 위치에서 생성되었습니다.

    bq --location=US load --autodetect --noreplace --source_format=CSV mydataset.mytable gs://mybucket/mydata.csv ./myschema.json
    
  • 다음 명령어는 gs://mybucket/mydata.csv에서 데이터를 로드하여 mydataset에 있는 mytable이라는 이름의 테이블에 데이터를 추가합니다. myschema.json이라는 이름의 로컬 JSON 스키마 파일을 사용합니다. 스키마 정의는 대상 테이블에는 없는 새 필드가 포함됩니다. mybucketmydatasetasia-northeast1 지역에서 생성되었습니다.

    bq --location=asia-northeast1 load --noreplace --schema_update_option=ALLOW_FIELD_ADDITION --source_format=CSV mydataset.mytable gs://mybucket/mydata.csv ./myschema.json
    
  • 다음 명령어는 gs://mybucket/mydata.csv에서 데이터를 로드하여 mydataset에 있는 mytable이라는 이름의 테이블에 데이터를 추가합니다. myschema.json이라는 이름의 로컬 JSON 스키마 파일을 사용합니다. 스키마 정의는 두 가지 REQUIRED 필드를 NULLABLE로 변경(완화)합니다. mybucketmydatasetasia-northeast1 지역에서 생성되었습니다.

    bq --location=asia-northeast1 load --noreplace --schema_update_option=ALLOW_FIELD_RELAXATION --source_format=CSV mydataset.mytable gs://mybucket/mydata.csv ./myschema.json
    

API

API를 사용하여 CSV 데이터를 로드하려면 다음 속성을 설정하세요.

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

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

  3. 소스 URI는 gs://[BUCKET]/[OBJECT] 형식으로 정규화되어야 합니다. 여러 URI를 쉼표로 구분된 목록으로 포함할 수 있습니다. Cloud Storage에서 CSV 데이터 로드 시 와일드 카드도 지원됩니다.

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

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

  6. 로드 작업의 스키마를 업데이트하려면 configuration.load.schemaUpdateOptions 속성을 ALLOW_FIELD_ADDITION 또는 ALLOW_FIELD_RELAXATION으로 설정합니다.

Go

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

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.csv")
gcsRef.SourceFormat = bigquery.CSV
gcsRef.AutoDetect = true
gcsRef.SkipLeadingRows = 1
loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
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())
}

Node.js

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

기존 테이블의 행을 바꾸려면 metadata 매개변수의 writeDisposition 값을 'WRITE_TRUNCATE'로 설정합니다.

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

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

/**
 * 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.csv';

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

  // Instantiate clients
  const bigqueryClient = new BigQuery();
  const storageClient = new Storage();

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.load
  const metadata = {
    sourceFormat: 'CSV',
    skipLeadingRows: 1,
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
      ],
    },
    // 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 bigqueryClient
    .dataset(datasetId)
    .table(tableId)
    .load(storageClient.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;
  }
}
loadCSVFromGCSTruncate();

PHP

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

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.csv';
$loadConfig = $table->loadFromStorage($gcsUri)->skipLeadingRows(1)->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 참조 문서를 확인하세요.

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

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('existing_table')

job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_TRUNCATE
job_config.skip_leading_rows = 1
# The source format defaults to CSV, so the line below is optional.
job_config.source_format = bigquery.SourceFormat.CSV
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
load_job = client.load_table_from_uri(
    uri, table_ref, job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

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

CSV 옵션

BigQuery가 CSV 데이터를 파싱하는 방법을 변경하려면 Console, 기본 UI, CLI 또는 API에 추가 옵션을 지정합니다. CSV 형식에 대한 자세한 내용은 RFC 4180을 참조하세요.

CSV 옵션 콘솔 옵션 기본 UI 옵션 CLI 플래그 BigQuery API 속성 설명
필드 구분 기호 필드 구분 기호: 쉼표, 탭, 파이프, 커스텀 필드 구분 기호: 쉼표, 탭, 파이프, 기타 -F 또는 --field_delimiter fieldDelimiter (선택사항) CSV 파일의 필드 구분 기호입니다. CSV 파일의 구분 기호는 ISO-8859-1 단일 바이트의 어떤 문자도 될 수 있습니다. 128~255 범위의 문자를 사용하려면 문자를 UTF-8로 인코딩해야 합니다. BigQuery는 문자열을 ISO-8859-1 인코딩으로 변환하고 인코딩된 문자열의 첫 번째 바이트를 사용해 데이터를 원시 바이너리 상태로 분할합니다. BigQuery는 이스케이프 문자 시퀀스 '\t'로 탭 구분 기호를 지정할 수 있습니다. 기본값은 쉼표(`,`)입니다.
헤더 행 건너뛸 헤더 행 건너뛸 헤더 행 --skip_leading_rows skipLeadingRows (선택사항) 소스 데이터의 헤더 행 수를 나타내는 정수입니다.
허용된 불량 레코드 수 허용되는 오류 개수 허용되는 오류 개수 --max_bad_records maxBadRecords (선택사항) 작업을 실행할 때 BigQuery가 무시할 수 있는 불량 레코드의 최대 개수입니다. 불량 레코드의 수가 이 값을 초과하면 작업 결과에 잘못된 오류가 반환됩니다. 기본값은 0이며 모든 레코드가 유효해야 합니다.
줄바꿈 문자 따옴표 안에 줄바꿈 허용 따옴표 안에 줄바꿈 허용 --allow_quoted_newlines allowQuotedNewlines (선택사항) CSV 파일에서 따옴표 안에 줄바꿈 문자가 포함된 데이터 섹션을 허용할지 여부를 표시합니다. 기본값은 false입니다.
커스텀 null 값 없음 없음 --null_marker nullMarker (선택사항) CSV 파일의 null 값을 나타내는 문자열을 지정합니다. 예를 들어 '\N'을 지정하면 BigQuery는 CSV 파일을 로드할 때 '\N'을 null 값으로 지정합니다. 기본값은 빈 문자열입니다. 이 속성을 커스텀 값으로 설정했을 때 STRING과 BYTE를 제외한 모든 데이터 유형에 빈 문자열이 존재하면 BigQuery에서 오류가 발생합니다. BigQuery는 STRING과 BYTE 열의 빈 문자열을 빈 값으로 해석합니다.
후행 선택 열 불균일 행 허용 불균일 행 허용 --allow_jagged_rows allowJaggedRows (선택사항) 뒤에 오는 선택적인 열이 누락된 행을 허용합니다. 누락된 값은 null로 취급됩니다. false라면 뒤에 오는 열이 누락된 레코드가 불량 레코드로 취급되고, 불량 레코드가 너무 많다면 작업 결과에 잘못된 오류가 반환됩니다. 기본값은 false입니다. CSV에만 적용되며 다른 형식에서는 무시됩니다.
알 수 없는 값 알 수 없는 값 무시 알 수 없는 값 무시 --ignore_unknown_values ignoreUnknownValues (선택사항) BigQuery가 테이블 스키마에 표시되지 않는 추가 값을 허용해야 하는지를 나타냅니다. true라면 추가 값은 무시됩니다. false라면 추가 열이 있는 레코드는 불량 레코드로 처리되며 불량 레코드가 너무 많다면 작업 결과에 잘못된 오류가 반환됩니다. 기본값은 false입니다. sourceFormat 속성은 BigQuery가 추가 값으로 처리하는 대상을 결정합니다.
  • CSV: 후행 열
  • JSON: 어떠한 열 이름과도 일치하지 않는 이름이 지정된 값으로 처리하는 대상을 결정합니다.
따옴표 없음 없음 --quote quote (선택사항) CSV 파일에서 데이터 섹션을 인용하는 데 사용하는 값입니다. BigQuery는 문자열을 ISO-8859-1 인코딩으로 변환하고 인코딩된 문자열의 첫 번째 바이트를 사용해 데이터를 원시 바이너리 상태로 분할합니다. 기본값은 큰 따옴표('"')입니다. 데이터에 인용된 섹션이 없다면 속성 값을 빈 문자열로 설정합니다. 데이터에 줄바꿈 문자가 있다면 allowQuotedNewlines 속성을 true로 설정해야 합니다.
인코딩 없음 없음 -E 또는 --encoding encoding (선택사항) 데이터의 문자 인코딩입니다. 지원되는 값은 UTF-8 또는 ISO-8859-1입니다. 기본값은 UTF-8입니다. BigQuery는 원시 바이너리 데이터가 quotefieldDelimiter 속성 값으로 분할되면 데이터를 디코딩합니다.
이 페이지가 도움이 되었나요? 평가를 부탁드립니다.

다음에 대한 의견 보내기...

도움이 필요하시나요? 지원 페이지를 방문하세요.