テーブルデータの管理

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

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

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

始める前に

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

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

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

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

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

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

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

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

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

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

次のクエリを使用して、1 つのテーブルから別のテーブルにレコードを追加できます。

  INSERT INTO <projectID>.<datasetID>.<table1> (
    <column2>,
    <column3>) (SELECT * FROM <projectID>.<datasetID>.<table2>)

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

テーブルデータの閲覧

テーブルデータは次の方法で閲覧または読み取ることができます。

Google 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 のロールと権限については、事前定義ロールと権限をご覧ください。

テーブルデータの閲覧

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

コンソール

Google Cloud コンソールで、[BigQuery] ページを開きます。

[BigQuery] に移動
[エクスプローラ] パネルでプロジェクトを開いて、データセットを選択します。
リスト内のテーブルを 1 つクリックします。
[詳細] をクリックし、[行数] の値を書き留めます。bq コマンドラインツールまたは API を使用して結果の開始点を制御する際に、この値が必要になることがあります。
[プレビュー] をクリックします。データのサンプルセットが表示されます。

コマンドライン

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

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

C#

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアントライブラリの認証情報を設定するをご覧ください。


using Google.Api.Gax;
using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;
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 クライアントライブラリでは、デフォルトで自動的にページ分けされるため、ページ分けを自分で実装する必要はありません。次に例を示します。

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

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


// 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 を使用すると、ページ分割が自動的に行われます。この関数はイテレーション中に結果の次のページをフェッチします。

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 用 Cloud クライアントライブラリで Table#data と Data#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 テーブルに書き込むか、Bigtable または Pub/Sub にエクスポートできます。この機能を使用すると、分析情報の作成と即時対応、リアルタイムの ML 推論の適用、イベントドリブンデータパイプラインの構築など、時間的制約があるタスクを実行できます。

クエリジョブは、次の方法で実行できます。

Google Cloud コンソールでクエリを作成して実行します。
bq コマンドラインツールで bq query コマンドを実行します。
プログラマティックな方法で BigQuery REST API の jobs.query または jobs.insert メソッドを呼び出します。
BigQuery クライアントライブラリを使用します。

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

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

テーブルデータの変更

SQL のデータ操作言語（DML）ステートメントを使用して、テーブルのデータを変更できます。DML ステートメントによって、テーブルの行を更新、マージ、挿入、削除できます。それぞれの種類の DML ステートメントの構文リファレンスと例については、GoogleSQL のデータ操作言語ステートメントをご覧ください。

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

テーブルデータのコピー

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

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

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

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

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

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

テーブルのセキュリティ

BigQuery でテーブルへのアクセスを制御するには、IAM を使用してリソースへのアクセスを制御するをご覧ください。

次のステップ

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