テーブルデータの管理

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

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

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

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

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

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

• Cloud Storage からのデータの読み込みの詳細については、以下をご覧ください。

  • Avro データの読み込み
  • CSV データの読み込み
  • JSON データの読み込み
  • Parquet データの読み込み
  • ORC データの読み込み
  • Datastore エクスポートからのデータの読み込み
  • Firestore エクスポートからのデータの読み込み

• ローカルソースからのデータの読み込みの詳細については、ローカルデータ ソースから BigQuery へのデータの読み込みをご覧ください。

テーブルデータの閲覧

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

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

必要な権限

テーブルとパーティションのデータを閲覧するには、少なくとも bigquery.tables.getData 権限が付与されている必要があります。次の事前定義済みの IAM ロールには bigquery.tables.getData 権限が含まれています。

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

また、bigquery.datasets.create 権限を持つユーザーがデータセットを作成すると、そのデータセットに対する bigquery.dataOwner アクセス権がユーザーに付与されます。bigquery.dataOwner アクセス権により、ユーザーはデータセットに含まれるテーブルとパーティションのデータを閲覧できます。

BigQuery での IAM のロールと権限について詳しくは、事前定義されたロールと権限をご覧ください。

テーブルデータの閲覧

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

Console

1. Cloud Console で [BigQuery] ページを開きます。

   [BigQuery] ページに移動

2. ナビゲーション パネルの [リソース] セクションでプロジェクトを展開し、データセットを選択します。これにより、データセット内のテーブルとビューが表示されます。

3. リスト内のテーブルを 1 つクリックします。

4. [詳細] をクリックし、[行数] の値を書き留めます。bq コマンドライン ツールまたは API を使用して結果の開始点を制御するために、この値が必要になる場合があります。

5. [Preview] をクリックします。データのサンプルセットが表示されます。

   

従来の UI

1. BigQuery ウェブ UI のナビゲーション パネルで、データセットの左側にある青色の矢印をクリックして展開するか、データセット名をダブルクリックします。これにより、データセット内のテーブルとビューが表示されます。

2. リスト内のテーブルを 1 つクリックします。

3. [Details] をクリックし、[Number of Rows] の値を書き留めます。bq コマンドライン ツールまたは API を使用して結果の開始点を制御するために、この値が必要になる場合があります。

4. [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 "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.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 - 読み取りを開始する行を指し示す、ゼロから始まるインデックス。

注: 最後の行を超える startIndex をリクエストすると、メソッドは正常に返されますが、rows プロパティは返されません。テーブル内の行数を確認するには、tables.get メソッドを呼び出して、numRows プロパティを調べます。

値は 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 用の Cloud クライアント ライブラリでは、デフォルトで自動的にページ分けされるため、ページ分けを自分で実装する必要はありません。次に例を示します。

GitHub で表示 フィードバック

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
}

Java

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

GitHub で表示 フィードバック

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQuery.TableDataListOption;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableResult;

// Sample to directly browse a table with optional paging
public class BrowseTable {

  public static void runBrowseTable() {
    // TODO(developer): Replace these variables before running the sample.
    String table = "MY_TABLE_NAME";
    String dataset = "MY_DATASET_NAME";
    browseTable(dataset, table);
  }

  public static void browseTable(String dataset, String table) {
    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();

      // Identify the table itself
      TableId tableId = TableId.of(dataset, table);

      // Page over 100 records. If you don't need pagination, remove the pageSize parameter.
      TableResult result = bigquery.listTableData(tableId, TableDataListOption.pageSize(100));

      // Print the records
      result
          .iterateAll()
          .forEach(
              row -> {
                row.forEach(fieldValue -> System.out.print(fieldValue.toString() + ", "));
                System.out.println();
              });

      System.out.println("Query ran successfully");
    } catch (BigQueryException e) {
      System.out.println("Query failed to run \n" + e.toString());
    }
  }
}

Node.js

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。

Node.js 用の Cloud クライアント ライブラリでは、デフォルトで自動的にページ分けされるため、ページ分けを自分で実装する必要はありません。次に例を示します。

GitHub で表示 フィードバック

// 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 用の 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

# 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 用 Cloud クライアント ライブラリで 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 はユーザーに代わって各バッチクエリをキューに格納し、アイドル状態のリソースが使用可能になると直ちに（通常は数分以内に）クエリを開始します。

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

• Cloud Console の [クエリを新規作成] オプション
• bq コマンドライン ツールの bq query コマンド
• プログラムによって jobs.query メソッドまたはクエリ形式の jobs.insert メソッドを呼び出す BigQuery REST API
• BigQuery クライアント ライブラリ

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

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

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

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

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

• Avro データをテーブルに追加または上書きする
• CSV データをテーブルに追加、または CSV データでテーブルを上書きする
• JSON データをテーブルに追加または上書きする
• Parquet データでテーブルに追加または上書きする
• ORC データをテーブルに追加または上書きする
• Datastore データをテーブルに追加または上書きする
• ローカル ファイルを使用してテーブルに追加または上書きする

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

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

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

テーブルデータの変更

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

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

テーブルデータのコピー

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

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

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

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

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

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

次のステップ

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