テーブルデータの管理

このドキュメントでは、BigQuery でテーブルデータを管理する方法について説明します。BigQuery テーブルデータは、次の方法で操作できます。

テーブルにデータを読み込む
テーブルデータを参照（またはプレビュー）する
テーブルデータをクエリする
テーブルデータを追加または上書きする
データ操作言語を使用してテーブルデータを変更する
テーブルデータをコピーする
テーブルデータをエクスポートする

テーブルスキーマの管理については、テーブルスキーマの変更をご覧ください。

テーブルへのデータの読み込み

テーブルを作成するときにデータを読み込むことも、空のテーブルを作成して、後でデータを読み込むこともできます。データを読み込むときに、サポートされているデータ形式であれば、スキーマの自動検出を使用できます。またはスキーマを指定することもできます。

データの読み込みの詳細については、ソースデータの形式とロケーションに関するドキュメントをご覧ください。

Cloud Storage からのデータの読み込みの詳細については、以下を参照してください。
ローカルソースからのデータの読み込みの詳細については、ローカルデータソースから BigQuery へのデータの読み込みをご覧ください。

テーブルデータの閲覧

次の方法でテーブルデータを閲覧できます。

GCP Console または従来の BigQuery ウェブ UI を使用する
コマンドラインツールの bq head コマンドを使用する
tabledata.list API メソッドを呼び出す

必要な権限

データセットレベルでは、テーブルデータを閲覧するには閲覧対象のテーブルを含むデータセットへの READER アクセス権が必要です。

データセットレベルの権限を使用する代わりに、bigquery.tables.getData 権限を含むプロジェクトレベルの IAM 役割を利用できます。事前定義されているプロジェクトレベルの IAM 役割のうち、bigquery.user、bigquery.jobUser、bigquery.metadataViewer 以外の役割にはすべて bigquery.tables.getData 権限が含まれています。

さらに、bigquery.user 役割には bigquery.datasets.create 権限があるので、bigquery.user 役割に割り当てられたユーザーは、ユーザーが作成するすべてのデータセット内のすべてのテーブルのデータを読み取ることができます。bigquery.user 役割に割り当てられたユーザーがデータセットを作成すると、そのユーザーにはデータセットへの OWNER アクセス権が与えられます。データセットへの OWNER アクセス権が付与されたユーザーは、そのデータセットと、そこに含まれるすべてのテーブルを完全に制御できます。

BigQuery での IAM 役割と権限の詳細については、アクセス制御をご覧ください。データセットレベルの役割の詳細については、データセットに対する基本の役割をご覧ください。

テーブルデータの閲覧

テーブルデータを閲覧するには:

Console

GCP Console で BigQuery ウェブ UI を開きます。
BigQuery ウェブ UI に移動
ナビゲーションパネルの [リソース] セクションでプロジェクトを展開し、データセットを選択します。これにより、データセット内のテーブルとビューが表示されます。
リスト内のテーブルを 1 つクリックします。
[詳細] をクリックし、[行数] の値を書き留めます。CLI または API を使って結果の開始点を制御するには、この値が必要になることがあります。
[Preview] をクリックします。データのサンプルセットが表示されます。

従来の UI

BigQuery ウェブ UI のナビゲーションペインで、データセットの左側にある青色の矢印をクリックして展開するか、データセット名をダブルクリックします。これにより、データセット内のテーブルとビューが表示されます。
リスト内のテーブルを 1 つクリックします。
[Details] をクリックし、[Number of Rows] の値を書き留めます。CLI または API を使って結果の開始点を制御するには、この値が必要になることがあります。
[Preview] をクリックします。データのサンプルセットが表示されます。

コマンドライン

--max_rows フラグを使用して bq head コマンドを実行すると、特定の数のテーブル行のすべてのフィールドが一覧表示されます。--max_rows が指定されていない場合、デフォルトは 100 です。

テーブル内のフィールドのサブセット（ネストしたフィールドと繰り返しフィールドを含む）を閲覧するには、--selected_fields フラグを使用して、カンマ区切りリストとしてフィールドを入力します。

テーブルデータを表示する前にスキップする行数を指定するには、--start_row=[INTEGER] フラグ（または -s ショートカット）を使用します。デフォルト値は 0 です。テーブルの行数を取得するには、bq show コマンドを使用してテーブル情報を取得します。

閲覧しているテーブルがデフォルトのプロジェクト以外のプロジェクトにある場合は、[PROJECT_ID]:[DATASET].[TABLE] の形式でプロジェクト ID をコマンドに追加します。

bq head --max_rows [INTEGER1] --start_row [INTEGER2] --selected_fields "[FIELDS]" [PROJECT_ID]:[DATASET].[TABLE]

ここで

[INTEGER1] は、表示する行数です。
[INTEGER2] は、データを表示する前にスキップする行数です。
[FIELDS] は、フィールドのカンマ区切りのリストです。
[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.mytable 内の field1 と field2 のみを表示するには、次のコマンドを入力します。コマンドは --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 - 読み取りを開始する行を指し示す、ゼロから始まるインデックス。

値は 1 つの JSON オブジェクトにラップされて返されます。このオブジェクトを、tabledata.list リファレンスドキュメントに記載されている方法で解析する必要があります。

C#

このサンプルを試す前に、BigQuery クイックスタート: クライアントライブラリの使用にある C# 向けの手順に従って設定を行ってください。詳細については、BigQuery C# API のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック

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 クライアントライブラリでは、デフォルトで自動的に結果のページが分割されるので、ページ分割のためのコードを記述する必要はありません。次に例を示します。

GitHub で表示フィードバック

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.Println(row)
}

Java

このサンプルを試す前に、BigQuery クイックスタート: クライアントライブラリの使用にある Java 向けの手順に従って設定を行ってください。詳細については、BigQuery Java API のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック

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 クライアントライブラリでは、デフォルトで自動的に結果のページが分割されるので、ページ分割のためのコードを記述する必要はありません。次に例を示します。

GitHub で表示フィードバック

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

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

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

  // Create a client
  const bigqueryClient = new BigQuery();

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

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

browseRows();

PHP

このサンプルを試す前に、BigQuery クイックスタート: クライアントライブラリの使用にある PHP 向けの手順に従って設定を行ってください。詳細については、BigQuery PHP API のリファレンスドキュメントをご覧ください。

PHP 用の Google Cloud クライアントライブラリでジェネレータ関数 rows を使用すると、ページが自動的に分割されます。この関数は反復処理中に次の結果ページをフェッチします。

GitHub で表示フィードバック

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 のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック

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

dataset_ref = client.dataset("samples", project="bigquery-public-data")
table_ref = dataset_ref.table("shakespeare")
table = client.get_table(table_ref)  # API call

# Load all rows from a table
rows = client.list_rows(table)
assert len(list(rows)) == table.num_rows

# Load the first 10 rows
rows = client.list_rows(table, max_results=10)
assert len(list(rows)) == 10

# Specify selected fields to limit the results to certain columns
fields = table.schema[:2]  # first two columns
rows = client.list_rows(table, selected_fields=fields, max_results=10)
assert len(rows.schema) == 2
assert len(list(rows)) == 10

# Use the start index to load an arbitrary portion of the table
rows = client.list_rows(table, start_index=10, max_results=10)

# Print row data in tabular format
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 のリファレンスドキュメントをご覧ください。

Google Cloud Client Library for Ruby の Table#data と Data#next ではページが自動的に分割されます。

GitHub で表示フィードバック

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 は次の 2 種類のクエリをサポートします。

インタラクティブクエリ
バッチクエリ

デフォルトで、BigQuery はインタラクティブ クエリを実行します。つまり、クエリはすぐに実行されます。

BigQuery ではバッチクエリも提供されています。BigQuery はユーザーに代わって各バッチクエリをキューに格納し、アイドル状態のリソースが使用可能になると直ちに（通常は数分以内に）クエリを開始します。

以下を使用して、インタラクティブクエリとバッチクエリを実行できます。

コンソールのクエリエディタ
BigQuery ウェブ UI の [クエリを作成] オプション
BigQuery コマンドラインツールの bq query コマンド
プログラム手法で jobs.query またはクエリタイプ jobs.insert メソッドを呼び出すための BigQuery REST API
BigQuery クライアントライブラリ

BigQuery テーブルのクエリの詳細については、BigQuery データのクエリの概要をご覧ください。

BigQuery テーブルに格納されたデータをクエリするだけでなく、外部に保存されたデータをクエリすることもできます。詳細については、外部データソースへのクエリの実行をご覧ください。

テーブルデータの追加と上書き

読み込みまたはクエリオペレーションを使用してテーブルデータを上書きできます。既存のテーブルにデータを追加するには、読み込み追加オペレーションを実行するか、クエリ結果をテーブルに追加します。

データの読み込み時にテーブルに追加するか、上書きする方法の詳細については、ソースデータ形式のドキュメントを参照してください。

クエリ結果を使用して、テーブルに追加または上書きするには、宛先のテーブルを指定し、次のいずれかに書込み処理を設定します。

Append to table - クエリ結果を既存のテーブルに追加します。
Overwrite table - クエリ結果を既存のテーブルに同じ名前で上書きします。

クエリ結果を使用してデータを追加または上書きする方法の詳細については、クエリ結果の書き込みをご覧ください。

テーブルデータの変更

標準 SQL 言語を使用すると、DML ステートメントを使用してテーブル内のデータを変更できます。DML ステートメントを使用すると、行の一括更新、挿入、および削除を実行できます。DML の使用例については、データ操作言語を使用したテーブルデータの更新をご覧ください。

従来の SQL 言語は DML ステートメントをサポートしていません。従来の SQL を使用してデータを更新または削除するには、テーブルを削除してから、新しいデータでテーブルを再作成する必要があります。または、データを変更し、クエリ結果を新しい宛先テーブルに書き込むクエリを記述することもできます。

テーブルデータのコピー

次の方法でテーブルをコピーできます。

GCP Console または従来の BigQuery ウェブ UI を使用する
コマンドラインツールの bq cp コマンドを使用する
jobs.insert API メソッドを呼び出してコピージョブを構成する

テーブルのコピーの詳細については、テーブルのコピーをご覧ください。

テーブルデータのエクスポート

テーブルデータは、CSV、JSON、Avro 形式でエクスポートできます。現在のところ、データを Cloud Storage バケットにエクスポートする必要があります。ローカルマシンへのエクスポートはサポートされていません。ただし GCP Console または従来の BigQuery ウェブ UI を使用してクエリ結果をダウンロードして保存できます。

詳細については、テーブルデータのエクスポートをご覧ください。

次のステップ

データの読み込みの詳細については、データの読み込みの概要をご覧ください。
データのクエリの詳細については、BigQuery データのクエリの概要をご覧ください。
テーブルスキーマの変更の詳細については、テーブルスキーマの変更をご覧ください。
テーブルの作成と使用の詳細については、テーブルの作成と使用をご覧ください。
テーブルの管理の詳細については、テーブルの管理をご覧ください。

テーブルへのデータの読み込み

テーブルデータの閲覧

必要な権限

テーブルデータの閲覧

Console

従来の UI

コマンドライン

API

C#

Go

Java

Node.js

PHP

Python

Ruby

テーブルデータのクエリ

テーブルデータの追加と上書き

テーブルデータの変更

テーブルデータのコピー

テーブルデータのエクスポート

次のステップ

フィードバックを送信...