テーブルデータの管理

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

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

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

始める前に

このドキュメントのタスクを実行するユーザーに必要な権限を付与するロールを付与します。タスクの実行に必要な権限（存在する場合）については、「必要な権限」セクションをご覧ください。

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

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

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

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

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

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

テーブルデータの閲覧

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

• Cloud コンソールの使用
• bq コマンドライン ツールの bq head コマンドを使用する
• tabledata.list API メソッドを呼び出す
• クライアント ライブラリを使用する

必要な権限

テーブルとパーティションのデータを閲覧するには、Identity and Access Management（IAM）権限 bigquery.tables.getData が必要です。

次の IAM 事前定義ロールには、テーブルを参照してデータをパーティション分割するために必要な権限が含まれています。

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

bigquery.datasets.create 権限がある場合、作成したデータセットのテーブルとパーティション内のデータを参照できます。

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

テーブルデータの閲覧

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

Console

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

   BigQuery に移動

2. [エクスプローラ] パネルでプロジェクトを開いて、データセットを選択します。

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

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

5. [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 のデータ操作言語ステートメントをご覧ください。

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

テーブルデータのコピー

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

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

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

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

Cloud Storage バケットに CSV、JSON、Avro、Parquet（プレビュー）形式でテーブルデータをエクスポートできます。ローカルマシンへのエクスポートはサポートされていません。ただし、Cloud Console を使用してクエリ結果をダウンロードして保存できます。

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

テーブルのセキュリティ

BigQuery でテーブルへのアクセスを制御するには、テーブルのアクセス制御の概要をご覧ください。

次のステップ

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