테이블 데이터 관리

이 문서에서는 BigQuery에서 테이블 데이터를 관리하는 방법을 설명합니다. BigQuery 테이블 데이터에 할 수 있는 작업은 다음과 같습니다.

  • 테이블에 데이터 로드
  • 테이블 데이터 찾아보기(또는 미리보기)
  • 테이블 데이터 쿼리
  • 테이블에 데이터 추가 또는 테이블 데이터 덮어쓰기
  • DML을 사용하여 테이블 데이터 수정
  • 테이블 데이터 복사
  • 테이블 데이터 내보내기

테이블 스키마 관리에 대한 자세한 내용은 테이블 스키마 수정을 참조하세요.

테이블에 데이터 로드

테이블을 만들 때 데이터를 로드하거나, 빈 테이블을 만든 후 나중에 데이터를 로드할 수 있습니다. 데이터를 로드할 때는 지원되는 데이터 형식에 스키마 자동 감지를 사용하거나 스키마를 직접 지정할 수 있습니다.

데이터 로드에 자세한 내용은 소스 데이터 형식 및 위치에 대한 문서를 참조하세요.

테이블 데이터 찾아보기

다음과 같은 방법으로 테이블 데이터를 찾아볼 수 있습니다.

  • Cloud Console 또는 기본 BigQuery 웹 UI 사용
  • 명령줄 도구의 bq head 명령어 사용
  • tabledata.list API 메서드 호출
  • 클라이언트 라이브러리 사용

필수 권한

테이블 및 파티션 데이터를 찾아보려면 최소한 bigquery.tables.getData 권한이 있어야 합니다. 다음과 같은 사전 정의된 Cloud IAM 역할에는 bigquery.tables.getData 권한이 포함되어 있습니다.

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

또한 bigquery.datasets.create 권한이 있는 사용자는 데이터세트를 만들 때 해당 데이터세트에 대한 bigquery.dataOwner 액세스 권한을 부여받습니다. bigquery.dataOwner 액세스 권한이 있는 사용자는 데이터세트에서 테이블과 파티션의 데이터를 찾아볼 수 있습니다.

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

테이블 데이터 찾아보기

테이블 데이터를 찾아보려면 다음 안내를 따르세요.

Console

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

  2. 탐색 패널의 리소스 섹션에서 프로젝트를 펼치고 데이터세트를 선택합니다. 그러면 데이터세트에 있는 테이블과 뷰가 표시됩니다.

  3. 목록에서 테이블을 클릭합니다.

  4. 세부정보를 클릭하고 행 개수 값을 확인합니다. CLI 또는 API를 사용하여 결과의 시작점을 제어하려면 이 값이 필요할 수 있습니다.

  5. 미리보기를 클릭합니다. 샘플 데이터세트가 표시됩니다.

    테이블 미리보기

기본 UI

  1. 기본 BigQuery 웹 UI의 탐색창에서 데이터세트 왼쪽에 있는 파란색 화살표를 클릭하여 데이터세트를 확장하거나 데이터세트 이름을 더블클릭합니다. 그러면 데이터세트에 있는 테이블과 뷰가 표시됩니다.

  2. 목록에서 테이블을 클릭합니다.

  3. 세부정보를 클릭하고 행 개수 값을 확인합니다. CLI 또는 API를 사용하여 결과의 ​​시작점을 제어하려면 이 값이 필요할 수 있습니다.

  4. 미리보기를 클릭합니다. 샘플 데이터세트가 표시됩니다.

    테이블 미리보기

명령줄

특정 수의 테이블 행에 있는 모든 열을 나열하려면 bq head 명령어를 --max_rows 플래그와 함께 실행합니다. --max_rows를 지정하지 않으면 기본값은 100입니다.

테이블의 일부 열(중첩 열 및 반복 열 포함)을 찾아보려면 --selected_fields 플래그를 사용하고 열을 쉼표로 구분된 목록으로 입력합니다.

테이블 데이터를 표시하기 전에 건너뛸 행 수를 지정하려면 --start_row=integer 플래그(또는 -s 단축키)를 사용합니다. 기본값은 0입니다. bq show 명령어로 테이블 정보를 검색하여 테이블의 행 수를 검색할 수 있습니다.

찾아볼 테이블이 기본 프로젝트가 아닌 다른 프로젝트에 있으면 프로젝트 ID를 project_id:dataset.table 형식으로 명령어에 추가합니다.

bq head \
--max_rows integer1 \
--start_row integer2 \
--selected_fields "columns" \
project_id:dataset.table

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

  • integer1은 표시할 행 수입니다.
  • integer2는 데이터를 표시하기 전에 건너뛸 행 수입니다.
  • columns는 쉼표로 구분된 열 목록입니다.
  • project_id는 프로젝트 ID입니다.
  • dataset는 테이블이 포함된 데이터세트 이름입니다.
  • table은 찾아볼 테이블 이름입니다.

예:

mydataset.mytable에서 처음 10행의 모든 열을 나열하려면 다음 명령어를 입력합니다. 여기서 mydataset는 기본 프로젝트에 있습니다.

bq head --max_rows=10 mydataset.mytable

mydataset.mytable에서 처음 100행의 모든 열을 나열하려면 다음 명령어를 입력합니다. 여기서 mydataset는 기본 프로젝트가 아닌 myotherproject에 있습니다.

bq head myotherproject:mydataset.mytable

mydataset.mytablefield1field2만 표시하려면 다음 명령어를 입력합니다. 이 명령어에서 --start_row 플래그를 사용하면 100번째 행으로 건너뜁니다. 여기서 mydataset.mytable은 기본 프로젝트에 있습니다.

bq head --start_row 100 --selected_fields "field1,field2" mydataset.mytable

bq head 명령어는 쿼리 작업을 만들지 않으므로 bq head 명령어는 쿼리 기록에 나타나지 않고 비용이 청구되지 않습니다.

API

tabledata.list를 호출하여 테이블의 데이터를 찾아볼 수 있습니다. tableId 매개변수에 테이블 이름을 지정하세요.

다음과 같은 선택적 매개변수를 구성하여 출력을 제어할 수 있습니다.

  • maxResults — 반환할 결과의 최대 수입니다.
  • selectedFields — 반환할 필드를 쉼표로 구분한 목록입니다. 지정하지 않으면 모든 열이 반환됩니다.
  • startIndex — 읽기를 시작할 행의 0부터 시작하는 색인입니다.

반환되는 값은 JSON 객체에 래핑되므로 tabledata.list 참조 문서의 설명에 따라 객체를 파싱해야 합니다.

C#

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


using Google.Api.Gax;
using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;
using System.Collections.Generic;
using System.Linq;

public class BigQueryBrowseTable
{
    public void BrowseTable(
        string projectId = "your-project-id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        TableReference tableReference = new TableReference()
        {
            TableId = "shakespeare",
            DatasetId = "samples",
            ProjectId = "bigquery-public-data"
        };
        // Load all rows from a table
        PagedEnumerable<TableDataList, BigQueryRow> result = client.ListRows(
            tableReference: tableReference,
            schema: null
        );
        // Print the first 10 rows
        foreach (BigQueryRow row in result.Take(10))
        {
            Console.WriteLine($"{row["corpus"]}: {row["word_count"]}");
        }
    }
}

Go

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

Go용 Google Cloud 클라이언트 라이브러리는 기본적으로 자동 페이지 나누기를 수행하므로 사용자가 직접 페이지 나누기를 구현할 필요가 없습니다. 예를 들면 다음과 같습니다.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// browseTable demonstrates reading data from a BigQuery table directly without the use of a query.
// For large tables, we also recommend the BigQuery Storage API.
func browseTable(w io.Writer, projectID, datasetID, tableID 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()

	table := client.Dataset(datasetID).Table(tableID)
	it := table.Read(ctx)
	for {
		var row []bigquery.Value
		err := it.Next(&row)
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintln(w, row)
	}
	return nil
}

자바

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

TableId tableIdObject = TableId.of(datasetName, tableName);
// This example reads the result 100 rows per RPC call. If there's no need to limit the number,
// simply omit the option.
TableResult tableData =
    bigquery.listTableData(tableIdObject, TableDataListOption.pageSize(100));
for (FieldValueList row : tableData.iterateAll()) {
  // do something with the row
}

Node.js

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

Node.js용 Google Cloud 클라이언트 라이브러리는 기본적으로 자동 페이지 나누기를 수행하므로 사용자가 직접 페이지 나누기를 구현할 필요가 없습니다. 예를 들면 다음과 같습니다.


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

async function browseRows() {
  // Displays rows from "my_table" in "my_dataset".

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

  // List rows in the table
  const [rows] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .getRows();

  console.log('Rows:');
  rows.forEach(row => console.log(row));
}

PHP

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

PHP용 Google Cloud 클라이언트 라이브러리에서는 생성기 함수 rows를 사용하여 페이지 나누기를 자동으로 수행하고 반복을 통해 다음 결과 페이지를 가져옵니다.

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';
// $maxResults = 10;

$maxResults = 10;
$startIndex = 0;

$options = [
    'maxResults' => $maxResults,
    'startIndex' => $startIndex
];
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
$numRows = 0;
foreach ($table->rows($options) as $row) {
    print('---');
    foreach ($row as $column => $value) {
        printf('%s: %s' . PHP_EOL, $column, $value);
    }
    $numRows++;
}

Python

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


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 browse data rows.
# table_id = "your-project.your_dataset.your_table_name"

# Download all rows from a table.
rows_iter = client.list_rows(table_id)  # Make an API request.

# Iterate over rows to make the API requests to fetch row data.
rows = list(rows_iter)
print("Downloaded {} rows from table {}".format(len(rows), table_id))

# Download at most 10 rows.
rows_iter = client.list_rows(table_id, max_results=10)
rows = list(rows_iter)
print("Downloaded {} rows from table {}".format(len(rows), table_id))

# Specify selected fields to limit the results to certain columns.
table = client.get_table(table_id)  # Make an API request.
fields = table.schema[:2]  # First two columns.
rows_iter = client.list_rows(table_id, selected_fields=fields, max_results=10)
rows = list(rows_iter)
print("Selected {} columns from table {}.".format(len(rows_iter.schema), table_id))
print("Downloaded {} rows from table {}".format(len(rows), table_id))

# Print row data in tabular format.
rows = client.list_rows(table, max_results=10)
format_string = "{!s:<16} " * len(rows.schema)
field_names = [field.name for field in rows.schema]
print(format_string.format(*field_names))  # Prints column headers.
for row in rows:
    print(format_string.format(*row))  # Prints row data.

Ruby

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

Ruby용 Google Cloud 클라이언트 라이브러리에서는 Table#dataData#next를 사용하여 페이지 나누기가 자동으로 수행됩니다.

require "google/cloud/bigquery"

def browse_table
  bigquery = Google::Cloud::Bigquery.new project_id: "bigquery-public-data"
  dataset  = bigquery.dataset "samples"
  table    = dataset.table "shakespeare"

  # Load all rows from a table
  rows = table.data

  # Load the first 10 rows
  rows = table.data max: 10

  # Print row data
  rows.each { |row| puts row }
end

테이블 데이터 쿼리

데이터를 BigQuery에 로드한 후 테이블의 데이터를 쿼리할 수 있습니다. BigQuery는 다음 두 가지 유형의 쿼리를 지원합니다.

기본적으로 BigQuery는 양방향 쿼리를 실행합니다. 즉, 최대한 빨리 쿼리가 실행됩니다.

BigQuery는 일괄 쿼리도 제공합니다. BigQuery는 사용자를 대신하여 각 일괄 쿼리를 대기열에 포함시키고 유휴 리소스가 있으면 바로(대개 몇 분 소요) 쿼리를 시작합니다.

다음을 사용하여 대화형 쿼리와 일괄 쿼리를 실행할 수 있습니다.

BigQuery 테이블 쿼리에 대한 자세한 내용은 BigQuery 데이터 쿼리 소개를 참조하세요.

BigQuery 테이블에 저장된 데이터뿐만 아니라 외부에 저장된 데이터도 쿼리할 수 있습니다. 자세한 내용은 외부 데이터 소스 소개를 참조하세요.

테이블 데이터 추가 및 덮어쓰기

로드 또는 쿼리 작업을 수행하여 테이블 데이터를 덮어쓸 수 있습니다. 로드-추가 작업을 수행하거나 쿼리 결과를 테이블에 추가하여 기존 테이블에 데이터를 추가할 수도 있습니다.

데이터를 로드할 때 테이블 데이터를 추가하거나 덮어쓰는 자세한 방법은 소스 데이터 형식에 대한 다음 문서를 참조하세요.

쿼리 결과를 사용하여 테이블에 데이터를 추가하거나 테이블을 덮어쓰려면 대상 테이블을 지정하고 쓰기 처리를 다음 중 하나로 설정합니다.

  • 테이블에 추가 - 쿼리 결과를 기존 테이블에 추가합니다.
  • 테이블 덮어쓰기 - 쿼리 결과를 사용하여 이름이 같은 기존 테이블을 덮어씁니다.

쿼리 결과를 사용한 데이터 추가 또는 덮어쓰기에 대한 자세한 내용은 쿼리 결과 쓰기를 참조하세요.

테이블 데이터 수정

표준 SQL 방언을 사용하는 경우 DML 문으로 테이블의 데이터를 수정할 수 있습니다. DML 문을 사용하면 일괄 행 업데이트, 삽입 및 삭제를 수행할 수 있습니다. DML을 사용하는 예시는 DML을 사용하여 테이블 데이터 업데이트를 참조하세요.

legacy SQL 언어는 DML 문을 지원하지 않습니다. legacy SQL을 사용하여 데이터를 업데이트하거나 삭제하려면 테이블을 삭제한 다음 새 데이터로 다시 만들어야 합니다. 또는 데이터를 수정하고 쿼리 결과를 새 대상 테이블에 쓰는 쿼리를 작성할 수도 있습니다.

테이블 데이터 복사

다음 방법을 사용하여 테이블을 복사할 수 있습니다.

  • Cloud Console 또는 기본 BigQuery 웹 UI 사용
  • 명령줄 도구의 bq cp 명령어 사용
  • jobs.insert API 메서드 호출 및 copy 작업 구성
  • 클라이언트 라이브러리 사용

테이블 복사에 대한 자세한 내용은 테이블 복사를 참조하세요.

테이블 데이터 내보내기

테이블 데이터를 CSV, JSON 또는 Avro 형식으로 내보낼 수 있습니다. 현재는 데이터를 Cloud Storage 버킷으로 내보내야 합니다. 로컬 머신으로 내보내기는 지원되지 않습니다. 하지만 Cloud Console이나 기본 BigQuery 웹 UI를 사용하여 쿼리 결과를 다운로드하여 저장할 수 있습니다.

자세한 내용은 테이블 데이터 내보내기를 참조하세요.

다음 단계