テーブルの作成と使用

このドキュメントでは、BigQuery で標準（組み込み）テーブルを作成して使用する方法について説明します。他のタイプのテーブルを作成する方法については、以下をご覧ください。

• パーティション分割テーブルの作成
• クラスタ化テーブルの作成と使用

テーブルを作成した後は、次の操作を行うことができます。

• テーブルデータへのアクセスを制御する。
• テーブルに関する情報を取得する。
• データセット内のテーブルを一覧表示する。
• テーブルのメタデータを取得する。

テーブルのプロパティの更新、テーブルのコピー、テーブルの削除などのテーブルの管理の詳細については、テーブルの管理をご覧ください。

始める前に

このドキュメントの各タスクを実行するために必要な権限をユーザーに与える Identity and Access Management（IAM）のロールを付与します。

必要なロール

テーブルの作成に必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

• データを読み込んでテーブルを作成する場合、またはクエリ結果をテーブルに保存する場合は、プロジェクトに対する BigQuery ジョブユーザー （roles/bigquery.jobUser）。
• テーブルを作成するデータセットに対する BigQuery データ編集者 （roles/bigquery.dataEditor）。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

これらの事前定義ロールには、テーブルの作成に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

テーブルを作成するには、次の権限が必要です。

• テーブルを作成するデータセットに対する bigquery.tables.create。
• クエリ結果をテーブルとして保存する場合は、クエリが参照するすべてのテーブルとビューに対する bigquery.tables.getData。
• データを読み込んでテーブルを作成する場合、またはクエリ結果をテーブルに保存する場合は、プロジェクトに対する bigquery.jobs.create。
• クエリ結果を使用してテーブルに追加または上書きする場合は、テーブルに対する bigquery.tables.updateData。

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

注: bigquery.datasets.create 権限がある場合は、作成したデータセットにテーブルを作成できます。

テーブルの命名

BigQuery でテーブルを作成するとき、テーブル名はデータセットごとに一意である必要があります。テーブル名の要件は次のとおりです。

• UTF-8 バイトの文字を合計で 1,024 バイト以下にする。
• カテゴリ L（文字）、M（マーク）、N（数字）、Pc（コネクタ、アンダースコアを含む）、Pd（ダッシュ）、Zs（スペース）の Unicode 文字を含む。詳しくは、一般カテゴリをご覧ください。

table 01、ग्राहक、00_お客様、étudiant-01 などが有効なテーブル名です。

注意点:

• テーブル名では、デフォルトで大文字と小文字が区別されます。mytable と MyTable は、大文字と小文字を区別しないデータセットでない限り、同じデータセット内に共存できます。
• 一部のテーブル名とテーブル名の接頭辞は予約済みです。テーブル名または接頭辞が予約されているというエラーが表示された場合は、別の名前を選択して、もう試してください。

• ドット演算子（.）を連続して含めると、重複する演算子が暗黙的に削除されます。

  たとえば、以下は、project_name....dataset_name..table_name

  project_name.dataset_name.table_name のようになります。

テーブルを作成する

BigQuery では、次の方法でテーブルを作成できます。

• Google Cloud コンソールまたは bq コマンドライン ツールの bq mk コマンドを使用して手動で作成する。
• プログラムで tables.insert API メソッドを呼び出して作成する。
• クライアント ライブラリを使用する。
• クエリ結果から作成する。
• 外部データソースを参照するテーブルを定義する。
• データを読み込むときに作成する。
• CREATE TABLE データ定義言語（DDL）ステートメントを使用する。

スキーマ定義を含む空のテーブルを作成する

次の方法でスキーマ定義を含む空のテーブルを作成できます。

• Google Cloud コンソールを使用してスキーマを入力する。
• bq コマンドライン ツールを使用してインラインでスキーマを指定する。
• bq コマンドライン ツールを使用して JSON スキーマ ファイルを送信する。
• API の tables.insert メソッドを呼び出すときに、テーブル リソースでスキーマを指定する。

テーブル スキーマの指定方法については、スキーマの指定をご覧ください。

テーブルを作成した後、そのテーブルへデータを入力するにはデータの読み込みまたはクエリ結果の書き込みを行います。

スキーマ定義を含む空のテーブルを作成するには:

コンソール

1. Google Cloud コンソールで、[BigQuery] ページに移動します。

   [BigQuery] に移動

2. 左側のペインで、 [エクスプローラ] をクリックします。
3. [エクスプローラ] ペインでプロジェクトを開き、[データセット] をクリックして、データセットを選択します。
4. [データセット情報] セクションで、[ テーブルを作成] をクリックします。
5. [テーブルを作成] ペインで、次の詳細を指定します。
1. [ソース] セクションの [テーブルの作成元] リストで [空のテーブル] を選択します。
2. [送信先] セクションで、次の詳細を指定します。
   1. [データセット] で、テーブルを作成するデータセットを選択します。
   2. [テーブル] フィールドに、作成するテーブルの名前を入力します。
   3. [テーブルタイプ] フィールドが [ネイティブ テーブル] に設定されていることを確認します。
3. [スキーマ] セクションでスキーマ定義を入力します。スキーマ情報は、次のいずれかの方法で手動で入力できます。
   • オプション 1: [テキストとして編集] をクリックし、スキーマを JSON 配列の形式で貼り付けます。JSON 配列を使用する場合は、JSON スキーマ ファイルの作成と同じプロセスを使用してスキーマを生成します。既存のテーブルのスキーマを JSON 形式で表示するには、次のコマンドを入力します。

         bq show --format=prettyjson dataset.table
         

   • オプション 2: [フィールドを追加] をクリックして、テーブル スキーマを入力します。各フィールドの名前、型、モードを指定します。
4. 省略可: [パーティションとクラスタの設定] を指定します。詳細については、パーティション分割テーブルの作成とクラスタ化テーブルの作成と使用をご覧ください。
5. 省略可: [詳細オプション] セクションで、顧客管理の暗号鍵を使用する場合は、[顧客管理の暗号鍵（CMEK）を使用] オプションを選択します。デフォルトでは、BigQuery は Google-owned and Google-managed encryption keyを使用して保存されているお客様のコンテンツを暗号化します。
6. [テーブルを作成] をクリックします。

注: Google Cloud コンソールを使用する場合、空テーブルの作成時にラベル、説明、有効期限を追加することはできません。テーブル作成時にこれらのオプションのプロパティを追加するには、bq コマンドライン ツールまたは API を使用します。 Google Cloud コンソールでテーブルを作成した後、有効期限、説明、およびラベルを追加できます。

SQL

次の例では、2023 年 1 月 1 日まで有効の、newtable という名前のテーブルを作成します。

1. Google Cloud コンソールで、[BigQuery] ページに移動します。

   [BigQuery] に移動

2. クエリエディタで次のステートメントを入力します。

   CREATE TABLE mydataset.newtable (
     x INT64 OPTIONS (description = 'An optional INTEGER field'),
     y STRUCT <
       a ARRAY <STRING> OPTIONS (description = 'A repeated STRING field'),
       b BOOL
     >
   ) OPTIONS (
       expiration_timestamp = TIMESTAMP '2023-01-01 00:00:00 UTC',
       description = 'a table that expires in 2023',
       labels = [('org_unit', 'development')]);

3. [実行] をクリックします。

クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. --table または -t フラグを指定した bq mk コマンドを使用します。テーブル スキーマ情報は、インラインで、または JSON スキーマ ファイルを使用して指定できます。パラメータの一覧については、bq mk --table リファレンスをご覧ください。オプション パラメータには、次のようなものがあります。

   • --expiration
   • --description
   • --time_partitioning_field
   • --time_partitioning_type
   • --range_partitioning
   • --clustering_fields
   • --destination_kms_key
   • --label

   --time_partitioning_field、--time_partitioning_type、--range_partitioning、--clustering_fields、--destination_kms_key については、ここでは説明しません。これらのオプション パラメータの詳細については、次のリンクをご覧ください。

   • --time_partitioning_field、--time_partitioning_type、--range_partitioning の詳細については、パーティション分割テーブルをご覧ください。
   • --clustering_fields の詳細については、クラスタ化テーブルをご覧ください。
   • --destination_kms_key の詳細については、顧客管理の暗号鍵をご覧ください。

   デフォルト以外のプロジェクトでテーブルを作成する場合は、project_id:dataset の形式でプロジェクト ID をデータセットに追加します。

   既存のデータセット内にスキーマ定義を持つ空のテーブルを作成するには、以下を入力します。

   bq mk \
   --table \
   --expiration=integer \
   --description=description \
   --label=key_1:value_1 \
   --label=key_2:value_2 \
   --add_tags=key_3:value_3[,...] \
   project_id:dataset.table \
   schema

   次のように置き換えます。

   • integer はテーブルのデフォルトの存続期間（秒）です。最小値は 3,600 秒（1 時間）です。現在の UTC 時間にこの整数値を足した値が、有効期限になります。テーブルの作成時に有効期限を設定した場合、データセットのデフォルトのテーブル有効期限設定は無視されます。
   • description はテーブルの説明です。引用符で囲みます。
   • key_1:value_1 と key_2:value_2 は、ラベルを指定する Key-Value ペアです。
   • key_3:value_3 は、タグを指定する Key-Value ペアです。同じフラグで、各 Key-Value ペアをカンマで区切って複数のタグを追加できます。
   • project_id はプロジェクト ID です。
   • dataset は、プロジェクトのデータセットです。
   • table は、作成するテーブルの名前です。
   • schema は、field:data_type,field:data_type 形式のインライン スキーマ定義、またはローカルマシン上の JSON スキーマ ファイルへのパスです。

   コマンドラインでスキーマを指定する場合、RECORD（STRUCT）型や列の説明を含めることはできません。また、列モードも指定できません。すべてのモードはデフォルトの NULLABLE になります。説明、モード、RECORD 型を含めるには、JSON スキーマ ファイルを指定します。

   例:

   インライン スキーマ定義を使用してテーブルを作成するには、以下のコマンドを入力します。このコマンドは、デフォルト プロジェクトにある mydataset 内に mytable という名前のテーブルを作成します。テーブルの存続期間は 3,600 秒（1 時間）、説明は This is my table、ラベルは organization:development に設定されます。このコマンドでは --table ではなく -t ショートカットを使用しています。スキーマはインラインで qtr:STRING,sales:FLOAT,year:STRING と指定されています。

   bq mk \
    -t \
    --expiration 3600 \
    --description "This is my table" \
    --label organization:development \
    mydataset.mytable \
    qtr:STRING,sales:FLOAT,year:STRING

   次のコマンドを入力し、JSON スキーマ ファイルを使用してテーブルを作成します。このコマンドは、デフォルト プロジェクトにある mydataset 内に mytable という名前のテーブルを作成します。テーブルの存続期間は 3,600 秒（1 時間）、説明は This is my table、ラベルは organization:development に設定されます。スキーマ ファイルのパスは /tmp/myschema.json です。

   bq mk \
    --table \
    --expiration 3600 \
    --description "This is my table" \
    --label organization:development \
    mydataset.mytable \
    /tmp/myschema.json

   JSON スキーマ ファイルを使用してテーブルを作成するには、次のコマンドを入力します。このコマンドは、myotherproject プロジェクトにある mydataset 内に mytable という名前のテーブルを作成します。テーブルの存続期間は 3,600 秒（1 時間）、説明は This is my table、ラベルは organization:development に設定されます。スキーマ ファイルのパスは /tmp/myschema.json です。

   bq mk \
    --table \
    --expiration 3600 \
    --description "This is my table" \
    --label organization:development \
    myotherproject:mydataset.mytable \
    /tmp/myschema.json

   テーブルを作成した後、テーブルの有効期限、説明、ラベルを更新できます。スキーマ定義を変更することもできます。

Terraform

google_bigquery_table リソースを使用します。

注: Terraform を使用して BigQuery オブジェクトを作成するには、Cloud Resource Manager API を有効にする必要があります。

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

テーブルを作成する

次の例では、mytable という名前のテーブルが作成されます。

resource "google_bigquery_dataset" "default" {
  dataset_id                      = "mydataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

resource "google_bigquery_table" "default" {
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "mytable"
  deletion_protection = false # set to "true" in production

  schema = <<EOF
[
  {
    "name": "ID",
    "type": "INT64",
    "mode": "NULLABLE",
    "description": "Item ID"
  },
  {
    "name": "Item",
    "type": "STRING",
    "mode": "NULLABLE"
  }
]
EOF

}

テーブルを作成してアクセス権を付与する

次の例では、mytable という名前のテーブルを作成し、google_bigquery_table_iam_policy リソースを使用してそのテーブルへのアクセス権を付与します。このステップは、テーブルが存在するデータセットへのアクセス権を持たないプリンシパルにテーブルへのアクセス権を付与する場合にのみ行います。

resource "google_bigquery_dataset" "default" {
  dataset_id                      = "mydataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

resource "google_bigquery_table" "default" {
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "mytable"
  deletion_protection = false # set to "true" in production

  schema = <<EOF
[
  {
    "name": "ID",
    "type": "INT64",
    "mode": "NULLABLE",
    "description": "Item ID"
  },
  {
    "name": "Item",
    "type": "STRING",
    "mode": "NULLABLE"
  }
]
EOF

}

data "google_iam_policy" "default" {
  binding {
    role = "roles/bigquery.dataOwner"
    members = [
      "user:[e-mail]",
    ]
  }
}

resource "google_bigquery_table_iam_policy" "policy" {
  dataset_id  = google_bigquery_table.default.dataset_id
  table_id    = google_bigquery_table.default.table_id
  policy_data = data.google_iam_policy.default.policy_data
}

顧客管理の暗号鍵を使用してテーブルを作成する

次の例では、mytable という名前のテーブルを作成します。また、google_kms_crypto_key と google_kms_key_ring リソースを使用し、テーブルに Cloud Key Management Service の鍵を指定します。この例を実行する前に、Cloud Key Management Service API を有効にする必要があります。

resource "google_bigquery_dataset" "default" {
  dataset_id                      = "mydataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

resource "google_bigquery_table" "default" {
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "mytable"
  deletion_protection = false # set to "true" in production

  schema = <<EOF
[
  {
    "name": "ID",
    "type": "INT64",
    "mode": "NULLABLE",
    "description": "Item ID"
  },
  {
    "name": "Item",
    "type": "STRING",
    "mode": "NULLABLE"
  }
]
EOF

  encryption_configuration {
    kms_key_name = google_kms_crypto_key.crypto_key.id
  }

  depends_on = [google_project_iam_member.service_account_access]
}

resource "google_kms_crypto_key" "crypto_key" {
  name     = "example-key"
  key_ring = google_kms_key_ring.key_ring.id
}

resource "random_id" "default" {
  byte_length = 8
}

resource "google_kms_key_ring" "key_ring" {
  name     = "${random_id.default.hex}-example-keyring"
  location = "us"
}

# Enable the BigQuery service account to encrypt/decrypt Cloud KMS keys
data "google_project" "project" {
}

resource "google_project_iam_member" "service_account_access" {
  project = data.google_project.project.project_id
  role    = "roles/cloudkms.cryptoKeyEncrypterDecrypter"
  member  = "serviceAccount:bq-${data.google_project.project.number}@bigquery-encryption.iam.gserviceaccount.com"
}

Google Cloud プロジェクトで Terraform 構成を適用するには、次のセクションの手順を完了します。

Cloud Shell を準備する

1. Cloud Shell を起動します。

2. Terraform 構成を適用するデフォルトの Google Cloud プロジェクトを設定します。

   このコマンドは、プロジェクトごとに 1 回だけ実行する必要があります。これは任意のディレクトリで実行できます。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Terraform 構成ファイルに明示的な値を設定すると、環境変数がオーバーライドされます。

ディレクトリを準備する

Terraform 構成ファイルには独自のディレクトリ（ルート モジュールとも呼ばれます）が必要です。

1. Cloud Shell で、ディレクトリを作成し、そのディレクトリ内に新しいファイルを作成します。ファイルの拡張子は .tf にする必要があります（例: main.tf）。このチュートリアルでは、このファイルを main.tf とします。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. チュートリアルを使用している場合は、各セクションまたはステップのサンプルコードをコピーできます。

   新しく作成した main.tf にサンプルコードをコピーします。

   必要に応じて、GitHub からコードをコピーします。Terraform スニペットがエンドツーエンドのソリューションの一部である場合は、この方法をおすすめします。

3. 環境に適用するサンプル パラメータを確認し、変更します。
4. 変更を保存します。
5. Terraform を初期化します。これは、ディレクトリごとに 1 回だけ行います。

   terraform init

   最新バージョンの Google プロバイダを使用する場合は、-upgrade オプションを使用します。

   terraform init -upgrade

変更を適用する

1. 構成を確認して、Terraform が作成または更新するリソースが想定どおりであることを確認します。

   terraform plan

   必要に応じて構成を修正します。

2. 次のコマンドを実行します。プロンプトで「yes」と入力して、Terraform 構成を適用します。

   terraform apply

   Terraform に「Apply complete!」というメッセージが表示されるまで待ちます。

3. Google Cloud プロジェクトを開いて結果を表示します。 Google Cloud コンソールの UI でリソースに移動して、Terraform によって作成または更新されたことを確認します。

注: Terraform のサンプルでは通常、必要な API が Google Cloud プロジェクトで有効になっていることを前提としています。

API

定義済みのテーブル リソースを使用して tables.insert メソッドを呼び出します。

C#

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

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

using Google.Cloud.BigQuery.V2;

public class BigQueryCreateTable
{
    public BigQueryTable CreateTable(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var dataset = client.GetDataset(datasetId);
        // Create schema for new table.
        var schema = new TableSchemaBuilder
        {
            { "full_name", BigQueryDbType.String },
            { "age", BigQueryDbType.Int64 }
        }.Build();
        // Create the table
        return dataset.CreateTable(tableId: "your_table_id", schema: schema);
    }
}

Go

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

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

import (
	"context"
	"fmt"
	"time"

	"cloud.google.com/go/bigquery"
)

// createTableExplicitSchema demonstrates creating a new BigQuery table and specifying a schema.
func createTableExplicitSchema(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydatasetid"
	// tableID := "mytableid"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType},
		{Name: "age", Type: bigquery.IntegerFieldType},
	}

	metaData := &bigquery.TableMetadata{
		Schema:         sampleSchema,
		ExpirationTime: time.Now().AddDate(1, 0, 0), // Table will be automatically deleted in 1 year.
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, metaData); err != nil {
		return err
	}
	return nil
}

Java

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

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.TableDefinition;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

public class CreateTable {

  public static void runCreateTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    Schema schema =
        Schema.of(
            Field.of("stringField", StandardSQLTypeName.STRING),
            Field.of("booleanField", StandardSQLTypeName.BOOL));
    createTable(datasetName, tableName, schema);
  }

  public static void createTable(String datasetName, String tableName, Schema schema) {
    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();

      TableId tableId = TableId.of(datasetName, tableName);
      TableDefinition tableDefinition = StandardTableDefinition.of(schema);
      TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Table created successfully");
    } catch (BigQueryException e) {
      System.out.println("Table was not created. \n" + e.toString());
    }
  }
}

Node.js

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

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

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

async function createTable() {
  // Creates a new table named "my_table" in "my_dataset".

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";
  // const schema = 'Name:string, Age:integer, Weight:float, IsMagic:boolean';

  // For all options, see https://cloud.google.com/bigquery/docs/reference/v2/tables#resource
  const options = {
    schema: schema,
    location: 'US',
  };

  // Create a new table in the dataset
  const [table] = await bigquery
    .dataset(datasetId)
    .createTable(tableId, options);

  console.log(`Table ${table.id} created.`);
}

PHP

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

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

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';
// $fields = [
//    [
//        'name' => 'field1',
//        'type' => 'string',
//        'mode' => 'required'
//    ],
//    [
//        'name' => 'field2',
//        'type' => 'integer'
//    ],
//];

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$schema = ['fields' => $fields];
$table = $dataset->createTable($tableId, ['schema' => $schema]);
printf('Created table %s' . PHP_EOL, $tableId);

Python

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

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

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

schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
]

table = bigquery.Table(table_id, schema=schema)
table = client.create_table(table)  # Make an API request.
print(
    "Created table {}.{}.{}".format(table.project, table.dataset_id, table.table_id)
)

Ruby

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

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

require "google/cloud/bigquery"

def create_table dataset_id = "my_dataset"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table_id = "my_table"

  table = dataset.create_table table_id do |updater|
    updater.string  "full_name", mode: :required
    updater.integer "age",       mode: :required
  end

  puts "Created table: #{table_id}"
end

スキーマ定義を含まない空のテーブルを作成する

Java

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

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.TableDefinition;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

// Sample to create a table without schema
public class CreateTableWithoutSchema {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    createTableWithoutSchema(datasetName, tableName);
  }

  public static void createTableWithoutSchema(String datasetName, String tableName) {
    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();

      TableId tableId = TableId.of(datasetName, tableName);
      TableDefinition tableDefinition = StandardTableDefinition.of(Schema.of());
      TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Table created successfully");
    } catch (BigQueryException e) {
      System.out.println("Table was not created. \n" + e.toString());
    }
  }
}

クエリ結果からテーブルを作成する

クエリ結果からテーブルを作成するには、結果を宛先テーブルに書き込みます。

コンソール

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

   [BigQuery] ページに移動

2. 左側のペインで、 [エクスプローラ] をクリックします。

   

   左側のペインが表示されていない場合は、 左側のペインを開くをクリックしてペインを開きます。

3. [エクスプローラ] ペインでプロジェクトを開き、[データセット] をクリックして、データセットを選択します。

4. クエリエディタで、有効な SQL クエリを入力します。

5. [展開] をクリックして、[クエリ オプション] を選択します。

   

6. [クエリ結果の宛先テーブルを設定する] オプションを選択します。

   

7. [送信先] セクションで、テーブルを作成するデータセットを選択し、テーブル ID を選択します。

8. [宛先テーブルの書き込み設定] セクションで、次のいずれかを選択します。

   • [空の場合に書き込む] - テーブルが空の場合にのみ、クエリ結果をテーブルに書き込みます。
   • [テーブルに追加する] - クエリ結果を既存のテーブルに追加します。
   • [テーブルを上書きする] - 既存のテーブルにクエリ結果を同じ名前で上書きします。

9. 省略可: [データのロケーション] で、ロケーションを選択します。

10. クエリの設定を更新するには、[保存] をクリックします。

11. [実行] をクリックします。これにより、指定したテーブルにクエリ結果を書き込むクエリジョブが作成されます。

宛先テーブルを指定せずにクエリを実行した場合は、エディタの上にある [結果を保存する] ボタンをクリックすると、キャッシュに保存された結果テーブルを永続テーブルにコピーできます。

SQL

次の例では、CREATE TABLE ステートメントを使用して、一般公開 bikeshare_trips テーブルのデータから trips テーブルを作成します。

1. Google Cloud コンソールで、[BigQuery] ページに移動します。

   [BigQuery] に移動

2. クエリエディタで次のステートメントを入力します。

   CREATE TABLE mydataset.trips AS (
     SELECT
       bike_id,
       start_time,
       duration_minutes
     FROM
       bigquery-public-data.austin_bikeshare.bikeshare_trips
   );

3. [実行] をクリックします。

クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。

詳細については、既存のテーブルから新しいテーブルを作成するをご覧ください。

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. クエリ結果に基づいて永続テーブルを作成するには、bq query コマンドを入力して、--destination_table フラグを指定します。GoogleSQL 構文を使用するには、use_legacy_sql=false フラグを指定します。デフォルト プロジェクト以外のプロジェクトにあるテーブルにクエリ結果を書き込むには、project_id:dataset の形式でプロジェクト ID をデータセット名に追加します。

   省略可: --location フラグを指定して、その値を使用するロケーションに設定します。

   既存の宛先テーブルに対する書き込み処理を制御するには、次のオプション フラグのいずれかを指定します。

   • --append_table: 宛先テーブルが存在する場合、クエリ結果がそのテーブルに追加されます。

   • --replace: 宛先テーブルが存在する場合、そのテーブルはクエリ結果で上書きされます。

     bq --location=location query \
     --destination_table project_id:dataset.table \
     --use_legacy_sql=false 'query'

     次のように置き換えます。

   • location は、クエリの処理に使用するロケーションの名前です。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。ロケーションのデフォルト値は、.bigqueryrc ファイルを使用して設定できます。

   • project_id はプロジェクト ID です。

   • dataset は、クエリ結果を書き込むテーブルを含むデータセットの名前です。

   • table は、クエリ結果を書き込むテーブルの名前です。

   • query は、GoogleSQL 構文のクエリです。

     書き込み処理フラグが指定されていない場合は、デフォルトの動作として、テーブルが空の場合にのみ結果が書き込まれます。テーブルが存在していて空でない場合は、BigQuery error in query operation: Error processing job project_id:bqjob_123abc456789_00000e1234f_1: Already Exists: Table project_id:dataset.table というエラーが返されます。

     例:

     注: これらの例では、米国に置かれた一般公開データセットに対してクエリを実行しています。一般公開データセットは米国のマルチリージョン ロケーションに保管されているため、宛先テーブルが含まれるデータセットも米国内に存在する必要があります。あるロケーションのデータセットに対するクエリを実行して、結果を別のロケーションにあるテーブルに書き込むことはできません。

     次のコマンドを入力すると、mydataset 内の mytable という宛先テーブルにクエリ結果が書き込まれます。このデータセットはデフォルト プロジェクトにあります。コマンドに書き込み処理フラグは指定されていないため、宛先テーブルは新規または空である必要があります。それ以外の場合は、Already exists エラーが返されます。このクエリは、USA Name Data 一般公開データセットからデータを取得します。

     bq query \
     --destination_table mydataset.mytable \
     --use_legacy_sql=false \
     'SELECT
     name,
     number
     FROM
     `bigquery-public-data`.usa_names.usa_1910_current
     WHERE
     gender = "M"
     ORDER BY
     number DESC'

     クエリ結果を使用して mydataset 内の mytable という名前の宛先テーブルを上書きするには、次のコマンドを入力します。このデータセットはデフォルト プロジェクトにあります。このコマンドには --replace フラグが指定されているため、宛先テーブルが上書きされます。

     bq query \
     --destination_table mydataset.mytable \
     --replace \
     --use_legacy_sql=false \
     'SELECT
     name,
     number
     FROM
     `bigquery-public-data`.usa_names.usa_1910_current
     WHERE
     gender = "M"
     ORDER BY
     number DESC'

     mydataset 内の mytable という名前の宛先テーブルにクエリ結果を追加するには、次のコマンドを入力します。このデータセットはデフォルト プロジェクトではなく my-other-project にあります。このコマンドには --append_table フラグが指定されているため、クエリ結果が宛先テーブルに追加されます。

     bq query \
     --append_table \
     --use_legacy_sql=false \
     --destination_table my-other-project:mydataset.mytable \
     'SELECT
     name,
     number
     FROM
     `bigquery-public-data`.usa_names.usa_1910_current
     WHERE
     gender = "M"
     ORDER BY
     number DESC'

     上記のそれぞれの例では、次のような出力が生成されます。読みやすくするために、出力の一部のみを示します。

     Waiting on bqjob_r123abc456_000001234567_1 ... (2s) Current status: DONE
     +---------+--------+
     |  name   | number |
     +---------+--------+
     | Robert  |  10021 |
     | John    |   9636 |
     | Robert  |   9297 |
     | ...              |
     +---------+--------+
     

API

クエリ結果を永続テーブルに保存するには、jobs.insert メソッドを呼び出して query ジョブを構成し、destinationTable プロパティの値を含めます。既存の宛先テーブルに対する書き込み処理を制御するには、writeDisposition プロパティを構成します。

クエリジョブの処理を行うロケーションを制御するには、ジョブリソースの jobReference セクションにある location プロパティを指定します。

Go

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

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

import (
	"context"
	"fmt"
	"io"

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

// queryWithDestination demonstrates saving the results of a query to a specific table by setting the destination
// via the API properties.
func queryWithDestination(w io.Writer, projectID, destDatasetID, destTableID 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()

	q := client.Query("SELECT 17 as my_col")
	q.Location = "US" // Location must match the dataset(s) referenced in query.
	q.QueryConfig.Dst = client.Dataset(destDatasetID).Table(destTableID)
	// Run the query and print results when the query job is completed.
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}
	it, err := job.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 のリファレンス ドキュメントをご覧ください。

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

クエリの結果を永続テーブルに保存するには、QueryJobConfiguration で宛先テーブルを目的の TableId に設定します。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableId;

public class SaveQueryToTable {

  public static void runSaveQueryToTable() {
    // TODO(developer): Replace these variables before running the sample.
    String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
    String destinationTable = "MY_TABLE";
    String destinationDataset = "MY_DATASET";

    saveQueryToTable(destinationDataset, destinationTable, query);
  }

  public static void saveQueryToTable(
      String destinationDataset, String destinationTableId, String query) {
    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 destination table
      TableId destinationTable = TableId.of(destinationDataset, destinationTableId);

      // Build the query job
      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query).setDestinationTable(destinationTable).build();

      // Execute the query.
      bigquery.query(queryConfig);

      // The results are now saved in the destination table.

      System.out.println("Saved query ran successfully");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Saved query did not run \n" + e.toString());
    }
  }
}

Node.js

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

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

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

async function queryDestinationTable() {
  // Queries the U.S. given names dataset for the state of Texas
  // and saves results to permanent table.

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

  // Create destination table reference
  const dataset = bigquery.dataset(datasetId);
  const destinationTable = dataset.table(tableId);

  const query = `SELECT name
    FROM \`bigquery-public-data.usa_names.usa_1910_2013\`
    WHERE state = 'TX'
    LIMIT 100`;

  // For all options, see https://cloud.google.com/bigquery/docs/reference/v2/tables#resource
  const options = {
    query: query,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
    destination: destinationTable,
  };

  // Run the query as a job
  const [job] = await bigquery.createQueryJob(options);

  console.log(`Job ${job.id} started.`);
  console.log(`Query results loaded to table ${destinationTable.id}`);
}

Python

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

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

クエリ結果を永続テーブルに保存するには、QueryJobConfig を作成し、宛先を目的の TableReference に設定します。そのジョブ構成を query メソッドに渡します。

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the destination table.
# table_id = "your-project.your_dataset.your_table_name"

job_config = bigquery.QueryJobConfig(destination=table_id)

sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""

# Start the query, passing in the extra configuration.
query_job = client.query(sql, job_config=job_config)  # Make an API request.
query_job.result()  # Wait for the job to complete.

print("Query results loaded to the table {}".format(table_id))

外部データソースを参照するテーブルを作成する

外部データソースは、データが BigQuery ストレージに格納されていない場合でも、BigQuery から直接クエリできるデータソースです。たとえば、別の Google Cloud データベース、Cloud Storage のファイル、または別のクラウド プロダクトにまとめてデータを保管していて、BigQuery で分析を行うものの、移行の準備はできていない場合があります。

詳細については、外部データソースの概要をご覧ください。

データの読み込み時にテーブルを作成する

BigQuery にデータを読み込む際は、そのデータを新しいテーブルやパーティションに読み込むか、既存のテーブルまたはパーティションに追加できます。また、テーブルまたはパーティションを上書きすることもできます。データを読み込む前に空のテーブルを作成する必要はありません。新しいテーブルの作成とデータの読み込みを同時に行うことができます。

BigQuery にデータを読み込むとき、テーブルまたはパーティションのスキーマを指定できます。また、サポートされているデータ形式であれば、スキーマの自動検出を使用できます。

データの読み込みの詳細については、BigQuery へのデータの読み込みの概要をご覧ください。

テーブルへのアクセスの制御

テーブルとビューへのアクセスを構成するには、エンティティに次のレベルで IAM ロールを付与します。以下に、各レベルを許可されるリソースの範囲が大きい順に一覧で示します。

• プロジェクト レベル、フォルダレベル、組織レベルなど、Google Cloud リソース階層の上位レベル
• データセット レベル
• テーブルまたはビューレベル

次の方法で、テーブル内のデータアクセスを制限することもできます。

• 列レベルのセキュリティ
• 列データ マスキング
• 行レベルのセキュリティ

IAM で保護されているリソースを使用したアクセスは追加型です。たとえば、エンティティにプロジェクトなどの上位レベルのアクセス権がない場合は、データセット レベルでアクセス権を付与すると、データセット内のテーブルとビューにアクセスできます。同様に、エンティティに高レベルまたはデータセット レベルでのアクセス権がない場合は、テーブルレベルまたはビューレベルでエンティティにアクセス権を付与できます。

プロジェクト レべル、フォルダレベル、組織レベルなど、Google Cloudリソース階層の上位レベルで IAM ロールを付与すると、エンティティは幅広いリソースのセットにアクセスできるようになります。たとえば、プロジェクト レベルでエンティティにロールを付与すると、そのエンティティには、プロジェクトに含まれるすべてのデータセットに適用される権限が付与されます。

データセット レベルでロールを付与すると、そのエンティティが上位レベルでアクセスできない場合でも、そのデータセットのテーブルとビューで実行できるオペレーションが指定されます。データセット レベルのアクセス制御を構成する方法については、データセットへのアクセスの制御をご覧ください。

テーブルまたはビューレベルでロールを付与すると、エンティティに上位レベルのアクセスがない場合でも、特定のテーブルやビューに対してエンティティが実行できるオペレーションが特定されます。テーブルレベルのアクセス制御の構成については、テーブルおよびビューへのアクセスの制御をご覧ください。

また、IAM カスタムロールを作成することもできます。カスタムロールを作成する場合、エンティティに実行を許可する特定のオペレーションによって、付与する権限は異なります。

IAM で保護されているリソースに「拒否」権限を設定することはできません。

ロールと権限の詳細については、IAM のドキュメント内のロールについてと BigQuery の IAM のロールと権限をご覧ください。

テーブルに関する情報を取得する

テーブルに関する情報またはメタデータは、次の方法で入手できます。

• Google Cloud コンソールを使用する。
• bq コマンドライン ツールの bq show コマンドを使用する。
• tables.get API メソッドを呼び出す。
• クライアント ライブラリを使用する。
• INFORMATION_SCHEMA.VIEWS ビューのクエリ

必要な権限

テーブルに関する情報を取得するには、少なくとも bigquery.tables.get 権限が付与されている必要があります。次の事前定義済みの IAM ロールには bigquery.tables.get 権限が含まれています。

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

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

BigQuery での IAM ロールと権限の詳細については、アクセス制御をご覧ください。

テーブル情報の取得

テーブルに関する情報を取得するには:

コンソール

1. ナビゲーション パネルの [リソース] セクションでプロジェクトを開き、データセットを選択します。

2. データセット名をクリックして開きます。データセット内のテーブルとビューが表示されます。

3. テーブル名をクリックします。

4. [詳細] パネルで [詳細] をクリックして、テーブルの説明とテーブル情報を表示します。

5. 必要に応じて、[スキーマ] タブに切り替えて、テーブルのスキーマ定義を表示します。

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. すべてのテーブル情報を表示するには、bq show コマンドを発行します。テーブルのスキーマ情報のみを表示するには、--schema フラグを使用します。--format フラグを使用して出力を制御できます。

   デフォルト以外のプロジェクトにあるテーブルの情報を取得する場合は、project_id:dataset の形式でプロジェクト ID をデータセットに追加します。

   bq show \
   --schema \
   --format=prettyjson \
   project_id:dataset.table

   ここで

   • project_id はプロジェクト ID です。
   • dataset は、データセットの名前です。
   • table は、テーブルの名前です。

   例:

   次のコマンドを入力して、mydataset にある mytable に関するすべての情報を表示します。mydataset はデフォルト プロジェクトにあります。

   bq show --format=prettyjson mydataset.mytable

   次のコマンドを入力して、mydataset にある mytable に関するすべての情報を表示します。mydataset は、デフォルト プロジェクトではなく myotherproject にあります。

   bq show --format=prettyjson myotherproject:mydataset.mytable

   mydataset 内の mytable に関するスキーマ情報のみを表示するには、次のコマンドを入力します。mydataset はデフォルト プロジェクトではなく myotherproject にあります。

   bq show --schema --format=prettyjson myotherproject:mydataset.mytable

API

tables.get メソッドを呼び出し、関連パラメータを指定します。

Go

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

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

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
)

// printTableInfo demonstrates fetching metadata from a table and printing some basic information
// to an io.Writer.
func printTableInfo(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()

	meta, err := client.Dataset(datasetID).Table(tableID).Metadata(ctx)
	if err != nil {
		return err
	}
	// Print basic information about the table.
	fmt.Fprintf(w, "Schema has %d top-level fields\n", len(meta.Schema))
	fmt.Fprintf(w, "Description: %s\n", meta.Description)
	fmt.Fprintf(w, "Rows in managed storage: %d\n", meta.NumRows)
	return nil
}

Java

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

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;

public class GetTable {

  public static void runGetTable() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "bigquery_public_data";
    String datasetName = "samples";
    String tableName = "shakespeare";
    getTable(projectId, datasetName, tableName);
  }

  public static void getTable(String projectId, String datasetName, String tableName) {
    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();

      TableId tableId = TableId.of(projectId, datasetName, tableName);
      Table table = bigquery.getTable(tableId);
      System.out.println("Table info: " + table.getDescription());
    } catch (BigQueryException e) {
      System.out.println("Table not retrieved. \n" + e.toString());
    }
  }
}

Node.js

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

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

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

async function getTable() {
  // Retrieves table named "my_table" in "my_dataset".

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

  // Retrieve table reference
  const dataset = bigquery.dataset(datasetId);
  const [table] = await dataset.table(tableId).get();

  console.log('Table:');
  console.log(table.metadata.tableReference);
}
getTable();

PHP

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

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

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';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);

Python

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

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

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the model to fetch.
# table_id = 'your-project.your_dataset.your_table'

table = client.get_table(table_id)  # Make an API request.

# View table properties
print(
    "Got table '{}.{}.{}'.".format(table.project, table.dataset_id, table.table_id)
)
print("Table schema: {}".format(table.schema))
print("Table description: {}".format(table.description))
print("Table has {} rows".format(table.num_rows))

INFORMATION_SCHEMA を使用してテーブル情報を取得する

INFORMATION_SCHEMA は、データセット、ルーティン、テーブル、ビュー、ジョブ、予約、ストリーミング データに関するメタデータへのアクセスを可能にする一連のビューです。

次のビューにクエリを実行すると、テーブル情報を取得できます。

• INFORMATION_SCHEMA.TABLES ビューと INFORMATION_SCHEMA.TABLE_OPTIONS ビューは、プロジェクト内のテーブルとビューに関するメタデータの取得に使用します。
• INFORMATION_SCHEMA.COLUMNS ビューと INFORMATION_SCHEMA.COLUMN_FIELD_PATHS ビューは、テーブル内の列（フィールド）に関するメタデータの取得に使用します。
• INFORMATION_SCHEMA.TABLE_STORAGE ビューは、テーブルによる現在と過去のストレージ使用量に関するメタデータの取得に使用します。

TABLES と TABLE_OPTIONS ビューには、ビューに関する概要情報も含まれています。詳細情報を取得するには、INFORMATION_SCHEMA.VIEWS ビューに対してクエリを実行します。

TABLES ビュー

INFORMATION_SCHEMA.TABLES ビューにクエリを実行すると、クエリの結果として、データセット内の各テーブルまたはビューが 1 行で返されます。ビューの詳細情報を取得するには、INFORMATION_SCHEMA.VIEWS ビューに対してクエリを実行します。

INFORMATION_SCHEMA.TABLES ビューのスキーマは次のとおりです。

列名	データ型	値
table_catalog	STRING	データセットを含むプロジェクトの ID。
table_schema	STRING	テーブルやビューを含むデータセットの名前（datasetId とも呼ばれる）。
table_name	STRING	テーブルまたはビューの名前（tableId とも呼ばれる）。
table_type	STRING	テーブルタイプ: 次のいずれかです。 BASE TABLE: 標準のテーブル CLONE: テーブル クローン SNAPSHOT: テーブル スナップショット VIEW: ビュー MATERIALIZED VIEW: マテリアライズド ビューまたはマテリアライズド ビュー レプリカ EXTERNAL: 外部データソースを参照するテーブル
managed_table_type	STRING	この列はプレビュー版です。マネージド テーブルタイプ:次のいずれかです。 NATIVE: 標準のテーブル BIGLAKE: BigQuery 内の Apache Iceberg 用 BigLake テーブル
is_insertable_into	STRING	YES または NO（テーブルが DML INSERT ステートメントに対応しているかどうかによる）
is_fine_grained_mutations_enabled	STRING	YES または NO（きめ細かい DML ミューテーションがテーブルで有効になっているかどうかによる）
is_typed	STRING	値は常に NO
is_change_history_enabled	STRING	変更履歴が有効かどうかに応じて YES または NO
creation_time	TIMESTAMP	テーブルの作成時間
base_table_catalog	STRING	テーブル クローンとテーブル スナップショットの場合、ベーステーブルのプロジェクト。table_type が CLONE または SNAPSHOT に設定されているテーブルにのみ該当します。
base_table_schema	STRING	テーブル クローンとテーブル スナップショットの場合、ベーステーブルのデータセット。table_type が CLONE または SNAPSHOT に設定されているテーブルにのみ該当します。
base_table_name	STRING	テーブル クローンとテーブル スナップショットの場合、ベーステーブルの名前。table_type が CLONE または SNAPSHOT に設定されているテーブルにのみ該当します。
snapshot_time_ms	TIMESTAMP	テーブル クローンとテーブル スナップショットの場合、このテーブルを作成するために、ベーステーブルに対してクローンまたはスナップショットのオペレーションが実行された時刻。タイムトラベルが使用された場合、このフィールドにはタイムトラベルのタイムスタンプが含まれます。それ以外の場合、snapshot_time_ms フィールドは creation_time フィールドと同じです。table_type が CLONE または SNAPSHOT に設定されているテーブルにのみ該当します。
replica_source_catalog	STRING	マテリアライズド ビュー レプリカの場合、ベースのマテリアライズド ビューのプロジェクト。
replica_source_schema	STRING	マテリアライズド ビュー レプリカの場合: ベースのマテリアライズド ビューのデータセット。
replica_source_name	STRING	マテリアライズド ビュー レプリカの場合、ベース マテリアライズド ビューの名前。
replication_status	STRING	マテリアライズド ビュー レプリカの場合、ベースのマテリアライズド ビューからマテリアライズド ビュー レプリカへのレプリケーションのステータス。次のいずれかです。 REPLICATION_STATUS_UNSPECIFIED ACTIVE: レプリケーションがアクティブで、エラーはない。 SOURCE_DELETED: ソース マテリアライズド ビューが削除されている。 PERMISSION_DENIED: マテリアライズド ビューを作成したクエリで使用したソースの Amazon S3 BigLake テーブルを含むデータセットで、ソースのマテリアライズド ビューが承認されていない。 UNSUPPORTED_CONFIGURATION: レプリカの前提条件に問題がある（ソースのマテリアライズド ビューの承認以外）。
replication_error	STRING	replication_status がマテリアライズド ビュー レプリカのレプリケーションの問題を示している場合は、replication_error に問題の詳細が示されます。
ddl	STRING	テーブルの再作成に使用できる DDL ステートメント（CREATE TABLE、CREATE VIEW など）
default_collation_name	STRING	デフォルトの照合順序仕様が存在する場合はその名前。それ以外の場合は NULL。
upsert_stream_apply_watermark	TIMESTAMP	変更データ キャプチャ（CDC）を使用するテーブルの場合、行の変更が最後に適用された時刻。詳細については、テーブル upsert オペレーションの進行状況をモニタリングするをご覧ください。

例

例 1:

次の例では、mydataset という名前のデータセット内のすべてのテーブルのメタデータを取得します。デフォルト プロジェクト内の mydataset にあるすべてのタイプのテーブルに関するメタデータが返されます。

mydataset には、次のテーブルが含まれています。

• mytable1: 標準の BigQuery テーブル
• myview1: BigQuery のビュー

デフォルト プロジェクト以外のプロジェクトに対してクエリを実行するには、`project_id`.dataset.INFORMATION_SCHEMA.view という形式でそのプロジェクト ID をデータセットに追加します（例: `myproject`.mydataset.INFORMATION_SCHEMA.TABLES）。

注: INFORMATION_SCHEMA ビューの名前では大文字と小文字が区別されます。

SELECT
  table_catalog, table_schema, table_name, table_type,
  is_insertable_into, creation_time, ddl
FROM
  mydataset.INFORMATION_SCHEMA.TABLES;

次のような結果になります。読みやすくするため、一部の列は結果から除外されています。

+----------------+---------------+----------------+------------+--------------------+---------------------+---------------------------------------------+
| table_catalog  | table_schema  |   table_name   | table_type | is_insertable_into |    creation_time    |                     ddl                     |
+----------------+---------------+----------------+------------+--------------------+---------------------+---------------------------------------------+
| myproject      | mydataset     | mytable1       | BASE TABLE | YES                | 2018-10-29 20:34:44 | CREATE TABLE `myproject.mydataset.mytable1` |
|                |               |                |            |                    |                     | (                                           |
|                |               |                |            |                    |                     |   id INT64                                  |
|                |               |                |            |                    |                     | );                                          |
| myproject      | mydataset     | myview1        | VIEW       | NO                 | 2018-12-29 00:19:20 | CREATE VIEW `myproject.mydataset.myview1`   |
|                |               |                |            |                    |                     | AS SELECT 100 as id;                        |
+----------------+---------------+----------------+------------+--------------------+---------------------+---------------------------------------------+

例 2:

次の例では、INFORMATION_SCHEMA.TABLES ビューから CLONE 型または SNAPSHOT 型のすべてのテーブルのテーブル メタデータを取得します。デフォルト プロジェクトの mydataset にあるテーブルに関するメタデータが返されます。

デフォルト プロジェクト以外のプロジェクトに対してクエリを実行するには、`project_id`.dataset.INFORMATION_SCHEMA.view という形式でそのプロジェクト ID をデータセットに追加します（例: `myproject`.mydataset.INFORMATION_SCHEMA.TABLES）。

  SELECT
    table_name, table_type, base_table_catalog,
    base_table_schema, base_table_name, snapshot_time_ms
  FROM
    mydataset.INFORMATION_SCHEMA.TABLES
  WHERE
    table_type = 'CLONE'
  OR
    table_type = 'SNAPSHOT';

次のような結果になります。読みやすくするため、一部の列は結果から除外されています。

  +--------------+------------+--------------------+-------------------+-----------------+---------------------+
  | table_name   | table_type | base_table_catalog | base_table_schema | base_table_name | snapshot_time_ms    |
  +--------------+------------+--------------------+-------------------+-----------------+---------------------+
  | items_clone  | CLONE      | myproject          | mydataset         | items           | 2018-10-31 22:40:05 |
  | orders_bk    | SNAPSHOT   | myproject          | mydataset         | orders          | 2018-11-01 08:22:39 |
  +--------------+------------+--------------------+-------------------+-----------------+---------------------+

例 3:

次の例では、census_bureau_usa データセットにある population_by_zip_2010 テーブルの INFORMATION_SCHEMA.TABLES ビューから table_name 列と ddl 列を取得します。このデータセットは、BigQuery の一般公開データセット プログラムの一部です。

クエリ対象のテーブルは別のプロジェクトにあるため、`project_id`.dataset.INFORMATION_SCHEMA.view の形式でプロジェクト ID をデータセットに追加します。この例での値は `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.TABLES です。

SELECT
  table_name, ddl
FROM
  `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.TABLES
WHERE
  table_name = 'population_by_zip_2010';

次のような結果になります。

+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|       table_name       |                                                                                                            ddl                                                                                                             |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| population_by_zip_2010 | CREATE TABLE `bigquery-public-data.census_bureau_usa.population_by_zip_2010`                                                                                                                                               |
|                        | (                                                                                                                                                                                                                          |
|                        |   geo_id STRING OPTIONS(description="Geo code"),                                                                                                                                                                           |
|                        |   zipcode STRING NOT NULL OPTIONS(description="Five digit ZIP Code Tabulation Area Census Code"),                                                                                                                          |
|                        |   population INT64 OPTIONS(description="The total count of the population for this segment."),                                                                                                                             |
|                        |   minimum_age INT64 OPTIONS(description="The minimum age in the age range. If null, this indicates the row as a total for male, female, or overall population."),                                                          |
|                        |   maximum_age INT64 OPTIONS(description="The maximum age in the age range. If null, this indicates the row as having no maximum (such as 85 and over) or the row is a total of the male, female, or overall population."), |
|                        |   gender STRING OPTIONS(description="male or female. If empty, the row is a total population summary.")                                                                                                                    |
|                        | )                                                                                                                                                                                                                          |
|                        | OPTIONS(                                                                                                                                                                                                                   |
|                        |   labels=[("freebqcovid", "")]                                                                                                                                                                                             |
|                        | );                                                                                                                                                                                                                         |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  

TABLE_OPTIONS ビュー

INFORMATION_SCHEMA.TABLE_OPTIONS ビューに対してクエリを実行すると、クエリ結果として、データセットに含まれる各テーブルまたはビューのオプションごとに 1 行が表示されます。ビューの詳細情報を取得するには、INFORMATION_SCHEMA.VIEWS ビューに対してクエリを実行します。

INFORMATION_SCHEMA.TABLE_OPTIONS ビューのスキーマは次のとおりです。

列名	データ型	値
TABLE_CATALOG	STRING	データセットを含むプロジェクトのプロジェクト ID
TABLE_SCHEMA	STRING	datasetId とも呼ばれる、テーブルやビューを含むデータセットの名前
TABLE_NAME	STRING	テーブルまたはビューの名前（tableId とも呼ばれる）
OPTION_NAME	STRING	オプション テーブル内の名前値の 1 つ
OPTION_TYPE	STRING	オプション テーブルのデータ型の値の 1 つ
OPTION_VALUE	STRING	オプション テーブルの値オプションの 1 つ

オプション テーブル

OPTION_NAME	OPTION_TYPE	OPTION_VALUE
description	STRING	テーブルの説明
enable_refresh	BOOL	マテリアライズド ビューで自動更新が有効にされているかどうか
expiration_timestamp	TIMESTAMP	このテーブルの有効期限
friendly_name	STRING	テーブルのわかりやすい名前
kms_key_name	STRING	テーブルの暗号化に使用される Cloud KMS 鍵の名前
labels	ARRAY<STRUCT<STRING, STRING>>	テーブルのラベルを表す STRUCT の配列
max_staleness	INTERVAL	BigQuery 変更データ キャプチャ（CDC）の upsert の構成済みテーブルの最大鮮度
partition_expiration_days	FLOAT64	パーティション分割テーブルのすべてのパーティションのデフォルトの存続期間（日数）
refresh_interval_minutes	FLOAT64	マテリアライズド ビューが更新される頻度
require_partition_filter	BOOL	テーブルに対するクエリでパーティション フィルタが必要かどうか
tags	ARRAY<STRUCT<STRING, STRING>>	名前空間付きの <key, value> 構文でテーブルに適用されるタグ。詳細については、タグと条件付きアクセスをご覧ください。

外部テーブルの場合、次のオプションを使用できます。

オプション
allow_jagged_rows	BOOL true の場合、末尾のオプションの列が欠落している行を受け入れます。 CSV データに適用されます。
allow_quoted_newlines	BOOL true の場合、改行文字を含む引用符で囲まれたデータ セクションを許可します。 CSV データに適用されます。
bigtable_options	STRING Bigtable 外部テーブルを作成する場合にのみ必要です。 Bigtable 外部テーブルのスキーマを JSON 形式で指定します。 Bigtable テーブル定義オプションのリストについては、REST API リファレンスの BigtableOptions をご覧ください。
column_name_character_map	STRING 列名にサポートされる文字の範囲と、サポートされない文字の処理方法を定義します。デフォルト設定は STRICT です。サポートされない文字が入力されると、BigQuery でエラーがスローされます。V1 と V2 は、サポートされない文字をアンダースコアに置き換えます。 次の値がサポートされています。 STRICT: 柔軟な列名を有効にします。これはデフォルト値です。ジョブは、サポートされない文字が列名に含まれている場合は読み込みで失敗し、エラー メッセージが返されます。サポートされない文字をアンダースコアに置き換えて、ジョブの読み込みが成功するように構成するには、default_column_name_character_map 構成設定を指定します。 V1: 列名には、列名の標準文字のみを含めることができます。サポートされていない文字（Parquet ファイルの列名のピリオドを除く）は、アンダースコアに置き換えられます。これは、column_name_character_map の導入前に作成されたテーブルでのデフォルトの動作です。 V2: 列名の標準文字に加えて、柔軟な列名もサポートしています。サポートされていない文字（Parquet ファイルの列名のピリオドを除く）は、アンダースコアに置き換えられます。 CSV データと Parquet データに適用されます。
compression	STRING データソースの圧縮タイプ。サポートされる値: GZIP。指定しない場合、データソースは圧縮されません。 CSV データと JSON データに適用されます。
decimal_target_types	ARRAY<STRING> Decimal 型の変換方法を指定します。ExternalDataConfiguration.decimal_target_types と同等です。 例: ["NUMERIC", "BIGNUMERIC"]。
description	STRING このテーブルの説明。
enable_list_inference	BOOL true の場合は、Parquet LIST 論理型専用のスキーマ推定を使用します。 Parquet データに適用されます。
enable_logical_types	BOOL true の場合、Avro の論理型を対応する SQL 型に変換します。詳細については、論理型をご覧ください。 Avro データに適用されます。
encoding	STRING データの文字エンコード。サポートされている値: UTF8（または UTF-8）、ISO_8859_1（または ISO-8859-1）、UTF-16BE、UTF-16LE、UTF-32BE、UTF-32LE。デフォルト値は UTF-8 です。 CSV データに適用されます。
enum_as_string	BOOL true の場合、Parquet ENUM 論理型はデフォルトで BYTES ではなく STRING として推測します。 Parquet データに適用されます。
expiration_timestamp	TIMESTAMP このテーブルの有効期限。指定しない場合、テーブルは期限切れになりません。 例: "2025-01-01 00:00:00 UTC"。
field_delimiter	STRING CSV ファイル内のフィールド区切り文字。 CSV データに適用されます。
format	STRING 外部データの形式。CREATE EXTERNAL TABLE に指定できる値は、AVRO、CLOUD_BIGTABLE、CSV、DATASTORE_BACKUP、DELTA_LAKE（プレビュー）、GOOGLE_SHEETS、NEWLINE_DELIMITED_JSON（またはJSON）、ORC、PARQUET です。 LOAD DATA に指定できる値は、AVRO、CSV、DELTA_LAKE（プレビュー）、NEWLINE_DELIMITED_JSON（または JSON）、ORC、PARQUET です。 値 JSON は NEWLINE_DELIMITED_JSON と同等です。
hive_partition_uri_prefix	STRING パーティション キーのエンコードを開始する前のすべてのソース URI の一般的なプレフィックス。Hive パーティション分割された外部テーブルにのみ適用されます。 Avro、CSV、JSON、Parquet、ORC のデータに適用されます。 例: "gs://bucket/path"。
file_set_spec_type	STRING 読み込みジョブと外部テーブルのソース URI の解釈方法を指定します。 次の値がサポートされています。 FILE_SYSTEM_MATCH。オブジェクト ストアからファイルを一覧表示して、ソース URI を拡張します。FileSetSpecType が設定されていない場合、これがデフォルトの動作です。 NEW_LINE_DELIMITED_MANIFEST。指定された URI が、1 行に 1 つの URI が含まれる改行区切りのマニフェスト ファイルであることを示します。ワイルドカード URI はマニフェスト ファイルではサポートされていません。また、参照されるすべてのデータファイルは、マニフェスト ファイルと同じバケットに配置する必要があります。 たとえば、ソース URI が "gs://bucket/path/file" で、file_set_spec_type が FILE_SYSTEM_MATCH の場合、このファイルがデータファイルとして直接使用されます。file_set_spec_type が NEW_LINE_DELIMITED_MANIFEST の場合、ファイル内の各行は、データファイルを指す URI として解釈されます。
ignore_unknown_values	BOOL true の場合、テーブル スキーマにない余分な値を無視します。エラーは返しません。 CSV データと JSON データに適用されます。
json_extension	STRING JSON データの場合、特定の JSON 置換形式を指定します。指定しない場合、BigQuery はデータを汎用 JSON レコードとして読み取ります。 サポートされる値は、次のとおりです。 GEOJSON。改行区切りの GeoJSON データ。詳細については、改行区切りの GeoJSON ファイルから外部テーブルを作成するをご覧ください。
max_bad_records	INT64 データの読み取り時に無視する不良レコードの最大数。 適用対象: CSV、JSON、Google スプレッドシートのデータ。
max_staleness	INTERVAL BigLake テーブルとオブジェクト テーブルに適用されます。 キャッシュに保存されたメタデータをテーブルに対するオペレーションで使用するかどうかを指定します。また、オペレーションで使用できるキャッシュ内のメタデータの鮮度を指定します。 メタデータのキャッシュ保存を無効にするには、0 を指定します。これがデフォルトです。 メタデータ キャッシュを有効にするには、30 分から 7 日の間で間隔リテラルの値を指定します。たとえば、4 時間の未更新間隔の場合、INTERVAL 4 HOUR を指定します。この値を指定すると、キャッシュに保存されたメタデータが過去 4 時間以内に更新されていれば、テーブルに対するオペレーションはそのメタデータを使用します。キャッシュに保存されたメタデータがそれより古い場合、オペレーションは代わりに Cloud Storage からメタデータを取得します。
null_marker	STRING CSV ファイル内の NULL 値を表す文字列。 CSV データに適用されます。
null_markers	ARRAY<STRING> （プレビュー） CSV ファイル内の NULL 値を表す文字列のリスト。 このオプションは、null_marker オプションと併用できません。 CSV データに適用されます。
object_metadata	STRING オブジェクト テーブルを作成する場合にのみ必要です。 オブジェクト テーブルの作成時に、このオプションの値を SIMPLE に設定します。
preserve_ascii_control_characters	BOOL true の場合、埋め込みの ASCII 制御文字（ASCII テーブルの最初の 32 文字、「\x00」から「\x1F」まで）が保持されます。 CSV データに適用されます。
projection_fields	STRING 読み込むエンティティ プロパティのリスト。 Datastore データに適用されます。
quote	STRING CSV ファイルのデータ セクションを引用するために使用される文字列。データに引用符で囲まれた改行文字が含まれている場合は、allow_quoted_newlines プロパティも true に設定します。 CSV データに適用されます。
reference_file_schema_uri	STRING テーブル スキーマを含む、ユーザー指定の参照ファイル。 Parquet/ORC/AVRO データに適用されます。 例: "gs://bucket/path/reference_schema_file.parquet"。
require_hive_partition_filter	BOOL true の場合、このテーブルに対するすべてのクエリでパーティション フィルタが必要になります。パーティション フィルタを使用すると、データを読み取るときにパーティションを削除できます。Hive パーティション分割された外部テーブルにのみ適用されます。 Avro、CSV、JSON、Parquet、ORC のデータに適用されます。
sheet_range	STRING クエリの対象となる Google スプレッドシートの範囲。 Google スプレッドシートのデータに適用されます。 例: "sheet1!A1:B20"。
skip_leading_rows	INT64 データを読み取る際にスキップするファイルの先頭行の数。 CSV データと Google スプレッドシートのデータに適用されます。
source_column_match	STRING （プレビュー） 読み込んだ列をスキーマにマッチングするために使用する戦略を制御します。 この値を指定しない場合、デフォルトはスキーマの提供方法に基づきます。自動検出が有効になっている場合、デフォルトの動作は名前による列のマッチングです。有効になっていない場合、デフォルトは位置による列のマッチングです。これは、動作の下位互換性を維持するために行われます。 次の値がサポートされています。 POSITION: 位置でマッチングします。このオプションでは、列がスキーマと同じ順序で並んでいることを前提としています。 NAME: 名前でマッチングします。このオプションでは、ヘッダー行を列名として読み取り、スキーマのフィールド名と一致するように列の順序を変更します。列名は、skip_leading_rows プロパティに基づいて、スキップされた最後の行から読み取られます。
tags	<ARRAY<STRUCT<STRING, STRING>>> テーブルの IAM タグの配列。Key-Value ペアで表されます。キーは名前空間付きのキー名、値は略称にする必要があります。
time_zone	STRING （プレビュー） タイムゾーンが指定されていないタイムスタンプ値を解析する際に適用されるデフォルトのタイムゾーン。 有効なタイムゾーン名を確認します。 この値が指定されていない場合、特定のタイムゾーンのないタイムスタンプ値は、デフォルトのタイムゾーン UTC を使用して解析されます。 CSV データと JSON データに適用されます。
date_format	STRING （プレビュー） 入力ファイルで DATE 値の書式設定方法を定義する書式設定要素（例: MM/DD/YYYY）。 この値が指定されている場合、この形式のみが互換性のある DATE 形式となります。スキーマの自動検出では、既存の形式ではなく、この形式に基づいて DATE 列の型も決定されます。 この値が指定されていない場合、DATE フィールドはデフォルトの形式で解析されます。 CSV データと JSON データに適用されます。
datetime_format	STRING （プレビュー） 入力ファイルで DATETIME 値の書式設定方法を定義する書式設定要素（例: MM/DD/YYYY HH24:MI:SS.FF3）。 この値が指定されている場合、この形式のみが互換性のある DATETIME 形式となります。スキーマの自動検出では、既存の形式ではなく、この形式に基づいて DATETIME 列の型も決定されます。 この値が指定されていない場合、DATETIME フィールドはデフォルトの形式で解析されます。 CSV データと JSON データに適用されます。
time_format	STRING （プレビュー） 入力ファイルで TIME 値の書式設定方法を定義する書式設定要素（HH24:MI:SS.FF3 など）。 この値が指定されている場合、この形式のみが互換性のある TIME 形式となります。スキーマの自動検出では、既存の形式ではなく、この形式に基づいて TIME 列の型も決定されます。 この値が指定されていない場合、TIME フィールドはデフォルトの形式で解析されます。 CSV データと JSON データに適用されます。
timestamp_format	STRING （プレビュー） 入力ファイルで TIMESTAMP 値の書式設定方法を定義する書式設定要素（例: MM/DD/YYYY HH24:MI:SS.FF3）。 この値が指定されている場合、この形式のみが互換性のある TIMESTAMP 形式となります。スキーマの自動検出では、既存の形式ではなく、この形式に基づいて TIMESTAMP 列の型も決定されます。 この値が指定されていない場合、TIMESTAMP フィールドはデフォルトの形式で解析されます。 CSV データと JSON データに適用されます。
uris	Bigtable テーブルではない、オブジェクト テーブルを含む外部テーブルの場合は、次のようになります。 ARRAY<STRING> 外部データのロケーションの完全修飾 URI の配列。各 URI に 1 つのアスタリスク（*）のワイルドカード文字を含めることができますが、このワイルドカードはバケット名より後にある必要があります。複数のファイルをターゲットとする uris 値を指定する場合、それらのファイルはすべて互換性のあるスキーマを共有する必要があります。 次の例に、有効な uris 値を示します。 ['gs://bucket/path1/myfile.csv'] ['gs://bucket/path1/*.csv'] ['gs://bucket/path1/*', 'gs://bucket/path2/file00*'] Bigtable テーブルの場合は、次のようになります。 STRING データソースとして使用する Bigtable テーブルを識別する URI。Bigtable URI は 1 つのみ指定できます。 例: https://googleapis.com/bigtable/projects/project_id/instances/instance_id[/appProfiles/app_profile]/tables/table_name Bigtable URI の作成の詳細については、Bigtable URI の取得をご覧ください。

例

例 1:

次の例では、INFORMATION_SCHEMA.TABLE_OPTIONS ビューにクエリを実行して、デフォルト プロジェクト（myproject）にある mydataset の全テーブルのデフォルトのテーブル有効期限を取得します。

デフォルト プロジェクト以外のプロジェクトに対してクエリを実行するには、`project_id`.dataset.INFORMATION_SCHEMA.view の形式でそのプロジェクト ID をデータセットに追加します。たとえば、`myproject`.mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS です。

注: INFORMATION_SCHEMA ビューの名前では大文字と小文字が区別されます。

  SELECT
    *
  FROM
    mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
  WHERE
    option_name = 'expiration_timestamp';

次のような結果になります。

  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  | table_catalog  | table_schema  | table_name |     option_name      | option_type |             option_value             |
  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  | myproject      | mydataset     | mytable1   | expiration_timestamp | TIMESTAMP   | TIMESTAMP "2020-01-16T21:12:28.000Z" |
  | myproject      | mydataset     | mytable2   | expiration_timestamp | TIMESTAMP   | TIMESTAMP "2021-01-01T21:12:28.000Z" |
  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  

注: 有効期限のないテーブルはクエリ結果から除外されます。

例 2:

次の例では、mydataset 内のすべてのテーブルから、テストデータを含むテーブルを絞り込んでそのメタデータを取得します。このクエリでは、説明に「test」が含まれているテーブルを見つけるために description オプションの値を使用します。mydataset はデフォルト プロジェクト（myproject）にあります。

デフォルト プロジェクト以外のプロジェクトに対してクエリを実行するには、`project_id`.dataset.INFORMATION_SCHEMA.view の形式でそのプロジェクト ID をデータセットに追加します。たとえば、`myproject`.mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS です。

  SELECT
    *
  FROM
    mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
  WHERE
    option_name = 'description'
    AND option_value LIKE '%test%';

次のような結果になります。

  +----------------+---------------+------------+-------------+-------------+--------------+
  | table_catalog  | table_schema  | table_name | option_name | option_type | option_value |
  +----------------+---------------+------------+-------------+-------------+--------------+
  | myproject      | mydataset     | mytable1   | description | STRING      | "test data"  |
  | myproject      | mydataset     | mytable2   | description | STRING      | "test data"  |
  +----------------+---------------+------------+-------------+-------------+--------------+
  

COLUMNS ビュー

INFORMATION_SCHEMA.COLUMNS ビューにクエリを実行すると、クエリ結果として、テーブル内の列（フィールド）ごとに 1 行が表示されます。

INFORMATION_SCHEMA.COLUMNS ビューのスキーマは次のとおりです。

列名	データ型	値
TABLE_CATALOG	STRING	データセットを含むプロジェクトのプロジェクト ID
TABLE_SCHEMA	STRING	datasetId とも呼ばれる、テーブルを含むデータセットの名前
TABLE_NAME	STRING	テーブルまたはビューの名前（tableId とも呼ばれる）
COLUMN_NAME	STRING	列の名前
ORDINAL_POSITION	INT64	テーブル内の列の 1 から始まるオフセット。_PARTITIONTIME や _PARTITIONDATE などの疑似列の場合、値は NULL
IS_NULLABLE	STRING	YES または NO（列のモードが NULL 値を許可するかどうかによる）
DATA_TYPE	STRING	列の GoogleSQL データ型
IS_GENERATED	STRING	値は常に NEVER
GENERATION_EXPRESSION	STRING	値は常に NULL
IS_STORED	STRING	値は常に NULL
IS_HIDDEN	STRING	YES または NO（列が _PARTITIONTIME や _PARTITIONDATE などの疑似列であるかどうかによる）
IS_UPDATABLE	STRING	値は常に NULL
IS_SYSTEM_DEFINED	STRING	YES または NO（列が _PARTITIONTIME や _PARTITIONDATE などの疑似列であるかどうかによる）
IS_PARTITIONING_COLUMN	STRING	YES または NO（列がパーティショニング列かどうかによる）
CLUSTERING_ORDINAL_POSITION	INT64	テーブルのクラスタリング列内の列の 1 から始まるオフセット。テーブルがクラスタ化テーブルでない場合、値は NULL
COLLATION_NAME	STRING	照合順序の仕様の名前（存在する場合）。それ以外の場合は NULL STRING または ARRAY<STRING> が渡されると、照合指定が存在する場合は返されます。それ以外の場合は、NULL が返されます。
COLUMN_DEFAULT	STRING	列のデフォルト値（存在する場合）。それ以外の場合、値は NULL になります。
ROUNDING_MODE	STRING	フィールドの型がパラメータ化された NUMERIC または BIGNUMERIC の場合、フィールドに書き込まれる値に使用される丸めモード。それ以外の場合は、値が NULL になります。
POLICY_TAGS	ARRAY<STRING>	列に接続されているポリシータグのリスト

例

次の例では、census_bureau_usa データセットにある population_by_zip_2010 テーブルの INFORMATION_SCHEMA.COLUMNS ビューからメタデータを取得しています。このデータセットは、BigQuery の一般公開データセット プログラムの一部です。

クエリ対象のテーブルは別のプロジェクト（bigquery-public-data プロジェクト）にあるため、この形式 `project_id`.dataset.INFORMATION_SCHEMA.view でプロジェクト ID をデータセットに追加します。例: `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.TABLES

次の列は現時点で今後の使用のために予約されているため、クエリ結果から除外されます。

• IS_GENERATED
• GENERATION_EXPRESSION
• IS_STORED
• IS_UPDATABLE

注: INFORMATION_SCHEMA ビューの名前では大文字と小文字が区別されます。

  SELECT
    * EXCEPT(is_generated, generation_expression, is_stored, is_updatable)
  FROM
    `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.COLUMNS
  WHERE
    table_name = 'population_by_zip_2010';

次のような結果になります。読みやすくするため、一部の列は結果から除外されています。

+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+-------------+
|       table_name       | column_name | ordinal_position | is_nullable | data_type | is_hidden | is_system_defined | is_partitioning_column | clustering_ordinal_position | policy_tags |
+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+-------------+
| population_by_zip_2010 | zipcode     |                1 | NO          | STRING    | NO        | NO                | NO                     |                        NULL | 0 rows      |
| population_by_zip_2010 | geo_id      |                2 | YES         | STRING    | NO        | NO                | NO                     |                        NULL | 0 rows      |
| population_by_zip_2010 | minimum_age |                3 | YES         | INT64     | NO        | NO                | NO                     |                        NULL | 0 rows      |
| population_by_zip_2010 | maximum_age |                4 | YES         | INT64     | NO        | NO                | NO                     |                        NULL | 0 rows      |
| population_by_zip_2010 | gender      |                5 | YES         | STRING    | NO        | NO                | NO                     |                        NULL | 0 rows      |
| population_by_zip_2010 | population  |                6 | YES         | INT64     | NO        | NO                | NO                     |                        NULL | 0 rows      |
+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+-------------+
  

COLUMN_FIELD_PATHS ビュー

INFORMATION_SCHEMA.COLUMN_FIELD_PATHS ビューにクエリを実行すると、クエリ結果として、RECORD（または STRUCT）列内でネストされた列ごとに 1 行が表示されます。

INFORMATION_SCHEMA.COLUMN_FIELD_PATHS ビューのスキーマは次のとおりです。

列名	データ型	値
TABLE_CATALOG	STRING	データセットを含むプロジェクトのプロジェクト ID
TABLE_SCHEMA	STRING	datasetId とも呼ばれる、テーブルを含むデータセットの名前
TABLE_NAME	STRING	テーブルまたはビューの名前（tableId とも呼ばれる）
COLUMN_NAME	STRING	列の名前
FIELD_PATH	STRING	RECORD 列または STRUCT 列内でネストされた列のパス
DATA_TYPE	STRING	列の GoogleSQL データ型
DESCRIPTION	STRING	列の説明
COLLATION_NAME	STRING	照合順序の仕様の名前（存在する場合）。それ以外の場合は NULL STRUCT の STRING、ARRAY<STRING>、または STRING フィールドが渡された場合、照合順序の仕様が存在する場合はそれが返されます。それ以外の場合は、NULL が返されます。
ROUNDING_MODE	STRING	パラメータ化された NUMERIC 値または BIGNUMERIC 値に精度とスケールを適用するために使用される丸めモード。それ以外の場合は NULL の値になります。
POLICY_TAGS	ARRAY<STRING>	列に接続されているポリシータグのリスト

例

次の例では、github_repos データセットにある commits テーブルの INFORMATION_SCHEMA.COLUMN_FIELD_PATHS ビューからメタデータを取得しています。このデータセットは、BigQuery の一般公開データセット プログラムの一部です。

クエリ対象のテーブルは別のプロジェクト（bigquery-public-data プロジェクト）にあるため、この形式 `project_id`.dataset.INFORMATION_SCHEMA.view でプロジェクト ID をデータセットに追加します。例: `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS

commits テーブルには、以下のネストされた列と、ネストされた繰り返し列があります。

• author: ネストされた RECORD 列
• committer: ネストされた RECORD 列
• trailer: ネストされた繰り返しの RECORD 列
• difference: ネストされた繰り返しの RECORD 列

author 列と difference 列に関するメタデータを表示するには、次のクエリを実行します。

注: INFORMATION_SCHEMA ビューの名前では大文字と小文字が区別されます。

SELECT
  *
FROM
  `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS
WHERE
  table_name = 'commits'
  AND (column_name = 'author' OR column_name = 'difference');

次のような結果になります。読みやすくするため、一部の列は結果から除外されています。

  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------+
  | table_name | column_name |     field_path      |                                                                      data_type                                                                      | description | policy_tags |
  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------+
  | commits    | author      | author              | STRUCT<name STRING, email STRING, time_sec INT64, tz_offset INT64, date TIMESTAMP>                                                                  | NULL        | 0 rows      |
  | commits    | author      | author.name         | STRING                                                                                                                                              | NULL        | 0 rows      |
  | commits    | author      | author.email        | STRING                                                                                                                                              | NULL        | 0 rows      |
  | commits    | author      | author.time_sec     | INT64                                                                                                                                               | NULL        | 0 rows      |
  | commits    | author      | author.tz_offset    | INT64                                                                                                                                               | NULL        | 0 rows      |
  | commits    | author      | author.date         | TIMESTAMP                                                                                                                                           | NULL        | 0 rows      |
  | commits    | difference  | difference          | ARRAY<STRUCT<old_mode INT64, new_mode INT64, old_path STRING, new_path STRING, old_sha1 STRING, new_sha1 STRING, old_repo STRING, new_repo STRING>> | NULL        | 0 rows      |
  | commits    | difference  | difference.old_mode | INT64                                                                                                                                               | NULL        | 0 rows      |
  | commits    | difference  | difference.new_mode | INT64                                                                                                                                               | NULL        | 0 rows      |
  | commits    | difference  | difference.old_path | STRING                                                                                                                                              | NULL        | 0 rows      |
  | commits    | difference  | difference.new_path | STRING                                                                                                                                              | NULL        | 0 rows      |
  | commits    | difference  | difference.old_sha1 | STRING                                                                                                                                              | NULL        | 0 rows      |
  | commits    | difference  | difference.new_sha1 | STRING                                                                                                                                              | NULL        | 0 rows      |
  | commits    | difference  | difference.old_repo | STRING                                                                                                                                              | NULL        | 0 rows      |
  | commits    | difference  | difference.new_repo | STRING                                                                                                                                              | NULL        | 0 rows      |
  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------+
  

TABLE_STORAGE ビュー

TABLE_STORAGE ビューと TABLE_STORAGE_BY_ORGANIZATION ビューのスキーマは次のとおりです。

列名	データ型	値
PROJECT_ID	STRING	データセットを含むプロジェクトのプロジェクト ID。
PROJECT_NUMBER	INT64	データセットを含むプロジェクトのプロジェクト番号
TABLE_CATALOG	STRING	データセットを含むプロジェクトのプロジェクト ID。
TABLE_SCHEMA	STRING	テーブルやマテリアライズド ビューを含むデータセットの名前（datasetId とも呼ばれる）
TABLE_NAME	STRING	テーブルまたはマテリアライズド ビューの名前（tableId とも呼ばれる）
CREATION_TIME	TIMESTAMP	テーブルの作成時刻。
TOTAL_ROWS	INT64	テーブルまたはマテリアライズド ビューの行の総数
TOTAL_PARTITIONS	INT64	テーブルまたはマテリアライズド ビューに存在するパーティションの数。パーティション分割されていないテーブルは 0 を返します。
TOTAL_LOGICAL_BYTES	INT64	テーブルまたはマテリアライズド ビューの論理（非圧縮）バイトの合計数
ACTIVE_LOGICAL_BYTES	INT64	作成後 90 日未満の論理（非圧縮）バイト数。
LONG_TERM_LOGICAL_BYTES	INT64	作成後 90 日以上経過した論理（非圧縮）バイト数。
CURRENT_PHYSICAL_BYTES	INT64	テーブルの現在のストレージを表す、すべてのパーティションにわたる物理バイトの合計数。
TOTAL_PHYSICAL_BYTES	INT64	ストレージに使用されている物理（圧縮）バイトの合計数。これには、アクティブ データ、長期保存データ、タイムトラベル データ（削除または変更されたデータ）のバイト数が含まれます。フェイルセーフ（タイムトラベル期間後も保持される、削除または変更されたデータ）のバイト数は含まれません。
ACTIVE_PHYSICAL_BYTES	INT64	90 日未満の物理（圧縮）バイト数。これには、タイムトラベル（削除または変更されたデータ）のバイト数が含まれます。
LONG_TERM_PHYSICAL_BYTES	INT64	作成後 90 日以上経過した物理（圧縮）バイト数
TIME_TRAVEL_PHYSICAL_BYTES	INT64	タイムトラベル ストレージ（削除または変更されたデータ）で使用される物理（圧縮）バイト数
STORAGE_LAST_MODIFIED_TIME	TIMESTAMP	データがテーブルに最後に書き込まれた時刻。
DELETED	BOOLEAN	テーブルが削除されているかどうかを示します。
TABLE_TYPE	STRING	テーブルのタイプ。例: BASE TABLE
MANAGED_TABLE_TYPE	STRING	この列はプレビュー版です。テーブルのマネージド タイプ。たとえば、NATIVE や BIGLAKE です。
FAIL_SAFE_PHYSICAL_BYTES	INT64	フェイルセーフ ストレージで使用される物理（圧縮）バイト数（削除または変更されたデータ）
LAST_METADATA_INDEX_REFRESH_TIME	TIMESTAMP	テーブルのメタデータ インデックスの最終更新時間。
TABLE_DELETION_REASON	STRING	DELETED フィールドが true の場合のテーブル削除の理由。値は次のいずれかになります。 TABLE_EXPIRATION: 設定された有効期限が切れた後にテーブルが削除されました DATASET_DELETION: データセットがユーザーによって削除されました USER_DELETED: テーブルがユーザーによって削除されました
TABLE_DELETION_TIME	TIMESTAMP	テーブルの削除時刻。

例

例 1:

次の例では、現在のプロジェクトに対して課金される合計論理バイト数を示しています。

SELECT
  SUM(total_logical_bytes) AS total_logical_bytes
FROM
  `region-REGION`.INFORMATION_SCHEMA.TABLE_STORAGE;

次のような結果になります。

+---------------------+
| total_logical_bytes |
+---------------------+
| 971329178274633     |
+---------------------+

例 2:

次の例は、現在のプロジェクトのデータセット レベルで、さまざまなストレージ バイト数（GiB）を示しています。

SELECT
  table_schema AS dataset_name,
  -- Logical
  SUM(total_logical_bytes) / power(1024, 3) AS total_logical_gib,  
  SUM(active_logical_bytes) / power(1024, 3) AS active_logical_gib, 
  SUM(long_term_logical_bytes) / power(1024, 3) AS long_term_logical_gib, 
  -- Physical
  SUM(total_physical_bytes) / power(1024, 3) AS total_physical_gib,
  SUM(active_physical_bytes) / power(1024, 3) AS active_physical_gib,
  SUM(active_physical_bytes - time_travel_physical_bytes) / power(1024, 3) AS active_no_tt_physical_gib,
  SUM(long_term_physical_bytes) / power(1024, 3) AS long_term_physical_gib,
  SUM(time_travel_physical_bytes) / power(1024, 3) AS time_travel_physical_gib,
  SUM(fail_safe_physical_bytes) / power(1024, 3) AS fail_safe_physical_gib 
FROM
  `region-REGION`.INFORMATION_SCHEMA.TABLE_STORAGE 
WHERE 
  table_type ='BASE TABLE'
GROUP BY 
  table_schema  
ORDER BY 
  dataset_name 

例 3:

次の例では、今後 30 日間の論理課金モデルと物理課金モデルの間における、データセットあたりの料金の差を予測する方法を示しています。この例では、クエリが実行されてから 30 日間、将来のストレージ使用量が一定であることを前提としています。予測はベーステーブルに限定され、データセット内の他のタイプのテーブルはすべて除外されます。

このクエリの料金変数で使用される料金は、us-central1 リージョンのものです。別のリージョンに対してこのクエリを実行する場合は、料金変数を適宜更新してください。料金体系の詳細については、ストレージ料金をご覧ください。

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

   [BigQuery] ページに移動

2. [クエリエディタ] ボックスに、次の GoogleSQL クエリを入力します。INFORMATION_SCHEMA には GoogleSQL 構文が必要です。GoogleSQL は Google Cloud コンソールのデフォルトの構文です。

   DECLARE active_logical_gib_price FLOAT64 DEFAULT 0.02;
   DECLARE long_term_logical_gib_price FLOAT64 DEFAULT 0.01;
   DECLARE active_physical_gib_price FLOAT64 DEFAULT 0.04;
   DECLARE long_term_physical_gib_price FLOAT64 DEFAULT 0.02;
   
   WITH
    storage_sizes AS (
      SELECT
        table_schema AS dataset_name,
        -- Logical
        SUM(IF(deleted=false, active_logical_bytes, 0)) / power(1024, 3) AS active_logical_gib,
        SUM(IF(deleted=false, long_term_logical_bytes, 0)) / power(1024, 3) AS long_term_logical_gib,
        -- Physical
        SUM(active_physical_bytes) / power(1024, 3) AS active_physical_gib,
        SUM(active_physical_bytes - time_travel_physical_bytes) / power(1024, 3) AS active_no_tt_physical_gib,
        SUM(long_term_physical_bytes) / power(1024, 3) AS long_term_physical_gib,
        -- Restorable previously deleted physical
        SUM(time_travel_physical_bytes) / power(1024, 3) AS time_travel_physical_gib,
        SUM(fail_safe_physical_bytes) / power(1024, 3) AS fail_safe_physical_gib,
      FROM
        `region-REGION`.INFORMATION_SCHEMA.TABLE_STORAGE_BY_PROJECT
      WHERE total_physical_bytes + fail_safe_physical_bytes > 0
        -- Base the forecast on base tables only for highest precision results
        AND table_type  = 'BASE TABLE'
        GROUP BY 1
    )
   SELECT
     dataset_name,
     -- Logical
     ROUND(active_logical_gib, 2) AS active_logical_gib,
     ROUND(long_term_logical_gib, 2) AS long_term_logical_gib,
     -- Physical
     ROUND(active_physical_gib, 2) AS active_physical_gib,
     ROUND(long_term_physical_gib, 2) AS long_term_physical_gib,
     ROUND(time_travel_physical_gib, 2) AS time_travel_physical_gib,
     ROUND(fail_safe_physical_gib, 2) AS fail_safe_physical_gib,
     -- Compression ratio
     ROUND(SAFE_DIVIDE(active_logical_gib, active_no_tt_physical_gib), 2) AS active_compression_ratio,
     ROUND(SAFE_DIVIDE(long_term_logical_gib, long_term_physical_gib), 2) AS long_term_compression_ratio,
     -- Forecast costs logical
     ROUND(active_logical_gib * active_logical_gib_price, 2) AS forecast_active_logical_cost,
     ROUND(long_term_logical_gib * long_term_logical_gib_price, 2) AS forecast_long_term_logical_cost,
     -- Forecast costs physical
     ROUND((active_no_tt_physical_gib + time_travel_physical_gib + fail_safe_physical_gib) * active_physical_gib_price, 2) AS forecast_active_physical_cost,
     ROUND(long_term_physical_gib * long_term_physical_gib_price, 2) AS forecast_long_term_physical_cost,
     -- Forecast costs total
     ROUND(((active_logical_gib * active_logical_gib_price) + (long_term_logical_gib * long_term_logical_gib_price)) -
        (((active_no_tt_physical_gib + time_travel_physical_gib + fail_safe_physical_gib) * active_physical_gib_price) + (long_term_physical_gib * long_term_physical_gib_price)), 2) AS forecast_total_cost_difference
   FROM
     storage_sizes
   ORDER BY
     (forecast_active_logical_cost + forecast_active_physical_cost) DESC;

   注: INFORMATION_SCHEMA ビューの名前では大文字と小文字が区別されます。

3. [実行] をクリックします。

次のような結果になります。

+--------------+--------------------+-----------------------+---------------------+------------------------+--------------------------+-----------------------------+------------------------------+----------------------------------+-------------------------------+----------------------------------+--------------------------------+
| dataset_name | active_logical_gib | long_term_logical_gib | active_physical_gib | long_term_physical_gib | active_compression_ratio | long_term_compression_ratio | forecast_active_logical_cost | forecaset_long_term_logical_cost | forecast_active_physical_cost | forecast_long_term_physical_cost | forecast_total_cost_difference |
+--------------+--------------------+-----------------------+---------------------+------------------------+--------------------------+-----------------------------+------------------------------+----------------------------------+-------------------------------+----------------------------------+--------------------------------+
| dataset1     |               10.0 |                  10.0 |                 1.0 |                    1.0 |                     10.0 |                        10.0 |                          0.2 |                              0.1 |                          0.04 |                             0.02 |                           0.24 |

データセットに含まれるテーブルを一覧表示する

データセット内のテーブルは、次の方法で一覧表示できます。

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

必要な権限

データセットに含まれるテーブルを一覧表示するには、少なくとも bigquery.tables.list 権限が付与されている必要があります。次の IAM 事前定義ロールには bigquery.tables.list 権限が含まれています。

• bigquery.user
• bigquery.metadataViewer
• bigquery.dataViewer
• bigquery.dataEditor
• bigquery.dataOwner
• bigquery.admin

BigQuery での IAM ロールと権限の詳細については、アクセス制御をご覧ください。

テーブルのリスト表示

データセット内のテーブルを一覧表示する場合:

コンソール

1. Google Cloud コンソールのナビゲーション パネルで、データセット名をクリックして展開します。これにより、データセット内のテーブルとビューが表示されます。

2. リストをスクロールして、データセット内のテーブルを表示します。テーブルとビューはアイコンで区別できます。

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. bq ls コマンドを発行します。--format フラグを使用して出力を制御できます。デフォルト プロジェクト以外のプロジェクトにあるテーブルを一覧表示する場合は、project_id:dataset の形式でプロジェクト ID をデータセットに追加します。

   その他のフラグ

   • --max_results または -n : 結果の最大数を示す整数。デフォルト値は 50 です。

   bq ls \
   --format=pretty \
   --max_results integer \
   project_id:dataset

   ここで

   • integer は一覧表示するテーブルの数を表す整数です。
   • project_id はプロジェクト ID です。
   • dataset は、データセットの名前です。

   このコマンドを実行すると、Type フィールドに TABLE または VIEW が表示されます。例:

   +-------------------------+-------+----------------------+-------------------+
   |         tableId         | Type  |        Labels        | Time Partitioning |
   +-------------------------+-------+----------------------+-------------------+
   | mytable                 | TABLE | department:shipping  |                   |
   | myview                  | VIEW  |                      |                   |
   +-------------------------+-------+----------------------+-------------------+
   

   例:

   次のコマンドを入力すると、デフォルト プロジェクトにある mydataset データセット内のテーブルが一覧表示されます。

      bq ls --format=pretty mydataset

   次のコマンドを入力して、mydataset からデフォルト出力数の 50 を超えるテーブルを返します。mydataset はデフォルト プロジェクトにあります。

      bq ls --format=pretty --max_results 60 mydataset

   次のコマンドを入力すると、myotherproject にある mydataset データセット内のテーブルが一覧表示されます。

      bq ls --format=pretty myotherproject:mydataset

API

API を使用してテーブルを一覧表示するには、tables.list メソッドを呼び出します。

C#

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

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

using Google.Cloud.BigQuery.V2;
using System;
using System.Collections.Generic;
using System.Linq;

public class BigQueryListTables
{
    public void ListTables(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Retrieve list of tables in the dataset
        List<BigQueryTable> tables = client.ListTables(datasetId).ToList();
        // Display the results
        if (tables.Count > 0)
        {
            Console.WriteLine($"Tables in dataset {datasetId}:");
            foreach (var table in tables)
            {
                Console.WriteLine($"\t{table.Reference.TableId}");
            }
        }
        else
        {
            Console.WriteLine($"{datasetId} does not contain any tables.");
        }
    }
}

Go

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

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

import (
	"context"
	"fmt"
	"io"

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

// listTables demonstrates iterating through the collection of tables in a given dataset.
func listTables(w io.Writer, projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	ts := client.Dataset(datasetID).Tables(ctx)
	for {
		t, err := ts.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Table: %q\n", t.TableID)
	}
	return nil
}

Java

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

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

import com.google.api.gax.paging.Page;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQuery.TableListOption;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.DatasetId;
import com.google.cloud.bigquery.Table;

public class ListTables {

  public static void runListTables() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "bigquery-public-data";
    String datasetName = "samples";
    listTables(projectId, datasetName);
  }

  public static void listTables(String projectId, String datasetName) {
    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();

      DatasetId datasetId = DatasetId.of(projectId, datasetName);
      Page<Table> tables = bigquery.listTables(datasetId, TableListOption.pageSize(100));
      tables.iterateAll().forEach(table -> System.out.print(table.getTableId().getTable() + "\n"));

      System.out.println("Tables listed successfully.");
    } catch (BigQueryException e) {
      System.out.println("Tables were not listed. Error occurred: " + e.toString());
    }
  }
}

Node.js

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

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

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

async function listTables() {
  // Lists tables in 'my_dataset'.

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

  // List all tables in the dataset
  const [tables] = await bigquery.dataset(datasetId).getTables();

  console.log('Tables:');
  tables.forEach(table => console.log(table.id));
}

PHP

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

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

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$tables = $dataset->tables();
foreach ($tables as $table) {
    print($table->id() . PHP_EOL);
}

Python

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

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

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset that contains
#                  the tables you are listing.
# dataset_id = 'your-project.your_dataset'

tables = client.list_tables(dataset_id)  # Make an API request.

print("Tables contained in '{}':".format(dataset_id))
for table in tables:
    print("{}.{}.{}".format(table.project, table.dataset_id, table.table_id))

Ruby

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

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

require "google/cloud/bigquery"

def list_tables dataset_id = "your_dataset_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id

  puts "Tables in dataset #{dataset_id}:"
  dataset.tables.each do |table|
    puts "\t#{table.table_id}"
  end
end

監査テーブルの履歴

ログ エクスプローラで Cloud Audit Logs をクエリすることで、BigQuery テーブルの履歴を監査できます。これらのログは、テーブルが作成、更新、削除された日時を追跡し、変更を行ったユーザーまたはサービス アカウントを特定するのに役立ちます。

必要な権限

監査ログを閲覧するには、roles/logging.privateLogViewer ロールが必要です。Cloud Logging の IAM ロールと権限の詳細については、IAM を使用したアクセス制御をご覧ください。

監査データを取得する

監査情報には、 Google Cloud コンソール、gcloud コマンドライン、REST API、およびクライアント ライブラリを使用してサポートされているすべての言語からアクセスできます。次の例に示すロギング フィルタは、使用するメソッドに関係なく使用できます。

1. Google Cloud コンソールで [Logging] ページに移動します。

   Logging に移動

2. 次のクエリを使用して、監査データにアクセスします。

   logName = "projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity"
   AND resource.type = "bigquery_dataset"
   AND timestamp >= "STARTING_TIMESTAMP"
   AND protoPayload.@type = "type.googleapis.com/google.cloud.audit.AuditLog"
   AND (
     protoPayload.metadata.tableCreation :*
     OR protoPayload.metadata.tableChange :*
     OR protoPayload.metadata.tableDeletion :*
   )
   AND protoPayload.resourceName : "projects/PROJECT_ID/datasets/DATASET_ID/tables/"
   

次のように置き換えます。

• PROJECT_ID: 目的のデータセットとテーブルを含むプロジェクト。
• STARTING_TIMESTAMP: 表示する最も古いログ。ISO 8601 形式（2025-01-01 や 2025-02-03T04:05:06Z など）を使用します。
• DATASET_ID: フィルタするデータセット。

結果を解釈する

ログ エクスプローラの [結果] ペインで、目的のエントリを開き、[ネストされたフィールドを展開] をクリックしてメッセージ全体を表示します。

ロギング エントリには、実行されたオペレーションを示す次のオブジェクトのいずれか 1 つのみが含まれます。

• protoPayload.metadata.tableCreation: テーブルが作成されました。
• protoPayload.metadata.tableChange: スキーマの更新、説明の変更、テーブルの置換など、テーブルのメタデータが変更されました。
• protoPayload.metadata.tableDeletion: テーブルが削除されました。

これらのオブジェクトの内容は、リクエストされたアクションを表します。詳細については、BigQueryAuditMetadata をご覧ください。

クエリの説明

• logName = "projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity": この行は、 Google Cloudプロジェクト内の管理アクティビティ監査ログをフィルタします。これらのログには、リソースの構成やメタデータを変更する API 呼び出しやアクションが記録されます。
• resource.type = "bigquery_dataset": これにより、テーブル オペレーションがロギングされる BigQuery データセットに関連するイベントに検索が絞り込まれます。
• timestamp >= "STARTING_TIMESTAMP": ログエントリをフィルタして、指定したタイムスタンプ以降に作成されたエントリのみを表示します。
• protoPayload.@type = "type.googleapis.com/google.cloud.audit.AuditLog": ログメッセージが標準の Cloud Audit Log 構造に準拠していることを確認します。
• ( ... ): このブロックは、前のセクションで説明したように、さまざまなタイプのテーブル イベントを見つけるための条件をグループ化します。:* 演算子は、キーが存在する必要があることを示します。テーブルの作成など、1 つのイベントのみに関心がある場合は、このブロックから不要な条件を削除します。

• protoPayload.resourceName : "projects/PROJECT_ID/datasets/DATASET_ID/tables/": 指定されたデータセットに含まれるテーブルと一致するログエントリを選択します。コロン（:）演算子は部分文字列検索を実行します。

  • 単一のテーブルのエントリをフィルタリングするには、条件を protoPayload.resourceName = "projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME" に置き換えます。
  • 特定のプロジェクト内のすべてのデータセットのすべてのテーブルを含めるには、この条件を削除します。

ログのフィルタリングの詳細については、Logging のクエリ言語をご覧ください。

テーブルのセキュリティ

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

次のステップ

• データセットの詳細については、データセットの概要をご覧ください。
• テーブルデータの処理の詳細については、テーブルデータの管理をご覧ください。
• テーブル スキーマの指定の詳細については、スキーマの指定をご覧ください。
• テーブル スキーマの変更の詳細については、テーブル スキーマの変更をご覧ください。
• テーブルの管理の詳細については、テーブルの管理をご覧ください。
• INFORMATION_SCHEMA の概要については、BigQuery INFORMATION_SCHEMA の概要をご覧ください。

使ってみる

Google Cloud を初めて使用される方は、アカウントを作成して、実際のシナリオでの BigQuery のパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

BigQuery の無料トライアル