標準 SQL のデータ定義言語（DDL）ステートメント

データ定義言語（DDL）ステートメントを使用すると、標準 SQL クエリ構文を使用して BigQuery リソースを作成および変更できます。DDL コマンドを使用して、次のようなリソースを作成、変更、および削除できます。テーブル、テーブル クローン、テーブルのスナップショット、ビュー、ユーザー定義関数（UDF）、行レベルのアクセス ポリシー。

必要な権限

DDL ステートメントを実行するジョブを作成するには、ジョブを実行するプロジェクトに対する bigquery.jobs.create 権限を付与されている必要があります。各 DDL ステートメントには、影響を受けるリソースに対する特定の権限も必要です。これは各ステートメントに記載されています。

IAM 役割

IAM の事前定義ロール bigquery.user、bigquery.jobUser、bigquery.admin には、必要な bigquery.jobs.create 権限が含まれています。

BigQuery の IAM ロールの概要については、事前定義ロールと権限または IAM 権限のリファレンスをご覧ください。

DDL ステートメントの実行

DDL ステートメントを実行するには、コンソールを使用する、bq コマンドライン ツールを使用する、jobs.query REST API を呼び出す、プログラムで BigQuery API クライアント ライブラリを使用する、などの方法があります。

コンソール

  1. コンソールの [BigQuery] ページに移動します。

    BigQuery に移動

  2. [クエリを新規作成] をクリックします。

    クエリの新規作成

  3. [クエリエディタ] テキスト領域に DDL ステートメントを入力します。次に例を示します。

     CREATE TABLE mydataset.newtable ( x INT64 )

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

bq

bq query コマンドを入力し、DDL ステートメントをクエリ パラメータとして指定します。use_legacy_sql フラグを false に設定します。

bq query --use_legacy_sql=false \
  'CREATE TABLE mydataset.newtable ( x INT64 )'

API

jobs.query メソッドを呼び出し、リクエスト本文の query プロパティで DDL ステートメントを指定します。

DDL 機能により、ジョブリソースによって返される情報が拡張されます。statistics.query.statementType には、DDL サポート用の次の追加の値が含まれます。

  • CREATE_TABLE
  • CREATE_TABLE_AS_SELECT
  • DROP_TABLE
  • CREATE_VIEW
  • DROP_VIEW

statistics.query には次の 2 つの追加のフィールドがあります。

  • ddlOperationPerformed: 実行された DDL オペレーションであり、DDL ターゲットの存在に依存する可能性があります。現在の値は次のとおりです。
    • CREATE: クエリによって DDL ターゲットが作成されました。
    • SKIP: 処理なし。例 - CREATE TABLE IF NOT EXISTS が送信され、テーブルが存在します。または、DROP TABLE IF EXISTS が送信され、テーブルが存在しません。
    • REPLACE: クエリによって DDL ターゲットが置き換えられました。例 - CREATE OR REPLACE TABLE が送信され、テーブルはすでに存在しています。
    • DROP: クエリによって DDL ターゲットが削除されました。
  • ddlTargetTable: CREATE TABLE/VIEW ステートメントまたは DROP TABLE/VIEW ステートメントを送信すると、次の 3 つのフィールドを持つオブジェクトとしてターゲット テーブルが返されます。
    • "projectId": string
    • "datasetId": string
    • "tableId": string

Java

BigQuery.create() メソッドを呼び出し、クエリジョブを開始します。Job.waitFor() メソッドを呼び出し、DDL クエリが完了するまで待ちます。

samples/snippets/src/main/java/com/example/bigquery/DDLCreateView.java 
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.QueryJobConfiguration;

// Sample to create a view using DDL
public class DDLCreateView {

  public static void runDDLCreateView() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetId = "MY_DATASET_ID";
    String tableId = "MY_VIEW_ID";
    String ddl =
        "CREATE VIEW "
            + "`"
            + projectId
            + "."
            + datasetId
            + "."
            + tableId
            + "`"
            + " OPTIONS("
            + " expiration_timestamp=TIMESTAMP_ADD("
            + " CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),"
            + " friendly_name=\"new_view\","
            + " description=\"a view that expires in 2 days\","
            + " labels=[(\"org_unit\", \"development\")]"
            + " )"
            + " AS SELECT name, state, year, number"
            + " FROM `bigquery-public-data.usa_names.usa_1910_current`"
            + " WHERE state LIKE 'W%'`";
    ddlCreateView(ddl);
  }

  public static void ddlCreateView(String ddl) {
    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();

      QueryJobConfiguration config = QueryJobConfiguration.newBuilder(ddl).build();

      // create a view using query and it will wait to complete job.
      Job job = bigquery.create(JobInfo.of(config));
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("View created successfully");
      } else {
        System.out.println("View was not created");
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("View was not created. \n" + e.toString());
    }
  }
}

Node.js

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

async function ddlCreateView() {
  // Creates a view via a DDL query

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

  const query = `
  CREATE VIEW \`${projectId}.${datasetId}.${tableId}\`
  OPTIONS(
      expiration_timestamp=TIMESTAMP_ADD(
          CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
      friendly_name="new_view",
      description="a view that expires in 2 days",
      labels=[("org_unit", "development")]
  )
  AS SELECT name, state, year, number
      FROM \`bigquery-public-data.usa_names.usa_1910_current\`
      WHERE state LIKE 'W%'`;

  // For all options, see https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query
  const options = {
    query: query,
  };

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

  job.on('complete', metadata => {
    console.log(`Created new view ${tableId} via job ${metadata.id}`);
  });
}

Python

Client.query() メソッドを呼び出し、クエリジョブを開始します。QueryJob.result() メソッドを呼び出し、DDL クエリが完了するまで待ちます。

docs/snippets.py 
# from google.cloud import bigquery
# project = 'my-project'
# dataset_id = 'my_dataset'
# table_id = 'new_view'
# client = bigquery.Client(project=project)

sql = """
CREATE VIEW `{}.{}.{}`
OPTIONS(
    expiration_timestamp=TIMESTAMP_ADD(
        CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
    friendly_name="new_view",
    description="a view that expires in 2 days",
    labels=[("org_unit", "development")]
)
AS SELECT name, state, year, number
    FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state LIKE 'W%'
""".format(
    project, dataset_id, table_id
)

job = client.query(sql)  # API request.
job.result()  # Waits for the query to finish.

print(
    'Created new view "{}.{}.{}".'.format(
        job.destination.project,
        job.destination.dataset_id,
        job.destination.table_id,
    )
)

CREATE SCHEMA ステートメント

新しいデータセットを作成します。

構文

CREATE SCHEMA [ IF NOT EXISTS ]
[project_name.]dataset_name
[DEFAULT COLLATE collate_specification]
[OPTIONS(schema_option_list)]

引数

  • IF NOT EXISTS: 同じ名前のデータセットが存在する場合、CREATE ステートメントは無効になります。OR REPLACE と一緒には使用できません。

  • DEFAULT COLLATE collate_specification: スキーマに新しいテーブルが作成されると、列 に対して照合仕様が明示的に指定されていない限り、テーブルに対してデフォルトの照合仕様が継承されます。

    後で ALTER SCHEMA ステートメントを使用してこの照合仕様を削除または変更しても、このスキーマの既存の照合仕様は変更されません。スキーマ内の既存の照合仕様を更新する場合は、仕様を含む列を変更する必要があります。

  • project_name: データセットを作成するプロジェクトの名前。デフォルトでは、この DDL ステートメントを実行するプロジェクトの名前が設定されます。

  • dataset_name: 作成するデータセットの名前。

  • schema_option_list: データセットを作成するためのオプションのリスト。

詳細

データセットは、クエリ設定で指定したロケーションに作成されます。詳細については、ロケーションの指定をご覧ください。

データセット作成の詳細については、データセットの作成をご覧ください。割り当ての詳細については、データセットの制限をご覧ください。

schema_option_list

オプション リストは、データセットのオプションを指定します。NAME=VALUE, ... の形式でオプションを指定します。

次のオプションがサポートされています。

NAME VALUE 詳細
default_kms_key_name STRING このデータセット内のテーブルデータを暗号化するためのデフォルトの Cloud KMS 鍵を指定します。テーブルの作成時にこの値をオーバーライドできます。
default_partition_expiration_days FLOAT64 このデータセットのテーブル パーティションのデフォルトの有効期限を日数で指定します。テーブルの作成時にこの値をオーバーライドできます。
default_table_expiration_days FLOAT64 このデータセットのテーブルのデフォルトの有効期限を日数で指定します。テーブルの作成時にこの値をオーバーライドできます。
description STRING データセットの説明。
friendly_name STRING データセットのわかりやすい名前。
labels <ARRAY<STRUCT<STRING, STRING>>> Key-Value ペアで表現されるデータセットのラベルの配列。
location STRING データセットを作成するロケーション。このオプションを指定しない場合、クエリが実行されるロケーションにデータセットが作成されます。このオプションを指定してクエリジョブのロケーションを明示的に設定する場合は、2 つの値が一致する必要があります。それ以外の場合、クエリは失敗します。
max_time_travel_hours SMALLINT

プレビュー版

データセットのタイムトラベル期間を時間で指定します。max_time_travel_hours 値は、整数の 48（2 日）～168（7 日）にする必要があります。このフラグを指定しない場合のデフォルトは 168 時間です。

タイムトラベル期間の詳細については、タイムトラベル期間の構成をご覧ください。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.datasets.create データセットを作成するプロジェクト。

Examples

新しいスキーマの作成

次の例では、デフォルトのテーブル有効期限と一連のラベルを含むデータセットを作成します。

CREATE SCHEMA mydataset
OPTIONS(
  location="us",
  default_table_expiration_days=3.75,
  labels=[("label1","value1"),("label2","value2")]
  )

照合をサポートするスキーマの作成

次の例では、照合仕様を含むデータセットを作成します。

CREATE SCHEMA mydataset
DEFAULT COLLATE 'und:ci'

CREATE TABLE ステートメント

新しいテーブルを作成します。

構文

CREATE [ OR REPLACE ] [ TEMP | TEMPORARY ] TABLE [ IF NOT EXISTS ]
table_name
[(
  column[, ...]
)]
[DEFAULT COLLATE collate_specification]
[PARTITION BY partition_expression]
[CLUSTER BY clustering_column_list]
[OPTIONS(table_option_list)]
[AS query_statement]

引数

  • OR REPLACE: 同じ名前のテーブルが存在する場合は、置き換えます。IF NOT EXISTS と一緒には使用できません。

  • TEMP | TEMPORARY: 一時テーブルを作成します。

  • IF NOT EXISTS: 同じ名前のテーブルが存在する場合、CREATE ステートメントは無効になります。OR REPLACE と一緒には使用できません。

  • table_name: 作成するテーブルの名前。テーブルパスの構文をご覧ください。一時テーブルの場合、プロジェクト名またはデータセット名を含めないでください。

  • column: テーブルのスキーマ情報。

  • collation_specification: スキーマで新しい列が作成され、列に明示的な照合仕様がない場合、列は STRING 型に関するこの照合仕様を継承します。

    後で ALTER TABLE ステートメントを使用してこの照合仕様を削除または変更しても、このテーブルの既存の照合仕様は変更されません。テーブル内の既存の照合仕様を更新する場合は、仕様を含む列を変更する必要があります。

    テーブルがスキーマの一部である場合、このテーブルのデフォルトの照合仕様は、スキーマのデフォルトの照合仕様をオーバーライドします。

  • partition_expression: テーブルのパーティショニング方法を決める式。

  • clustering_column_list: テーブルのクラスタ化の方法を決定する列参照のカンマ区切りリスト。このリストの列には照合を使用できません。

  • table_option_list: テーブルを作成するためのオプションのリスト。

  • query_statement: テーブルの作成元のクエリ。クエリ構文については、SQL 構文リファレンスをご覧ください。{: #query_statement } このテーブルで照合仕様が使用されている場合、照合はこのクエリ ステートメントを通過します。

詳細

CREATE TABLE ステートメントは、以下の規則に従う必要があります。

  • 使用できる CREATE ステートメントは 1 つのみです。
  • 列リストと as query_statement 句のいずれかまたは両方が存在する必要があります。
  • 列リストと as query_statement 句の両方が存在する場合、BigQuery は、as query_statement 句内の名前を無視し、位置に基づいて列を列リストに一致させます。
  • as query_statement 句が存在し、列リストが存在しない場合、BigQuery は、列の名前と型を as query_statement 句から判断します。
  • 列名は、列リスト、as query_statement 句、または LIKE 句のテーブルのスキーマのいずれかを使用して指定する必要があります。
  • 列名を重複させることはできません。
  • LIKE 句と as query_statement 句の両方が存在する場合、クエリ ステートメントの列リストは、LIKE 句が参照するテーブルの列と一致する必要があります。

制限事項:

  • クエリ結果から取り込み時間パーティション分割テーブルを作成することはできません。その代わりに、CREATE TABLE DDL ステートメントを使用して取り込み時間パーティション分割テーブルを作成した後、INSERT DML ステートメントを使用してそのテーブルにデータを挿入します。
  • OR REPLACE 修飾子を使用してテーブルを別の種類のパーティショニングで置き換えることはできません。その代わりに、テーブルに対して DROP を行った後、CREATE TABLE ... AS SELECT ... ステートメントを使用

このステートメントでは、次のバリアントがサポートされています。

  • CREATE TABLE LIKE: 既存のテーブルと同じスキーマのテーブルを作成します。
  • CREATE TABLE COPY: 既存のテーブルからスキーマとデータをコピーしてテーブルを作成します。

column

(column_name column_schema[, ...]) には、テーブルのスキーマ情報がカンマ区切りリストで含まれています。

column :=
  column_name column_schema

column_schema :=
   {
     simple_type [NOT NULL]
     | STRUCT<field_list> [NOT NULL]
     | ARRAY<array_element_schema>
   }
   [OPTIONS(column_option_list)]

field_list :=
  field_name column_schema [, ...]

array_element_schema :=
  { simple_type | STRUCT<field_list> }
  [NOT NULL]

simple_type :=
  { data_type | STRING COLLATE collate_specification }

  • column_name は、列の名前です。列名の要件は次のとおりです。

    • 英字（大文字または小文字）、数字（0～9）、アンダースコア（_）だけが含まれている
    • 英字またはアンダースコアで始まっている
    • 300 文字以内である

  • column_schema: データ型に似ていますが、ARRAY 以外の型に対してはオプションの NOT NULL 制約をサポートします。column_schema は、トップレベルの列と STRUCT フィールドに対するオプションもサポートします。

    column_schema は、CREATE TABLE ステートメントの列定義リストでのみ使用できます。式の中の型として使用することはできません。対象

  • simple_type: サポートされている任意のデータ型（STRUCT と ARRAY は除く）。

    simple_type が STRING の場合、生成される STRING の比較と並べ替えの方法を定義する照合の追加句がサポートされます。構文は次のとおりです。

    STRING COLLATE collate_specification

    DEFAULT COLLATE collate_specification がテーブルに割り当てられている場合は、列の照合仕様がテーブルの仕様をオーバーライドします。

  • field_list: STRUCT 内のフィールドを表します。

  • field_name: 構造体フィールドの名前。構造体フィールドの名前には列名と同じ制約があります。

  • NOT NULL: 列またはフィールドに対して NOT NULL 制約が存在する場合、その列またはフィールドは REQUIRED モードで作成されます。逆に、列またはフィールドに対して NOT NULL 制約がない場合、その列またはフィールドは NULLABLE モードで作成されます。

    ARRAY 型の列とフィールドでは NOT NULL 修飾子はサポートされていません。たとえば、ARRAY<INT64> NOT NULL という column_schema は無効です。その理由は、ARRAY 列には REPEATED モードがあり、列を空にすることはできますが、NULL にすることはできないためです。NOT NULL 制約が指定されているかどうかにかかわらず、テーブル内の配列要素を NULL にすることはできません。たとえば、ARRAY<INT64> は ARRAY<INT64 NOT NULL> と同じです。

    テーブルの column_schema の NOT NULL 属性は、テーブルに対するクエリを通じて伝播されません。たとえば、テーブル T に x INT64 NOT NULL として宣言されている列がある場合、CREATE TABLE dataset.newtable AS SELECT x FROM T によって x が NULLABLE である dataset.newtable という名前のテーブルが作成されます。

partition_expression

PARTITION BY は、テーブルのパーティショニングを制御するオプションの句です。partition_expression は、テーブルのパーティショニング方法を決める式です。パーティション式には次の値を使用できます。

  • _PARTITIONDATE。日別パーティションを使用して取り込み時間で分割します。この構文は AS query_statement 句と一緒には使用できません。
  • DATE(_PARTITIONTIME)。_PARTITIONDATE に相当します。この構文は AS query_statement 句と一緒には使用できません。
  • <date_column>。日別パーティションを使用して DATE 列で分割します。
  • DATE({ <timestamp_column> | <datetime_column> })。日別パーティションを使用して TIMESTAMP 列または DATETIME 列で分割します。
  • DATETIME_TRUNC(<datetime_column>, { DAY | HOUR | MONTH | YEAR })。指定したパーティショニング タイプを使用して DATETIME 列で分割します。
  • TIMESTAMP_TRUNC(<timestamp_column>, { DAY | HOUR | MONTH | YEAR })。指定したパーティショニング タイプを使用して TIMESTAMP 列で分割します。
  • TIMESTAMP_TRUNC(_PARTITIONTIME, { DAY | HOUR | MONTH | YEAR })。指定したパーティショニング タイプを使用して取り込み時間で分割します。この構文は AS query_statement 句と一緒には使用できません。
  • DATE_TRUNC(<date_column>, { MONTH | YEAR })。指定したパーティショニング タイプを使用して DATE 列で分割します。

  • RANGE_BUCKET(<int64_column>, GENERATE_ARRAY(<start>, <end>[, <interval>]))。指定された範囲で整数列で分割します。

    • start は範囲パーティショニングの開始値です。パーティションにはこの値も含まれます。
    • end は範囲パーティショニングの終了値です。パーティションにこの値は含まれません。
    • interval はパーティション内の各範囲の幅です。デフォルトは 1 です。

clustering_column_list

CLUSTER BY は、テーブルのクラスタ化を制御するオプションの句です。clustering_column_list は、テーブルのクラスタ化方法を決めるカンマ区切りのリストです。クラスタ化列リストには、4 個までのクラスタ化列を含めることができます。

table_option_list

オプション リストを使用すると、ラベルや有効期限などのテーブル オプションを設定できます。カンマ区切りのリストを使用して複数のオプションを含めることができます。

テーブル オプション リストは次の形式で指定します。

NAME=VALUE, ...

NAME と VALUE は、次のいずれかの組み合わせである必要があります。

NAME VALUE 詳細
expiration_timestamp TIMESTAMP

例: expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

このプロパティは、expirationTime テーブル リソース プロパティと同等です。
partition_expiration_days

FLOAT64

例: partition_expiration_days=7

パーティションの有効期限を日数で設定します。詳細については、パーティションの有効期限の設定をご覧ください。デフォルトでは、パーティションは期限切れになりません。

このプロパティは、timePartitioning.expirationMs テーブル リソース プロパティと同等ですが、単位はミリ秒ではなく日数です。1 日は 86,400,000 ミリ秒または 24 時間に相当します。

このプロパティは、テーブルが分割されている場合にのみ設定できます。
require_partition_filter

BOOL

例: require_partition_filter=true

このテーブルのクエリに、パーティショニングする列を除外する述語フィルタを含める必要があるかどうかを指定します。詳細については、パーティション フィルタの要件を設定するをご覧ください。デフォルト値は false です。

このプロパティは、timePartitioning.requirePartitionFilter テーブル リソース プロパティと同等です。

このプロパティは、テーブルが分割されている場合にのみ設定できます。
kms_key_name

STRING

例: kms_key_name="projects/project_id/locations/location/keyRings/keyring/cryptoKeys/key"

このプロパティは、encryptionConfiguration.kmsKeyName テーブル リソース プロパティと同等です。

詳細については、Cloud KMS 鍵によるデータの保護をご覧ください。
friendly_name

STRING

例: friendly_name="my_table"

このプロパティは、friendlyName テーブル リソース プロパティと同等です。
description

STRING

例: description="a table that expires in 2025"

このプロパティは、description テーブル リソース プロパティと同等です。
labels

ARRAY<STRUCT<STRING, STRING>>

例: labels=[("org_unit", "development")]

このプロパティは、labels テーブル リソース プロパティと同等です。

VALUE は、リテラル、クエリ パラメータ、スカラー関数のみを含む定数式です。

定数式には以下を含めることはできません。

  • テーブルへの参照
  • サブクエリ、または SELECT、CREATE、UPDATE などの SQL ステートメント。
  • ユーザー定義関数、集計関数、または分析関数
  • 以下のスカラー関数
    • ARRAY_TO_STRING
    • REPLACE
    • REGEXP_REPLACE
    • RAND
    • FORMAT
    • LPAD
    • RPAD
    • REPEAT
    • SESSION_USER
    • GENERATE_ARRAY
    • GENERATE_DATE_ARRAY

VALUE が NULL と評価された場合、CREATE TABLE ステートメント内の対応する NAME オプションは無視されます。

column_option_list

column_schema 内で column_option_list を使用すると、省略可能な列またはフィールドのオプションを指定できます。列のオプションの構文と要件はテーブル オプションの場合と同じですが、NAME と VALUE のリストは異なります。

NAME VALUE 詳細
description

STRING

例: description="a unique id"

このプロパティは、schema.fields[].description テーブル リソース プロパティと同等です。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.tables.create テーブルを作成するデータセット。

さらに、OR REPLACE 句には bigquery.tables.update 権限と bigquery.tables.updateData 権限が割り当てられている必要があります。

OPTIONS 句に有効期限オプションが含まれている場合は、bigquery.tables.delete 権限も必要です。

Examples

新しいテーブルの作成

次の例では、mydataset に newtable という名前のパーティション分割テーブルが作成されます。

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
  >
)
PARTITION BY _PARTITIONDATE
OPTIONS(
  expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC",
  partition_expiration_days=1,
  description="a table that expires in 2025, with each partition living for 24 hours",
  labels=[("org_unit", "development")]
)

デフォルト プロジェクトを構成していない場合は、プロジェクト ID をサンプル SQL のデータセット名の前に追加し、project_id に特殊文字 `project_id.dataset.table` が含まれる場合は、バッククォートで名前を囲みます。したがって、mydataset.newtable の代わりに、テーブル修飾子が `myproject.mydataset.newtable` であることがあります。

テーブル名がデータセット内に存在する場合は、次のエラーが返されます。

Already Exists: project_id:dataset.table

PARTITION BY _PARTITIONDATE という partition_expression を使用してテーブルがパーティショニング（分割）されます。この式は、_PARTITIONDATE 擬似列に日付を使用してテーブルを分割します。

テーブル スキーマには次の 2 つの列があります。

  • x: 整数と、「オプション INTEGER 型フィールド」の説明

  • y: 次の 2 つの列を含む STRUCT

    • a: 文字列の配列と、「繰り返し STRING 型フィールド」の説明
    • b: ブール値

テーブル オプション リストで指定する内容は次のとおりです。

  • テーブルの有効期限: 2025 年 1 月 1 日 00:00:00 UTC
  • パーティションの有効期限: 1 日
  • 説明: A table that expires in 2025
  • ラベル: org_unit = development

既存のテーブルから新しいテーブルを作成する

次の例では、クエリから top_words という名前のテーブルを mydataset 内に作成します。

CREATE TABLE mydataset.top_words
OPTIONS(
  description="Top ten words per Shakespeare corpus"
) AS
SELECT
  corpus,
  ARRAY_AGG(STRUCT(word, word_count) ORDER BY word_count DESC LIMIT 10) AS top_words
FROM bigquery-public-data.samples.shakespeare
GROUP BY corpus;

デフォルト プロジェクトを構成していない場合は、プロジェクト ID をサンプル SQL のデータセット名の前に追加し、project_id に特殊文字 `project_id.dataset.table` が含まれる場合は、バッククォートで名前を囲みます。したがって、mydataset.top_words の代わりに、テーブル修飾子が `myproject.mydataset.top_words` であることがあります。

テーブル名がデータセット内に存在する場合は、次のエラーが返されます。

Already Exists: project_id:dataset.table

テーブル スキーマには次の 2 つの列があります。

  • corpus: シェイクスピア全集の名前

  • top_words: word（STRING）と word_count（単語数を表す INT64）の 2 つのフィールドを持つ STRUCT の ARRAY

テーブル オプション リストで指定する内容は次のとおりです。

  • 説明: Top ten words per Shakespeare corpus

テーブルが存在しない場合にのみテーブルを作成する

次の例は、mydataset 内に newtable という名前のテーブルが存在しない場合にのみ、mydataset 内に newtable という名前のテーブルを作成します。テーブル名がデータセットに存在する場合、エラーは返されず、アクションも実行されません。

CREATE TABLE IF NOT EXISTS mydataset.newtable (x INT64, y STRUCT<a ARRAY<STRING>, b BOOL>)
OPTIONS(
  expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC",
  description="a table that expires in 2025",
  labels=[("org_unit", "development")]
)

デフォルト プロジェクトを構成していない場合は、プロジェクト ID をサンプル SQL のデータセット名の前に追加し、project_id に特殊文字 `project_id.dataset.table` が含まれる場合は、バッククォートで名前を囲みます。したがって、mydataset.newtable の代わりに、テーブル修飾子が `myproject.mydataset.newtable` であることがあります。

テーブル スキーマには次の 2 つの列があります。

  • x: 整数

  • y: a（文字列の配列）と b（ブール値）を持つ STRUCT

テーブル オプション リストで指定する内容は次のとおりです。

  • 有効期限: 2025 年 1 月 1 日 00:00:00 UTC
  • 説明: A table that expires in 2025
  • ラベル: org_unit = development

テーブルを作成または置換する

次の例では、mydataset 内に newtable という名前のテーブルを作成し、mydataset 内に newtable が存在している場合は、空のテーブルで上書きされます。

CREATE OR REPLACE TABLE mydataset.newtable (x INT64, y STRUCT<a ARRAY<STRING>, b BOOL>)
OPTIONS(
  expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC",
  description="a table that expires in 2025",
  labels=[("org_unit", "development")]
)

デフォルト プロジェクトを構成していない場合は、プロジェクト ID をサンプル SQL のデータセット名の前に追加し、project_id に特殊文字 `project_id.dataset.table` が含まれる場合は、バッククォートで名前を囲みます。したがって、mydataset.newtable の代わりに、テーブル修飾子が `myproject.mydataset.newtable` であることがあります。

テーブル スキーマには次の 2 つの列があります。

  • x: 整数

  • y: a（文字列の配列）と b（ブール値）を持つ STRUCT

テーブル オプション リストで指定する内容は次のとおりです。

  • 有効期限: 2025 年 1 月 1 日 00:00:00 UTC
  • 説明: A table that expires in 2025
  • ラベル: org_unit = development

REQUIRED 列を持つテーブルを作成する

次の例では、mydataset に newtable という名前のテーブルが作成されます。CREATE TABLE ステートメントの列定義リスト内の NOT NULL 修飾子は、列またはフィールドが REQUIRED モードで作成されることを指定します。

CREATE TABLE mydataset.newtable (
  x INT64 NOT NULL,
  y STRUCT<
    a ARRAY<STRING>,
    b BOOL NOT NULL,
    c FLOAT64
  > NOT NULL,
  z STRING
)

デフォルト プロジェクトを構成していない場合は、プロジェクト ID をサンプル SQL のデータセット名の前に追加し、project_id に特殊文字 `project_id.dataset.table` が含まれる場合は、バッククォートで名前を囲みます。したがって、mydataset.newtable の代わりに、テーブル修飾子が `myproject.mydataset.newtable` であることがあります。

テーブル名がデータセット内に存在する場合は、次のエラーが返されます。

Already Exists: project_id:dataset.table

テーブル スキーマには次の 3 つの列があります。

  • x: REQUIRED の整数
  • y: a（文字列の配列）、b（REQUIRED のブール値）、c（NULLABLE の float）を持つ REQUIRED の STRUCT

  • z: NULLABLE の文字列

照合サポートを持つテーブルの作成

次の例では、列 a、b、c を持つ mydataset という名前の newtable テーブルと、フィールド x および y を持つ構造体を作成します。

このテーブル内のすべての STRING 列スキーマは、'und:ci' と照合されます。

CREATE TABLE mydataset.newtable (
  a STRING,
  b STRING,
  c STRUCT<
    x FLOAT64
    y ARRAY<STRING>
  >
)
DEFAULT COLLATE 'und:ci';

b と y のみが 'und:ci' と照合されます。

CREATE TABLE mydataset.newtable (
  a STRING,
  b STRING COLLATE 'und:ci',
  c STRUCT<
    x FLOAT64
    y ARRAY<STRING COLLATE 'und:ci'>
  >
);

パラメータ化されたデータ型を持つテーブルの作成

次の例では、mydataset に newtable という名前のテーブルが作成されます。かっこ内のパラメータは、列にパラメータ化されたデータ型が含まれていることを指定します。パラメータ化されたデータ型の概要については、パラメータ化されたデータ型をご覧ください。

CREATE TABLE mydataset.newtable (
  x STRING(10),
  y STRUCT<
    a ARRAY<BYTES(5)>,
    b NUMERIC(15, 2),
    c FLOAT64
  >,
  z BIGNUMERIC(35)
)

デフォルト プロジェクトを構成していない場合は、プロジェクト ID をサンプル SQL のデータセット名の前に追加し、project_id に特殊文字 `project_id.dataset.table` が含まれる場合は、バッククォートで名前を囲みます。mydataset.newtable の代わりに、テーブル修飾子が `myproject.mydataset.newtable` である必要があります。

テーブル名がデータセット内に存在する場合は、次のエラーが返されます。

Already Exists: project_id:dataset.table

テーブル スキーマには次の 3 つの列があります。

  • x: 最大長が 10 のパラメータ化された文字列
  • y: a（最大長が 5 のパラメータ化されたバイトの配列）、b（最大精度 15、最大スケール 2 のパラメータ化された NUMERIC）、c （浮動小数点数）を含む STRUCT
  • z: 最大精度 35、最大スケール 0 のパラメータ化された BIGNUMERIC

分割テーブルの作成

次の例では、DATE 列を使用した newtable という名前のパーティション分割テーブルを mydataset 内に作成します。

CREATE TABLE mydataset.newtable (transaction_id INT64, transaction_date DATE)
PARTITION BY transaction_date
OPTIONS(
  partition_expiration_days=3,
  description="a table partitioned by transaction_date"
)

デフォルト プロジェクトを構成していない場合は、プロジェクト ID をサンプル SQL のデータセット名の前に追加し、project_id に特殊文字 `project_id.dataset.table` が含まれる場合は、バッククォートで名前を囲みます。したがって、mydataset.newtable の代わりに、テーブル修飾子が `myproject.mydataset.newtable` であることがあります。

テーブル スキーマには次の 2 つの列があります。

  • transaction_id: 整数
  • transaction_date: 日付

テーブル オプション リストで指定する内容は次のとおりです。

  • パーティションの有効期限: 3 日
  • 説明: A table partitioned by transaction_date

クエリ結果からパーティション分割テーブルを作成する

次の例では、DATE 列を使用した days_with_rain という名前のパーティション分割テーブルを mydataset 内に作成します。

CREATE TABLE mydataset.days_with_rain
PARTITION BY date
OPTIONS (
  partition_expiration_days=365,
  description="weather stations with precipitation, partitioned by day"
) AS
SELECT
  DATE(CAST(year AS INT64), CAST(mo AS INT64), CAST(da AS INT64)) AS date,
  (SELECT ANY_VALUE(name) FROM `bigquery-public-data.noaa_gsod.stations` AS stations
   WHERE stations.usaf = stn) AS station_name,  -- Stations can have multiple names
  prcp
FROM `bigquery-public-data.noaa_gsod.gsod2017` AS weather
WHERE prcp != 99.9  -- Filter unknown values
  AND prcp > 0      -- Filter stations/days with no precipitation

デフォルト プロジェクトを構成していない場合は、プロジェクト ID をサンプル SQL のデータセット名の前に追加し、project_id に特殊文字 `project_id.dataset.table` が含まれる場合は、バッククォートで名前を囲みます。したがって、mydataset.days_with_rain の代わりに、テーブル修飾子が `myproject.mydataset.days_with_rain` であることがあります。

テーブル スキーマには次の 2 つの列があります。

  • date: データ収集日（DATE）
  • station_name: 気象観測所の名前（STRING）
  • prcp: インチ単位の降水量（FLOAT64）

テーブル オプション リストで指定する内容は次のとおりです。

  • パーティションの有効期限: 1 年間
  • 説明: Weather stations with precipitation, partitioned by day

クラスタ化テーブルを作成する

例 1

次の例では、myclusteredtable という名前のクラスタ化テーブルを mydataset 内に作成します。このテーブルは TIMESTAMP 列によって分割されたパーティション分割テーブルであり、customer_id という名前の STRING 列によってクラスタ化されています。

CREATE TABLE mydataset.myclusteredtable
(
  timestamp TIMESTAMP,
  customer_id STRING,
  transaction_amount NUMERIC
)
PARTITION BY DATE(timestamp)
CLUSTER BY customer_id
OPTIONS (
  partition_expiration_days=3,
  description="a table clustered by customer_id"
)

デフォルト プロジェクトを構成していない場合は、プロジェクト ID をサンプル SQL のデータセット名の前に追加し、project_id に特殊文字 `project_id.dataset.table` が含まれる場合は、バッククォートで名前を囲みます。したがって、mydataset.myclusteredtable の代わりに、テーブル修飾子が `myproject.mydataset.myclusteredtable` であることがあります。

テーブル スキーマには次の 3 つの列があります。

  • timestamp: データ収集日（TIMESTAMP）
  • customer_id: お客様 ID（STRING）
  • transaction_amount: 取引金額（NUMERIC）

テーブル オプション リストで指定する内容は次のとおりです。

  • パーティションの有効期限: 3 日
  • 説明: A table clustered by customer_id
例 2

次の例では、myclusteredtable という名前のクラスタ化テーブルを mydataset 内に作成します。テーブルは、取り込み時間パーティション分割テーブルです。

CREATE TABLE mydataset.myclusteredtable
(
  customer_id STRING,
  transaction_amount NUMERIC
)
PARTITION BY DATE(_PARTITIONTIME)
CLUSTER BY
  customer_id
OPTIONS (
  partition_expiration_days=3,
  description="a table clustered by customer_id"
)

デフォルト プロジェクトを構成していない場合は、プロジェクト ID をサンプル SQL のデータセット名の前に追加し、project_id に特殊文字 `project_id.dataset.table` が含まれる場合は、バッククォートで名前を囲みます。したがって、mydataset.myclusteredtable の代わりに、テーブル修飾子が `myproject.mydataset.myclusteredtable` であることがあります。

テーブル スキーマには次の 2 つの列があります。

  • customer_id: お客様 ID（STRING）
  • transaction_amount: 取引金額（NUMERIC）

テーブル オプション リストで指定する内容は次のとおりです。

  • パーティションの有効期限: 3 日
  • 説明: A table clustered by customer_id
例 3

次の例では、myclusteredtable という名前のクラスタ化テーブルを mydataset 内に作成します。このテーブルは分割されていません。

CREATE TABLE mydataset.myclusteredtable
(
  customer_id STRING,
  transaction_amount NUMERIC
)
CLUSTER BY
  customer_id
OPTIONS (
  description="a table clustered by customer_id"
)

デフォルト プロジェクトを構成していない場合は、プロジェクト ID をサンプル SQL のデータセット名の前に追加し、project_id に特殊文字 `project_id.dataset.table` が含まれる場合は、バッククォートで名前を囲みます。したがって、mydataset.myclusteredtable の代わりに、テーブル修飾子が `myproject.mydataset.myclusteredtable` であることがあります。

テーブル スキーマには次の 2 つの列があります。

  • customer_id: お客様 ID（STRING）
  • transaction_amount: 取引金額（NUMERIC）

テーブル オプション リストで指定する内容は次のとおりです。

  • 説明: A table clustered by customer_id

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

例 1

次の例では、クエリの結果を使用して myclusteredtable という名前のクラスタ化テーブルを mydataset 内に作成します。テーブルは、TIMESTAMP 列で分割されたパーティション分割テーブルです。

CREATE TABLE mydataset.myclusteredtable
(
  timestamp TIMESTAMP,
  customer_id STRING,
  transaction_amount NUMERIC
)
PARTITION BY DATE(timestamp)
CLUSTER BY
  customer_id
OPTIONS (
  partition_expiration_days=3,
  description="a table clustered by customer_id"
)
AS SELECT * FROM mydataset.myothertable

デフォルト プロジェクトを構成していない場合は、プロジェクト ID をサンプル SQL のデータセット名の前に追加し、project_id に特殊文字 `project_id.dataset.table` が含まれる場合は、バッククォートで名前を囲みます。したがって、mydataset.myclusteredtable の代わりに、テーブル修飾子が `myproject.mydataset.myclusteredtable` であることがあります。

テーブル スキーマには次の 3 つの列があります。

  • timestamp: データ収集日（TIMESTAMP）
  • customer_id: お客様 ID（STRING）
  • transaction_amount: 取引金額（NUMERIC）

テーブル オプション リストで指定する内容は次のとおりです。

  • パーティションの有効期限: 3 日
  • 説明: A table clustered by customer_id
例 2

次の例では、クエリの結果を使用して myclusteredtable という名前のクラスタ化テーブルを mydataset 内に作成します。このテーブルは分割されていません。

CREATE TABLE mydataset.myclusteredtable
(
  customer_id STRING,
  transaction_amount NUMERIC
)
CLUSTER BY
  customer_id
OPTIONS (
  description="a table clustered by customer_id"
)
AS SELECT * FROM mydataset.myothertable

デフォルト プロジェクトを構成していない場合は、プロジェクト ID をサンプル SQL のデータセット名の前に追加し、project_id に特殊文字 `project_id.dataset.table` が含まれる場合は、バッククォートで名前を囲みます。したがって、mydataset.myclusteredtable の代わりに、テーブル修飾子が `myproject.mydataset.myclusteredtable` であることがあります。

テーブル スキーマには次の 2 つの列があります。

  • customer_id: お客様 ID（STRING）
  • transaction_amount: 取引金額（NUMERIC）

テーブル オプション リストで指定する内容は次のとおりです。

  • 説明: A table clustered by customer_id

一時テーブルの作成

次の例では、Example という名前の一時テーブルを作成し、値を挿入します。

CREATE TEMP TABLE Example
(
  x INT64,
  y STRING
);

INSERT INTO Example
VALUES (5, 'foo');

INSERT INTO Example
VALUES (6, 'bar');

SELECT *
FROM Example;

このスクリプトは、次の出力を返します。

+-----+---+-----+
| Row | x | y   |
+-----+---|-----+
| 1   | 5 | foo |
| 2   | 6 | bar |
+-----+---|-----+

CREATE TABLE LIKE ステートメント

別のテーブルの同じメタデータをすべて含む新しいテーブルを作成します。

構文

CREATE [ OR REPLACE ] TABLE [ IF NOT EXISTS ]
table_name
LIKE [[project_name.]dataset_name.]source_table_name
...
[OPTIONS(table_option_list)]

詳細

列リストの代わりに LIKE 句を使用する点を除き、構文は CREATE TABLE 構文と同じです。

CREATE TABLE LIKE ステートメントは、ソーステーブルのメタデータのみをコピーします。as query_statement 句を使用することで、新しいテーブルにデータを追加できます。

作成後の新しいテーブルはソーステーブルと関係ありません。ソーステーブルの変更は新しいテーブルに反映されません。

デフォルトでは、新しいテーブルはパーティショニング、クラスタリング、オプションのメタデータをソーステーブルから継承します。新しいテーブルのメタデータは、SQL ステートメントのオプションの句を使用してカスタマイズできます。たとえば、新しいテーブルに一連の別のオプションを指定する場合は、オプションと値のリストを指定した OPTIONS 句を含めます。この動作は ALTER TABLE SET OPTIONS の動作と同じです。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.tables.create テーブルを作成するデータセット。
bigquery.tables.get ソーステーブル。

さらに、OR REPLACE 句には bigquery.tables.update 権限と bigquery.tables.updateData 権限が割り当てられている必要があります。

OPTIONS 句に有効期限オプションが含まれている場合は、bigquery.tables.delete 権限も必要です。

Examples

例 1

次の例では、sourcetable と同じメタデータを含む新しいテーブルを newtable という名前で mydataset に作成します。

CREATE TABLE mydataset.newtable
LIKE mydataset.sourcetable

例 2

次の例では、sourcetable と同じメタデータと SELECT ステートメントのデータを含む新しいテーブルを newtable という名前で mydataset に作成します。

CREATE TABLE mydataset.newtable
LIKE mydataset.sourcetable
AS SELECT * FROM mydataset.myothertable

CREATE TABLE COPY ステートメント

別のテーブルと同じメタデータとデータを持つテーブルを作成します。ソーステーブルは、テーブル、テーブル クローン、またはテーブル スナップショットのいずれかです。

構文

CREATE [ OR REPLACE ] TABLE [ IF NOT EXISTS ] table_name
COPY source_table_name
...
[OPTIONS(table_option_list)]

詳細

列リストの代わりに COPY 句を使用する点を除き、構文は CREATE TABLE 構文と同じです。

CREATE TABLE COPY ステートメントは、ソーステーブルからメタデータとデータをコピーします。

新しいテーブルは、ソーステーブルからパーティショニングとクラスタリングを継承します。デフォルトでは、ソーステーブルからテーブル オプションのメタデータも継承されますが、OPTIONS 句を使用すると、テーブル オプションをオーバーライドできます。この動作は、テーブルをコピーした後に ALTER TABLE SET OPTIONS を実行する場合と同じです。

新しいテーブルは、ソーステーブルとは無関係のテーブルです。ソーステーブルの変更は新しいテーブルには反映されません。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.tables.create テーブル スナップショットを作成するデータセット。
bigquery.tables.get ソーステーブル。
bigquery.tables.getData ソーステーブル。

さらに、OR REPLACE 句には bigquery.tables.update 権限と bigquery.tables.updateData 権限が割り当てられている必要があります。

OPTIONS 句に有効期限オプションが含まれている場合は、bigquery.tables.delete 権限も必要です。

CREATE SNAPSHOT TABLE ステートメント

テーブル スナップショットをソーステーブルに基づいて作成します。ソーステーブルは、テーブル、テーブル クローン、またはテーブル スナップショットのいずれかです。

構文

CREATE SNAPSHOT TABLE [ IF NOT EXISTS ] table_snapshot_name
CLONE source_table_name
[FOR SYSTEM_TIME AS OF time_expression]
[OPTIONS(snapshot_option_list)]

引数

  • IF NOT EXISTS: テーブル スナップショットまたは他のテーブル リソースが同じ名前で存在する場合、CREATE ステートメントは無効になります。

  • table_snapshot_name: 作成するテーブル スナップショットの名前。テーブル スナップショット名はデータセット内で一意にする必要があります。テーブルパスの構文をご覧ください。

  • source_table_name: スナップショットを作成するテーブルの名前、またはコピーするテーブル スナップショットの名前。テーブルパスの構文をご覧ください。

    ソーステーブルが標準テーブルの場合、BigQuery はソーステーブルのテーブル スナップショットを作成します。ソーステーブルがテーブル スナップショットの場合、BigQuery はテーブル スナップショットのコピーを作成します。

  • FOR SYSTEM_TIME AS OF: timestamp_expression で指定された時点で最新だったテーブルのバージョンを選択できます。これはテーブル スナップショットを作成する場合にのみ使用できます。テーブル スナップショットのコピーを作成する場合は使用できません。

  • snapshot_option_list: ラベルや有効期限などの追加のテーブル スナップショット作成オプション。

詳細

CREATE SNAPSHOT TABLE ステートメントは、以下の規則に従う必要があります。

  • 使用できる CREATE ステートメントは 1 つのみです。
  • ソーステーブルは次のいずれかである必要があります。
    • テーブル
    • テーブル クローン
    • テーブル スナップショット
  • FOR SYSTEM_TIME AS OF 句は、テーブル スナップショットまたはテーブル クローンを作成する場合にのみ使用できます。テーブル スナップショットのコピーを作成する場合は使用できません。

snapshot_option_list

オプション リストを使用すると、ラベルや有効期限など、テーブル スナップショットのオプションを設定できます。カンマ区切りのリストを使用して複数のオプションを含めることができます。

テーブル スナップショットのオプション リストは次の形式で指定します。

NAME=VALUE, ...

NAME と VALUE は、次のいずれかの組み合わせである必要があります。

NAME VALUE 詳細
expiration_timestamp TIMESTAMP

例: expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

このプロパティは、expirationTime テーブル リソース プロパティと同等です。
friendly_name

STRING

例: friendly_name="my_table_snapshot"

このプロパティは、friendlyName テーブル リソース プロパティと同等です。
description

STRING

例: description="A table snapshot that expires in 2025"

このプロパティは、description テーブル リソース プロパティと同等です。
labels

ARRAY<STRUCT<STRING, STRING>>

例: labels=[("org_unit", "development")]

このプロパティは、labels テーブル リソース プロパティと同等です。

VALUE は、リテラル、クエリ パラメータ、スカラー関数のみを含む定数式です。

定数式には以下を含めることはできません。

  • テーブルへの参照
  • サブクエリ、または SELECT、CREATE、UPDATE などの SQL ステートメント
  • ユーザー定義関数、集計関数、または分析関数
  • 以下のスカラー関数
    • ARRAY_TO_STRING
    • REPLACE
    • REGEXP_REPLACE
    • RAND
    • FORMAT
    • LPAD
    • RPAD
    • REPEAT
    • SESSION_USER
    • GENERATE_ARRAY
    • GENERATE_DATE_ARRAY

VALUE が NULL と評価された場合、CREATE SNAPSHOT TABLE ステートメント内の対応する NAME オプションは無視されます。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.tables.create テーブル スナップショットを作成するデータセット。
bigquery.tables.createSnapshot ソーステーブル。
bigquery.tables.get ソーステーブル。
bigquery.tables.getData ソーステーブル。

Examples

テーブルのスナップショットの作成: すでに存在する場合は失敗する

次の例では、テーブル myproject.mydataset.mytable のテーブル スナップショットを作成します。テーブル スナップショットは、データセット mydataset に mytablesnapshot という名前で作成されます。

CREATE SNAPSHOT TABLE `myproject.mydataset.mytablesnapshot`
CLONE `myproject.mydataset.mytable`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="my_table_snapshot",
  description="A table snapshot that expires in 2 days",
  labels=[("org_unit", "development")]
)

データセットにテーブル スナップショット名が存在する場合、次のエラーが返されます。

Already Exists: myproject.mydataset.mytablesnapshot

テーブル スナップショットのオプション リストで指定する内容は次のとおりです。

  • 有効期限: テーブル スナップショットが作成された時点から 48 時間
  • わかりやすい名前: my_table_snapshot
  • 説明: A table snapshot that expires in 2 days
  • ラベル: org_unit = development

テーブルのスナップショットの作成: すでに存在する場合は無視

次の例では、テーブル myproject.mydataset.mytable のテーブル スナップショットを作成します。テーブル スナップショットは、データセット mydataset に mytablesnapshot という名前で作成されます。

CREATE SNAPSHOT TABLE IF NOT EXISTS `myproject.mydataset.mytablesnapshot`
CLONE `myproject.mydataset.mytable`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="my_table_snapshot",
  description="A table snapshot that expires in 2 days"
  labels=[("org_unit", "development")]
)

テーブル スナップショットのオプション リストで指定する内容は次のとおりです。

  • 有効期限: テーブル スナップショットが作成された時点から 48 時間
  • わかりやすい名前: my_table_snapshot
  • 説明: A table snapshot that expires in 2 days
  • ラベル: org_unit = development

データセットにテーブル スナップショット名が存在する場合、アクションは実行されず、エラーも返されません。

テーブル スナップショットの復元については、CREATE TABLE CLONE をご覧ください。

テーブル スナップショットの削除については、DROP SNAPSHOT TABLE をご覧ください。

CREATE TABLE CLONE ステートメント

テーブル クローンをソーステーブルに基づいて作成します。ソーステーブルは、テーブル、テーブル クローン、またはテーブル スナップショットのいずれかです。

構文

CREATE [ OR REPLACE ] TABLE [ IF NOT EXISTS ]
destination_table_name
CLONE source_table_name [FOR SYSTEM_TIME AS OF time_expression]
...
[OPTIONS(table_option_list)]

詳細

列リストの代わりに CLONE 句を使用する点を除き、構文は CREATE TABLE 構文と同じです。

引数

  • OR REPLACE: 同じ名前のテーブルが存在する場合は、置き換えます。IF NOT EXISTS と一緒には使用できません。

  • IF NOT EXISTS: 指定した宛先テーブル名がすでに存在する場合、CREATE ステートメントは無効になります。OR REPLACE と一緒には使用できません。

destination_table_name は、作成するテーブルの名前です。テーブル名はデータセット内で一意である必要があります。テーブル名には次のものを含めることができます。

  • 1,024 文字まで
  • 英字（大文字または小文字）、数字、アンダースコア

OPTIONS(table_option_list) を使用すると、ラベルや有効期限などのテーブル作成の追加オプションを指定できます。

source_table_name はソーステーブルの名前です。

CREATE TABLE CLONE ステートメントは、以下の規則に従う必要があります。

  • 使用できる CREATE ステートメントは 1 つのみです。
  • クローンを作成するテーブルは、テーブル、テーブル クローン、テーブル スナップショットのいずれかであることが必要です。

OPTIONS

CREATE TABLE CLONE オプションは CREATE TABLE オプションと同じです。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.tables.create テーブル クローンを作成するデータセット。
bigquery.tables.get ソーステーブル。
bigquery.tables.getData ソーステーブル。
bigquery.tables.restoreSnapshot ソーステーブル（ソーステーブルがテーブル スナップショットの場合にのみ必要）。

さらに、OR REPLACE 句には bigquery.tables.update 権限と bigquery.tables.updateData 権限が割り当てられている必要があります。

OPTIONS 句に有効期限オプションが含まれている場合は、bigquery.tables.delete 権限も必要です。

Examples

テーブル スナップショットの復元: 宛先テーブルが存在する場合は失敗する

次の例では、テーブル スナップショット myproject.mydataset.mytablesnapshot からテーブル myproject.mydataset.mytable を作成します。

CREATE TABLE `myproject.mydataset.mytable`
CLONE `myproject.mydataset.mytablesnapshot`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 365 DAY),
  friendly_name="my_table",
  description="A table that expires in 1 year",
  labels=[("org_unit", "development")]
)

テーブル名がデータセット内に存在する場合は、次のエラーが返されます。

Already Exists: myproject.mydataset.mytable.

テーブル オプション リストで指定する内容は次のとおりです。

  • 有効期限: テーブルの作成時点から 365 日
  • わかりやすい名前: my_table
  • 説明: A table that expires in 1 year
  • ラベル: org_unit = development

テーブルのクローンの作成: 宛先テーブルがすでに存在する場合は無視されます。

次の例では、テーブル myproject.mydataset.mytable に基づいてテーブル クローン myproject.mydataset.mytableclone を作成します。

CREATE TABLE IF NOT EXISTS `myproject.mydataset.mytableclone`
CLONE `myproject.mydataset.mytable`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 365 DAY),
  friendly_name="my_table",
  description="A table that expires in 1 year",
  labels=[("org_unit", "development")]
)

テーブル オプション リストで指定する内容は次のとおりです。

  • 有効期限: テーブルの作成時点から 365 日
  • わかりやすい名前: my_table
  • 説明: A table that expires in 1 year
  • ラベル: org_unit = development

テーブル名がデータセットに存在する場合、アクションは実行されず、エラーも返されません。

テーブルのコピーの作成については、CREATE TABLE COPY をご覧ください。

テーブルのスナップショットの作成については、CREATE SNAPSHOT TABLE をご覧ください。

CREATE VIEW ステートメント

新しいビューを作成します。

構文

CREATE [ OR REPLACE ] VIEW [ IF NOT EXISTS ] view_name
[(view_column_name_list)]
[OPTIONS(view_option_list)]
AS query_expression

引数

  • OR REPLACE: 同じ名前のビューが存在する場合は、置き換えます。IF NOT EXISTS と一緒には使用できません。

  • IF NOT EXISTS: ビューまたは他のテーブル リソースが同じ名前で存在する場合、CREATE ステートメントは無効になります。OR REPLACE と一緒には使用できません。

  • view_name: 作成するビューの名前。テーブルパスの構文をご覧ください。

  • view_column_name_list: ビューの列名を明示的に指定できます。これは、参照元の SQL クエリで列名のエイリアスにできます。

  • view_option_list: ラベルや有効期限などの追加のビュー作成オプション。

  • query_expression: ビューの定義に使用される標準 SQL クエリ式。

詳細

CREATE VIEW ステートメントは、以下の規則に従う必要があります。

  • 使用できる CREATE ステートメントは 1 つのみです。

view_column_name_list

このビューの列名リストは省略可能です。名前は一意にする必要がありますが、参照元の SQL クエリの列名と同じである必要はありません。たとえば、次のステートメントでビューを作成した場合。

CREATE VIEW mydataset.age_groups(age, count) AS SELECT age, COUNT(*)
FROM mydataset.people
group by age;

これで、以下を使用してクエリを実行できます。

SELECT age, count from mydataset.age_groups;

列名リスト内の列の数は、参照元の SQL クエリの列の数と一致する必要があります。参照元の SQL クエリのテーブルに列の追加や削除を行うと、そのビューは無効になり、再作成する必要があります。たとえば、age 列が mydataset.people テーブルから削除されると、上記の例で作成したビューは無効になります。

view_option_list

オプション リストを使用すると、ラベルや有効期限などのビュー オプションを設定できます。カンマ区切りのリストを使用して複数のオプションを含めることができます。

ビュー オプション リストは次の形式で指定します。

NAME=VALUE, ...

NAME と VALUE は、次のいずれかの組み合わせである必要があります。

NAME VALUE 詳細
expiration_timestamp TIMESTAMP

例: expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

このプロパティは、expirationTime テーブル リソース プロパティと同等です。
friendly_name

STRING

例: friendly_name="my_view"

このプロパティは、friendlyName テーブル リソース プロパティと同等です。
description

STRING

例: description="a view that expires in 2025"

このプロパティは、description テーブル リソース プロパティと同等です。
labels

ARRAY<STRUCT<STRING, STRING>>

例: labels=[("org_unit", "development")]

このプロパティは、labels テーブル リソース プロパティと同等です。

VALUE は、リテラル、クエリ パラメータ、スカラー関数のみを含む定数式です。

定数式には以下を含めることはできません。

  • テーブルへの参照
  • サブクエリ、または SELECT、CREATE、UPDATE などの SQL ステートメント。
  • ユーザー定義関数、集計関数、または分析関数
  • 以下のスカラー関数
    • ARRAY_TO_STRING
    • REPLACE
    • REGEXP_REPLACE
    • RAND
    • FORMAT
    • LPAD
    • RPAD
    • REPEAT
    • SESSION_USER
    • GENERATE_ARRAY
    • GENERATE_DATE_ARRAY

VALUE が NULL と評価された場合、CREATE VIEW ステートメント内の対応する NAME オプションは無視されます。

ビュー本文のデフォルト プロジェクト

ビューが CREATE VIEW ステートメントの実行に使用されたのと同じプロジェクトで作成された場合、ビューの本文 query_expression はプロジェクトを指定せずにエンティティを参照できます。デフォルト プロジェクトは、ビューを所有するプロジェクトです。以下のサンプルクエリを検討してください。

CREATE VIEW myProject.myDataset.myView AS SELECT * FROM anotherDataset.myTable;

プロジェクト myProject で上記の CREATE VIEW クエリを実行した後、クエリ SELECT * FROM myProject.myDataset.myView を実行できます。この SELECT クエリを実行するプロジェクトとしてどのプロジェクトを選択しても、参照されるテーブル anotherDataset.myTable は常にプロジェクト myProject に対して解決されます。

ビューが CREATE VIEW ステートメントの実行に使用したプロジェクトで作成されていない場合、ビューの本文 query_expression 内のすべての参照はプロジェクト ID で修飾する必要があります。たとえば、上記のサンプル CREATE VIEW クエリは、myProject と異なるプロジェクトで実行される場合は無効になります。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.tables.create ビューを作成するデータセット。

さらに、OR REPLACE 句には bigquery.tables.update 権限が必要です。

OPTIONS 句に有効期限が含まれている場合は、bigquery.tables.delete 権限も必要です。

Examples

新しいビューの作成

次の例では、mydataset に newview という名前のビューが作成されます。

CREATE VIEW `myproject.mydataset.newview`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="newview",
  description="a view that expires in 2 days",
  labels=[("org_unit", "development")]
)
AS SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

ビュー名がデータセット内に存在する場合、次のエラーが返されます。

Already Exists: project_id:dataset.table

ビューは、次の標準 SQL クエリを使用して定義されます。

SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

ビュー オプション リストで指定する内容は次のとおりです。

  • 有効期限: ビューが作成されてから 48 時間
  • わかりやすい名前: newview
  • 説明: A view that expires in 2 days
  • ラベル: org_unit = development

ビューが存在しない場合にのみビューを作成する

次の例は、mydataset 内に newview という名前のビューが存在しない場合にのみ、mydataset 内に newview という名前のビューを作成します。ビュー名がデータセットに存在する場合、エラーは返されず、アクションも実行されません。

CREATE VIEW IF NOT EXISTS `myproject.mydataset.newview`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="newview",
  description="a view that expires in 2 days",
  labels=[("org_unit", "development")]
)
AS SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

ビューは、次の標準 SQL クエリを使用して定義されます。

SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

ビュー オプション リストで指定する内容は次のとおりです。

  • 有効期限: ビューが作成されてから 48 時間
  • わかりやすい名前: newview
  • 説明: A view that expires in 2 days
  • ラベル: org_unit = development

ビューを作成または置換する

次の例では、mydataset 内に newview という名前のビューを作成し、mydataset 内に newview が存在している場合は、指定されたクエリ式を使用して上書きされます。

CREATE OR REPLACE VIEW `myproject.mydataset.newview`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="newview",
  description="a view that expires in 2 days",
  labels=[("org_unit", "development")]
)
AS SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

ビューは、次の標準 SQL クエリを使用して定義されます。

SELECT column_1, column_2, column_3 FROM myproject.mydataset.mytable

ビュー オプション リストで指定する内容は次のとおりです。

  • 有効期限: ビューが作成されてから 48 時間
  • わかりやすい名前: newview
  • 説明: A view that expires in 2 days
  • ラベル: org_unit = development

CREATE MATERIALIZED VIEW ステートメント

マテリアライズド ビューを作成します。

構文

CREATE [ OR REPLACE ] MATERIALIZED VIEW [ IF NOT EXISTS ] materialized_view_name
[PARTITION BY partition_expression]
[CLUSTER BY clustering_column_list]
[OPTIONS(materialized_view_option_list)]
AS query_expression

引数

  • OR REPLACE: 同じ名前のマテリアライズド ビューが存在する場合は、そのビューを置き換えます。IF NOT EXISTS と一緒には使用できません。

  • IF NOT EXISTS: マテリアライズド ビューまたは他のテーブル リソースが同じ名前で存在する場合、CREATE ステートメントは無効になります。OR REPLACE と一緒には使用できません。

  • materialized_view_name: 作成するマテリアライズド ビューの名前。テーブルパスの構文をご覧ください。

    project_name がマテリアライズド ビュー名から省略されているか、この DDL クエリを実行するプロジェクトと同じものである場合、後者は query_expression 内でテーブル、関数、その他のリソースを参照する際のデフォルト プロジェクトとして使用されます。参照のデフォルト プロジェクトは固定されており、新しいマテリアライズド ビューを呼び出す今後のクエリには依存しません。それ以外の場合、query_expression 内のすべての参照はプロジェクト名で修飾する必要があります。

    マテリアライズド ビュー名は、データセット内で一意である必要があります。

  • partition_expression: テーブルのパーティショニング方法を決める式。マテリアライズド ビューは、query expression（ベーステーブル）内のテーブルと同じ方法で分割できます。

  • clustering_column_list: マテリアライズド ビューのクラスタ化の方法を決定する列参照のカンマ区切りリスト。

  • materialized_view_option_list** を使用すると、更新が有効かどうか、更新間隔、ラベル、有効期限などのマテリアライズド ビュー オプションを設定できます。

  • query_expression: マテリアライズド ビューの定義に使用される標準 SQL クエリ式。

詳細

CREATE MATERIALIZED VIEW ステートメントは、以下の規則に従う必要があります。

  • 使用できる CREATE ステートメントは 1 つのみです。

マテリアライズド ビュー本文のデフォルト プロジェクト

実体化されたビューが CREATE MATERIALIZED VIEW ステートメントの実行に使用されたのと同じプロジェクトで作成された場合、実体化されたビューの本文 query_expression はプロジェクトを指定せずにエンティティを参照できます。デフォルト プロジェクトは、実体化されたビューを所有するプロジェクトです。以下のサンプルクエリを検討してください。

CREATE MATERIALIZED VIEW myProject.myDataset.myView AS SELECT * FROM anotherDataset.myTable;

プロジェクト myProject で上記の CREATE MATERIALIZED VIEW クエリを実行した後、クエリ SELECT * FROM myProject.myDataset.myView を実行できます。この SELECT クエリを実行するプロジェクトとしてどのプロジェクトを選択しても、参照されるテーブル anotherDataset.myTable は常にプロジェクト myProject に対して解決されます。

実体化されたビューが CREATE VIEW ステートメントの実行に使用したプロジェクトで作成されていない場合、実体化されたビューの本文 query_expression 内のすべての参照はプロジェクト ID で修飾する必要があります。たとえば、上記のサンプル CREATE MATERIALIZED VIEW クエリは、myProject と異なるプロジェクトで実行される場合は無効になります。

materialized_view_option_list

オプション リストを使用すると、更新が有効かどうか、更新間隔、ラベル、有効期限などのマテリアライズド ビュー オプションを設定できます。カンマ区切りのリストを使用して複数のオプションを含めることができます。

実体化されたビュー オプション リストは次の形式で指定します。

NAME=VALUE, ...

NAME と VALUE は、次のいずれかの組み合わせである必要があります。

NAME VALUE 詳細
enable_refresh BOOLEAN

例: enable_refresh=false

refresh_interval_minutes FLOAT64

例: refresh_interval_minutes=20

expiration_timestamp TIMESTAMP

例: expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

このプロパティは、expirationTime テーブル リソース プロパティと同等です。
friendly_name

STRING

例: friendly_name="my_mv"

このプロパティは、friendlyName テーブル リソース プロパティと同等です。
description

STRING

例: description="a materialized view that expires in 2025"

このプロパティは、description テーブル リソース プロパティと同等です。
labels

ARRAY<STRUCT<STRING, STRING>>

例: labels=[("org_unit", "development")]

このプロパティは、labels テーブル リソース プロパティと同等です。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.tables.create マテリアライズド ビューを作成するデータセット。

さらに、OR REPLACE 句には bigquery.tables.update 権限が必要です。

OPTIONS 句に有効期限オプションが含まれている場合は、bigquery.tables.delete 権限も必要です。

Examples

新しい実体化されたビューの作成

次の例では、mydataset に new_mv という名前の実体化されたビューが作成されます。

CREATE MATERIALIZED VIEW `myproject.mydataset.new_mv`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="new_mv",
  description="a materialized view that expires in 2 days",
  labels=[("org_unit", "development")],
  enable_refresh=true,
  refresh_interval_minutes=20
)
AS SELECT column_1, SUM(column_2) AS sum_2, AVG(column_3) AS avg_3
FROM `myproject.mydataset.mytable`
GROUP BY column_1

実体化されたビュー名がデータセット内に存在する場合、次のエラーが返されます。

Already Exists: project_id:dataset.materialized_view

DDL ステートメントを使用して実体化されたビューを作成する場合は、`project_id.dataset.materialized_view`（project_id に特殊文字が含まれる場合、バッククォートを含む）の形式でプロジェクト、データセット、実体化されたビューを指定する必要があります（例: `myproject.mydataset.new_mv`）。

実体化されたビューの定義には次の標準 SQL クエリを使用します。

SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

実体化されたビュー オプション リストで指定する内容は次のとおりです。

  • 有効期限: マテリアライズド ビューが作成されてから 48 時間
  • わかりやすい名前: new_mv
  • 説明: A materialized view that expires in 2 days
  • ラベル: org_unit = development
  • 更新が有効: true
  • 更新間隔: 20 分

実体化されたビューが存在しない場合にのみ実体化されたビューを作成

次の例は、mydataset 内に new_mv という名前の実体化されたビューが存在しない場合にのみ、mydataset 内に new_mv という名前の実体化されたビューを作成します。実体化されたビュー名がデータセットに存在する場合、エラーは返されず、アクションも実行されません。

CREATE MATERIALIZED VIEW IF NOT EXISTS `myproject.mydataset.new_mv`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="new_mv",
  description="a view that expires in 2 days",
  labels=[("org_unit", "development")],
  enable_refresh=false
)
AS SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

実体化されたビューの定義には次の標準 SQL クエリを使用します。

SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

実体化されたビュー オプション リストで指定する内容は次のとおりです。

  • 有効期限: ビューが作成されてから 48 時間
  • わかりやすい名前: new_mv
  • 説明: A view that expires in 2 days
  • ラベル: org_unit = development
  • 更新が有効: false

マテリアライズド ビューを作成してパーティショニングとクラスタ化を行う

次の例では、mydataset に new_mv という名前のマテリアライズド ビューを作成して、col_datetime 列で分割し、col_int 列でクラスタ化しています。

CREATE MATERIALIZED VIEW `myproject.mydataset.new_mv`
PARTITION BY DATE(col_datetime)
CLUSTER BY col_int
AS SELECT col_int, col_datetime, COUNT(1) as cnt
   FROM `myproject.mydataset.mv_base_table`
   GROUP BY col_int, col_datetime

ベーステーブル mv_base_table も col_datetime 列で分割する必要があります。詳細については、パーティション分割テーブルとクラスタ化テーブルの操作をご覧ください。

CREATE EXTERNAL TABLE ステートメント

新しい外部テーブルを作成します。

外部テーブルを使用すると、BigQuery ストレージの外部で保存されているデータを BigQuery で照会できます。外部テーブルの詳細については、外部データソースの概要をご覧ください。

構文

CREATE [ OR REPLACE ] EXTERNAL TABLE [ IF NOT EXISTS ] table_name
[(
  column_name column_schema,
  ...
)]
[WITH CONNECTION connection_name]
[WITH PARTITION COLUMNS
  [(
      partition_column_name partition_column_type,
      ...
  )]
]
OPTIONS (
  external_table_option_list,
  ...
);

引数

  • OR REPLACE: 同じ名前の外部テーブルが存在する場合は、置き換えます。IF NOT EXISTS と一緒には使用できません。

  • IF NOT EXISTS: 外部テーブルまたは他のテーブル リソースが同じ名前で存在する場合、CREATE ステートメントは無効になります。OR REPLACE と一緒には使用できません。

  • table_name: 外部テーブルの名前。テーブルパスの構文をご覧ください。

  • column_name: テーブルの列の名前。

  • column_schema: 列のスキーマを指定します。これは、CREATE TABLE ステートメントの column_schema 定義と同じ構文を使用します。この句を指定しない場合、BigQuery はスキーマを自動的に検出します。

  • connection_name: 外部データへのアクセス認証情報を含む接続リソースを指定します。接続名を PROJECT_ID.LOCATION.CONNECTION_ID の形式で指定します。プロジェクト ID またはロケーションにダッシュが含まれている場合は、接続名をバッククォート（`）で囲みます。

  • partition_column_name: パーティション列の名前。外部データが Hive パーティション分割レイアウトを使用している場合は、このフィールドを指定します。詳細については、サポートされるデータ レイアウトをご覧ください。

  • partition_column_type: パーティション列のタイプ。

  • external_table_option_list: 外部テーブルを作成するためのオプションのリスト。

詳細

CREATE EXTERNAL TABLE ステートメントは、外部の一時テーブルの作成をサポートしていません。

外部パーティション分割テーブルを作成するには、WITH PARTITION COLUMNS 句を使用して、パーティション スキーマの詳細を指定します。BigQuery は外部データソースに対して列定義を検証します。スキーマの宣言は、外部パスのフィールドの順序に厳密に従わなければなりません。外部パーティショニングの詳細については、外部パーティション分割データのクエリをご覧ください。

external_table_option_list

オプション リストには、外部テーブルを作成するためのオプションを指定します。format オプションと uris オプションは必須です。オプション リストを NAME=VALUE, ... の形式で指定します。

オプション
allow_jagged_rows

BOOL

true の場合、末尾のオプションの列が欠落している行を受け入れます。

CSV データに適用されます。
allow_quoted_newlines

BOOL

true の場合、改行文字を含む引用符で囲まれたデータ セクションを許可します。

CSV データに適用されます。
compression

STRING

データソースの圧縮タイプ。サポートされる値: GZIP。指定しない場合、データソースは圧縮されません。

CSV データと JSON データに適用されます。
description

STRING

このテーブルの説明。
enable_logical_types

BOOL

true の場合、Avro の論理型を対応する SQL 型に変換します。詳細については、論理型をご覧ください。

Avro データに適用されます。
enum_as_string

BOOL

true の場合、Parquet ENUM 論理型はデフォルトで BYTES ではなく STRING として推測されます。

Parquet データに適用されます。
enable_list_inference

BOOL

true の場合は、Parquet LIST 論理型専用のスキーマ推定を使用します。

Parquet データに適用されます。
encoding

STRING

データの文字エンコード。サポートされている値: UTF8（または UTF-8）、ISO_8859_1（または ISO-8859-1）。

CSV データに適用されます。
expiration_timestamp

TIMESTAMP

このテーブルの有効期限。指定しない場合、テーブルは期限切れになりません。

例: "2025-01-01 00:00:00 UTC"。
field_delimiter

STRING

CSV ファイル内のフィールド区切り文字。

CSV データに適用されます。
format

STRING

外部データの形式。 CREATE EXTERNAL TABLE に指定できる値は、AVRO、CSV、DATASTORE_BACKUP、GOOGLE_SHEETS、NEWLINE_DELIMITED_JSON（または JSON）、ORC、PARQUET です。

LOAD DATA に指定できる値は、AVRO、CSV、NEWLINE_DELIMITED_JSON（または JSON）、ORC、PARQUET です。

値 JSON は NEWLINE_DELIMITED_JSON と同等です。
decimal_target_types

ARRAY<STRING>

Decimal 型の変換方法を指定します。ExternalDataConfiguration.decimal_target_types と同等です。

例: ["NUMERIC", "BIGNUMERIC"]。
json_extension

STRING

JSON データの場合、特定の JSON 置換形式を指定します。指定しない場合、BigQuery はデータを汎用 JSON レコードとして読み取ります。

サポートされる値:
GEOJSON。改行区切りの GeoJSON データ。詳細については、改行区切りの GeoJSON ファイルから外部テーブルを作成するをご覧ください。
hive_partition_uri_prefix

STRING

パーティション キーのエンコードを開始する前のすべてのソース URI の一般的なプレフィックス。Hive パーティション分割された外部テーブルにのみ適用されます。

Avro、CSV、JSON、Parquet、ORC のデータに適用されます。

例: "gs://bucket/path"。
ignore_unknown_values

BOOL

true の場合、テーブル スキーマにない余分な値を無視します。エラーは返しません。

CSV データと JSON データに適用されます。
max_bad_records

INT64

データの読み取り時に無視する不良レコードの最大数。

適用対象: CSV、JSON、スプレッドシートのデータ。
null_marker

STRING

CSV ファイル内の NULL 値を表す文字列。

CSV データに適用されます。
preserve_ascii_control_characters

BOOL

true の場合、埋め込みの ASCII 制御文字（ASCII テーブルの最初の 32 文字「\x00」から「\x1F」まで）が保持されます。

CSV データに適用されます。
projection_fields

STRING

読み込むエンティティ プロパティのリスト。

Datastore データに適用されます。
quote

STRING

CSV ファイルのデータ セクションを引用するために使用される文字列。データに引用符で囲まれた改行文字が含まれている場合は、allow_quoted_newlines プロパティも true に設定します。

CSV データに適用されます。
require_hive_partition_filter

BOOL

true の場合、このテーブルに対するすべてのクエリでパーティション フィルタが必要になります。パーティション フィルタを使用すると、データを読み取るときにパーティションを削除できます。Hive パーティション分割された外部テーブルにのみ適用されます。

Avro、CSV、JSON、Parquet、ORC のデータに適用されます。
sheet_range

STRING

クエリの対象となるスプレッドシートのスプレッドシートの範囲。

スプレッドシートのデータに適用されます。

例: “sheet1!A1:B20”
skip_leading_rows

INT64

データを読み取る際にスキップするファイルの先頭行の数。

CSV データとスプレッドシートのデータに適用されます。
uris

ARRAY<STRING>

外部データのロケーションの完全修飾 URI の配列。

例: ["gs://bucket/path/*"]。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.tables.create 外部テーブルを作成するデータセット。

さらに、OR REPLACE 句には bigquery.tables.update 権限が必要です。

OPTIONS 句に有効期限が含まれている場合は、bigquery.tables.delete 権限も必要です。

Examples

次の例では、複数の URI から外部テーブルを作成します。データ形式は CSV です。この例では、スキーマの自動検出を使用しています。

CREATE EXTERNAL TABLE dataset.CsvTable OPTIONS (
  format = 'CSV',
  uris = ['gs://bucket/path1.csv', 'gs://bucket/path2.csv']
);

次の例では、CSV ファイルから外部テーブルを作成し、スキーマを明示的に指定しています。また、フィールド境界（'|'）を指定し、許可される不良レコードの最大数を設定します。

CREATE OR REPLACE EXTERNAL TABLE dataset.CsvTable
(
  x INT64,
  y STRING
)
OPTIONS (
  format = 'CSV',
  uris = ['gs://bucket/path1.csv'],
  field_delimiter = '|',
  max_bad_records = 5
);

次の例では、外部パーティション分割テーブルを作成します。スキーマの自動検出を使用して、ファイル スキーマと Hive パーティショニング レイアウトの両方を検出します。

たとえば、外部パスが gs://bucket/path/field_1=first/field_2=1/data.csv の場合、パーティション列は field_1（STRING）と field_2（INT64）になります。

CREATE EXTERNAL TABLE dataset.AutoHivePartitionedTable
WITH PARTITION COLUMNS
OPTIONS (
  uris=['gs://bucket/path/*'],
  format=csv,
  hive_partition_uri_prefix='gs://bucket/path'
);

次の例では、パーティション列を明示的に指定することで外部パーティション分割テーブルを作成します。この例は、外部ファイルのパスのパターンが gs://bucket/path/field_1=first/field_2=1/data.csv であることを前提としています。

CREATE EXTERNAL TABLE dataset.CustomHivePartitionedTable
WITH PARTITION COLUMNS (
  field_1 STRING, -- column order must match the external path
  field_2 INT64
)
OPTIONS (
  uris=['gs://bucket/path/*'],
  format=csv,
  hive_partition_uri_prefix='gs://bucket/path'
);

CREATE FUNCTION ステートメント

新しいユーザー定義関数（UDF）を作成します。BigQuery は、SQL または JavaScript で記述された UDF をサポートしています。

構文

SQL UDF を作成するには、次の構文を使用します。

CREATE [ OR REPLACE ] [ TEMPORARY | TEMP ] FUNCTION [ IF NOT EXISTS ]
    [[project_name.]dataset_name.]function_name
    ([named_parameter[, ...]])
     ([named_parameter[, ...]])
  [RETURNS data_type]
  AS (sql_expression)
  [OPTIONS (function_option_list)]

named_parameter:
  param_name param_type

JavaScript UDF を作成するには、次の構文を使用します。

CREATE [OR REPLACE] [TEMPORARY | TEMP] FUNCTION [IF NOT EXISTS]
    [[project_name.]dataset_name.]function_name
    ([named_parameter[, ...]])
  RETURNS data_type
  [determinism_specifier]
  LANGUAGE js
  [OPTIONS (function_option_list)]
  AS javascript_code

named_parameter:
  param_name param_type

determinism_specifier:
  { DETERMINISTIC | NOT DETERMINISTIC }

リモート関数を作成するには、次の構文を使用します。

CREATE [OR REPLACE] FUNCTION [IF NOT EXISTS]
    [[project_name.]dataset_name.]function_name
    ([named_parameter[, ...]])
  RETURNS data_type
  REMOTE WITH CONNECTION connection_path
  [OPTIONS (function_option_list)]

named_parameter:
  param_name param_type

ルーティン名に使用できる文字は、英字、数字、アンダースコアのみで、256 文字以下で指定する必要があります。

引数

  • OR REPLACE: 同じ名前の関数が存在する場合は、置き換えます。IF NOT EXISTS と一緒には使用できません。

  • IF NOT EXISTS: 同じ名前のデータセットが存在する場合、CREATE ステートメントは無効になります。OR REPLACE と一緒には使用できません。

  • TEMP または TEMPORARY: 一時的な関数を作成します。句が存在しない場合、ステートメントで永続的な UDF が作成されます。永続的な UDF は複数のクエリで再利用できるのに対し、一時的な UDF は 1 つのクエリ、スクリプト、またはステップでのみ使用できます。

  • project_name。永続関数の場合、関数を作成するプロジェクトの名前。デフォルトでは、DDL クエリを実行するプロジェクトの名前が設定されます。一時的な関数のプロジェクト名を含めないでください。

  • dataset_name。永続的な関数の場合、関数を作成するデータセットの名前。デフォルトでは、リクエスト内の defaultDataset の名前が設定されます。一時的な関数のデータセット名は含めないでください。

  • function_name。関数名。

  • named_parameter。カンマで区切られた param_name と param_type のペア。param_type の値は BigQuery のデータ型です。SQL UDF の場合は、param_type の値を ANY TYPE にすることもできます。

  • determinism_specifier。JavaScript UDF にのみ適用されます。クエリ結果をキャッシュに保存できるかどうかについてのヒントを BigQuery に提供します。次のいずれかの値です。

    • DETERMINISTIC: 同じ引数を渡すと、常に同じ結果が返されます。クエリ結果はキャッシュに保存できる可能性があります。たとえば、関数 add_one(i) が常に i + 1 を返す場合、この関数は確定的です。

    • NOT DETERMINISTIC: 同じ引数を渡しても、同じ結果が返されるとは限りません。このため、キャッシュに保存できません。たとえば、関数 add_random(i) が i + rand() を返す場合、関数は確定的ではないため、BigQuery はキャッシュに保存された結果を使用しません。

      呼び出された関数がすべて DETERMINISTIC の場合、結果を他の理由でキャッシュに保存できない場合を除き、BigQuery は結果をキャッシュしようとします。詳細については、キャッシュに保存されているクエリ結果を使用するをご覧ください。

  • data_type。関数が返すデータ型。

    • 関数が SQL で定義されている場合、RETURNS 句はオプションです。RETURNS 句を省略した場合、BigQuery は、クエリが関数を呼び出すときに SQL 関数本文から関数の結果の型を推測します。
    • 関数が JavaScript で定義されている場合、RETURNS 句は必須です。data_type で使用できる値の詳細については、サポートされた JavaScript UDF データ型をご覧ください。

  • sql_expression: 関数を定義する SQL 式。

  • function_option_list。関数を作成するためのオプションのリスト。

  • javascript_code: JavaScript 関数の定義。値は文字列リテラルです。コードに引用符とバックスラッシュが含まれている場合は、エスケープするか、元の文字列として表現する必要があります。たとえば、コード return "\n"; は次のいずれかで表されます。

    • 引用符付き文字列: "return \"\\n\";"。引用符とバックスラッシュはどちらもエスケープする必要があります。
    • 三重引用符付き文字列: """return "\\n";"""。バックスラッシュはエスケープする必要がありますが、引用符はエスケープする必要がありません。
    • 元の文字列: r"""return "\n";"""。エスケープは不要です。

  • connection_name: リモート エンドポイントへのアクセス認証情報を含む接続リソースを指定します。接続名を project_name.location.connection_id という形式で指定します。プロジェクト名またはロケーションにダッシュが含まれている場合は、接続名をバッククォート（`）で囲みます。

function_option_list

オプション リストには、UDF を作成するためのオプションを指定します。次のオプションがサポートされています。

NAME VALUE 詳細
description

STRING

 UDF の説明。
library

ARRAY<STRING>

関数定義に含める JavaScript ライブラリの配列。JavaScript UDF にのみ適用されます。詳しくは、JavaScript ライブラリの追加をご覧ください。

例: ["gs://my-bucket/lib1.js", "gs://my-bucket/lib2.js"]
endpoint

STRING

Cloud Functions の HTTP エンドポイント。リモート関数にのみ適用されます。

例: "https://us-east1-your-project.cloudfunctions.net/foo"

詳しくは、リモート関数の作成をご覧ください。
user_defined_context

ARRAY<STRUCT<STRING,STRING>>

関数の呼び出し時にすべての HTTP リクエストとともに送信される Key-Value ペアのリスト。リモート関数にのみ適用されます。

例: [("key1","value1"),("key2", "value2")]
max_batching_rows

INT64

各 HTTP リクエストの最大行数。指定しない場合、BigQuery が HTTP リクエストに含める行数を決定します。リモート関数にのみ適用されます。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.routines.create 関数を作成するデータセット。

さらに、OR REPLACE 句には bigquery.routines.update 権限が必要です。

リモート関数を作成するには、追加の IAM 権限が必要です。

権限 リソース
bigquery.connections.delegate リモート関数の作成に使用する接続。

Examples

SQL UDF を作成する

次の例では、mydataset という名前のデータセットに multiplyInputs という名前の永続 SQL UDF を作成します。

CREATE FUNCTION mydataset.multiplyInputs(x FLOAT64, y FLOAT64)
RETURNS FLOAT64
AS (x * y);

JavaScript UDF を作成する

次の例では、multiplyInputs という名前の一時的な JavaScript UDF を作成し、SELECT ステートメント内から呼び出します。

CREATE TEMP FUNCTION multiplyInputs(x FLOAT64, y FLOAT64)
RETURNS FLOAT64
LANGUAGE js
AS r"""
  return x*y;
""";

SELECT multiplyInputs(a, b) FROM (SELECT 3 as a, 2 as b);

リモート関数を作成する

次の例では、mydataset が US のロケーションにあり、ロケーションとプロジェクトが同じところに、接続 myconnection があると仮定して、mydataset というデータセットに remoteMultiplyInputs という名前の永続的なリモート関数を作成します。

CREATE FUNCTION mydataset.remoteMultiplyInputs(x FLOAT64, y FLOAT64)
RETURNS FLOAT64
REMOTE WITH CONNECTION us.myconnection
OPTIONS(endpoint="https://us-central1-myproject.cloudfunctions.net/multiply");

CREATE TABLE FUNCTION ステートメント

新しいテーブル関数を作成します。これはテーブル値関数（TVF）とも呼ばれます。

構文

CREATE [ OR REPLACE ] TABLE FUNCTION [ IF NOT EXISTS ]
  [[project_name.]dataset_name.]function_name
  ( [ function_parameter [, ...] ] )
  [RETURNS TABLE < column_declaration [, ...] > ]
  AS sql_query

function_parameter:
  parameter_name { data_type | ANY TYPE }

column_declaration:
  column_name data_type

引数

  • OR REPLACE: 同じ名前が存在する場合は、テーブル関数を置き換えます。IF NOT EXISTS と一緒には使用できません。
  • IF NOT EXISTS: 同じ名前のテーブル関数が存在する場合、CREATE ステートメントは無効になります。OR REPLACE と一緒には使用できません。
  • project_name: 関数を作成するプロジェクトの名前。デフォルトでは、この DDL ステートメントを実行するプロジェクトの名前が設定されます。
  • dataset_name: 関数を作成するデータセットの名前。
  • function_name: 作成する関数の名前。
  • function_parameter: 関数のパラメータ。パラメータ名とデータ型として指定します。data_type の値はスカラー BigQuery データ型または ANY TYPE です。
  • RETURNS TABLE: 関数が返すテーブルのスキーマ。列名とデータ型のペアのカンマ区切りのリストとして指定します。RETURNS TABLE が存在しない場合、BigQuery は関数本文のクエリ ステートメントから出力スキーマを推測します。RETURNS TABLE が含まれている場合、返されるテーブルタイプの名前は、SQL クエリの列名と一致する必要があります。
  • sql_query: 実行する SQL クエリを指定します。SQL クエリには、すべての列の名前を含める必要があります。

詳細

可能であれば BigQuery は引数の型を強制的に変換します。たとえば、FLOAT64 型のパラメータに INT64 値を渡すと、BigQuery は値を FLOAT64 に強制変換します。

パラメータの型が ANY TYPE の場合、この関数は引数の入力として任意の型を受け入れます。関数には、関数定義と互換性のある型の値を渡す必要があります。互換性のない型の引数を渡すと、クエリはエラーを返します。BigQuery では、ANY TYPE 型のパラメータが複数ある場合、これらのパラメータ間に型の関係は適用されません。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.routines.create テーブル関数を作成するデータセット。

さらに、OR REPLACE 句には bigquery.routines.update 権限が必要です。

Examples

次のテーブル関数は、クエリ結果のフィルタに使用する INT64 パラメータを受け取ります。

CREATE OR REPLACE TABLE FUNCTION mydataset.names_by_year(y INT64)
AS
  SELECT year, name, SUM(number) AS total
  FROM `bigquery-public-data.usa_names.usa_1910_current`
  WHERE year = y
  GROUP BY year, name

次の例では、RETURNS 句で戻り値の TABLE 型を指定します。

CREATE OR REPLACE TABLE FUNCTION mydataset.names_by_year(y INT64)
RETURNS TABLE<name STRING, year INT64, total INT64>
AS
  SELECT year, name, SUM(number) AS total
  FROM `bigquery-public-data.usa_names.usa_1910_current`
  WHERE year = y
  GROUP BY year, name

CREATE PROCEDURE ステートメント

新しいプロシージャを作成します。これは、他のクエリから呼び出し可能なステートメントのブロックです。 プロシージャは、それ自体を再帰的に呼び出すことができます。

構文

CREATE [OR REPLACE] PROCEDURE [IF NOT EXISTS]
[[project_name.]dataset_name.]procedure_name (procedure_argument[, ...] )
[OPTIONS(procedure_option_list)]
BEGIN
multi_statement_query
END;

procedure_argument: [procedure_argument_mode] argument_name argument_type

procedure_argument_mode: IN | OUT | INOUT

引数

  • OR REPLACE: 同じ名前のプロシージャが存在する場合は、置き換えます。IF NOT EXISTS と一緒には使用できません。

  • IF NOT EXISTS: 同じ名前のプロシージャが存在する場合、CREATE ステートメントは無効になります。OR REPLACE と一緒には使用できません。

  • project_name**: プロシージャを作成するプロジェクトの名前。デフォルトでは、この DDL クエリを実行するプロジェクトの名前が設定されます。プロジェクト名にコロンなどの特殊文字が含まれている場合は、バッククォート ` で囲む必要があります（例: `google.com:my_project`）。

  • dataset_name: プロシージャを作成するプロジェクトの名前。デフォルトでは、リクエスト内の defaultDataset の名前が設定されます。

  • procedure_name: 作成するプロシージャの名前。

  • multi_statement_query: 実行する複数ステートメント クエリ。

  • argument_type: 有効な BigQuery のタイプ。

  • procedure_argument_mode: 引数が入力、出力、またはその両方のいずれであるかを指定します。

procedure_option_list

procedure_option_list では、プロシージャのオプションを指定できます。プロシージャのオプションの構文と要件はテーブル オプションの場合と同じですが、NAME と VALUE のリストは異なります。

NAME VALUE 詳細
strict_mode

BOOL

例: strict_mode=FALSE

strict_mode が TRUE の場合、プロシージャの本文に追加のエラーチェックが実行され、存在しないテーブルや列などがないかどうか確認されます。これらのチェックのいずれかに失敗すると、CREATE PROCEDURE ステートメントは失敗します。

strict_mode は、一般的なタイプのエラーを検出するのに便利ですが、すべてのエラーを網羅したものではありません。strict_mode を含むプロシージャが正しく作成されても、ランタイムにプロシージャが正常に実行されるとは限りません。

strict_mode が FALSE の場合、プロシージャの本文では構文のみがチェックされます。検証中にまだ存在しないプロシージャによってエラーが発生しないようにするには、strict_mode=FALSE を使用して、自身を繰り返し呼び出すプロシージャを作成する必要があります。

デフォルト値は TRUE です。

引数モード

IN は、引数がプロシージャへの入力にすぎないということを示します。IN 引数には、変数または値の式のいずれかを指定できます。

OUT は、引数がプロシージャの出力であることを示します。OUT 引数は、プロシージャが開始するときに NULL に初期化されます。OUT 引数には変数を指定する必要があります。

INOUT は、引数がプロシージャからの入力と出力の両方であることを示します。INOUT 引数には変数を指定する必要があります。INOUT 引数は、プロシージャ本体で変数として参照され、新しい値が割り当てられます。

IN、OUT、INOUT のいずれも指定されていない場合、引数は IN 引数として扱われます。

変数のスコープ

変数がプロシージャの外部で宣言され、INOUT 引数または OUT 引数としてプロシージャに渡され、プロシージャがその変数に新しい値を割り当てると、新しい値はプロシージャの外部に表示されます。

プロシージャ内で宣言された変数は、プロシージャ外では表示できません。逆に、プロシージャ外で宣言された変数は、プロシージャ内では表示できません。

OUT 引数または INOUT 引数には、SET を使用して値が割り当てられる場合があります。この場合、変更された値はプロシージャの外部に表示されます。プロシージャが正常に終了した場合、OUT 引数または INOUT 引数は INOUT 変数に最後に割り当てられた値になります。

一時テーブルはスクリプトの存続期間中に存在するため、プロシージャが一時テーブルを作成する場合、プロシージャの呼び出し側も一時テーブルを参照できます。

プロシージャ本文のデフォルト プロジェクト

プロシージャの本文は、プロジェクトを指定せずにエンティティを参照できます。プロシージャを所有するプロジェクトがデフォルトのプロジェクトになりますが、このプロジェクトが CREATE PROCEDURE ステートメントの実行に使用されるとは限りません。以下のサンプルクエリを検討してください。

CREATE PROCEDURE myProject.myDataset.QueryTable()
BEGIN
  SELECT * FROM anotherDataset.myTable;
END;

上記のプロシージャを作成したら、クエリ CALL myProject.myDataset.QueryTable() を実行できます。この CALL クエリを実行するプロジェクトとしてどのプロジェクトを選択しても、参照されるテーブル anotherDataset.myTable は常にプロジェクト myProject に対して解決されます。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.routines.create プロシージャを作成するデータセット。

さらに、OR REPLACE 句には bigquery.routines.update 権限が必要です。

Examples

次の例では、入力引数として x を取り、出力として x を返しています。delta 引数は、引数モードが指定されていないため入力引数になります。このプロシージャは、1 つのステートメントを含むブロックで構成され、2 つの入力引数の合計を x に割り当てます。

CREATE PROCEDURE mydataset.AddDelta(INOUT x INT64, delta INT64)
BEGIN
  SET x = x + delta;
END;

次の例では、上記の例の AddDelta プロシージャを呼び出しています。2 つの呼び出しの両方で、accumulator 変数を渡しています。ここで、AddDelta 内の x の変化は AddDelta の外に表示されるので、これらのプロシージャ呼び出しによって accumulator が合計で 8 加算されます。

DECLARE accumulator INT64 DEFAULT 0;
CALL mydataset.AddDelta(accumulator, 5);
CALL mydataset.AddDelta(accumulator, 3);
SELECT accumulator;

これにより、次の結果が返されます。

+-------------+
| accumulator |
+-------------+
|           8 |
+-------------+

次の例では、target_date を入力引数、rows_added を出力とするプロシージャ SelectFromTablesAndAppend を作成しています。このプロシージャは、クエリから一時テーブル DataForTargetDate を作成し、DataForTargetDate 内の行数を計算した結果を rows_added に代入します。次に、target_date の値を列名の 1 つとして渡して、新しい行が TargetTable に挿入されます。最後に、テーブル DataForTargetDate を削除して rows_added を返します。

CREATE PROCEDURE mydataset.SelectFromTablesAndAppend(
  target_date DATE, OUT rows_added INT64)
BEGIN
  CREATE TEMP TABLE DataForTargetDate AS
  SELECT t1.id, t1.x, t2.y
  FROM dataset.partitioned_table1 AS t1
  JOIN dataset.partitioned_table2 AS t2
  ON t1.id = t2.id
  WHERE t1.date = target_date
    AND t2.date = target_date;

  SET rows_added = (SELECT COUNT(*) FROM DataForTargetDate);

  SELECT id, x, y, target_date  -- note that target_date is a parameter
  FROM DataForTargetDate;

  DROP TABLE DataForTargetDate;
END;

次の例では、変数 rows_added を宣言し、CURRENT_DATE の値とともに上記の例の SelectFromTablesAndAppend プロシージャに引数として渡しています。追加された行数を示すメッセージが返されます。

DECLARE rows_added INT64;
CALL mydataset.SelectFromTablesAndAppend(CURRENT_DATE(), rows_added);
SELECT FORMAT('Added %d rows', rows_added);

CREATE ROW ACCESS POLICY ステートメント

行レベルのアクセス ポリシーを作成または置き換えます。テーブルの行レベルのアクセス ポリシーには一意の名前を付ける必要があります。

構文

CREATE [ OR REPLACE ] ROW ACCESS POLICY [ IF NOT EXISTS ]
row_access_policy_name ON table_name
[GRANT TO (grantee_list)]
FILTER USING (filter_expression);

引数

  • IF NOT EXISTS: 同じ名前の行レベルのアクセス ポリシーが存在する場合、CREATE ステートメントは無視されます。OR REPLACE と一緒には使用できません。

  • row_access_policy_name: 作成する行レベルのアクセス ポリシーの名前。行レベルのアクセス ポリシー名は、テーブルごとに一意である必要があります。行レベルのアクセス ポリシー名には次のものを含めることができます。

    • 最大 256 文字。
    • 英字（大文字または小文字）、数字、アンダースコア。先頭は英文字でなければなりません。

  • table_name: 行レベルのアクセス ポリシーを作成するテーブルの名前。テーブルはすでに存在している必要があります。

  • GRANT TO grantee_list: 行レベルのアクセス ポリシーを作成する必要がある初期メンバーを指定するオプションの句。

    grantee_list は iam_member のユーザーまたはグループのリストです。文字列は、IAM ポリシー バインディングのメンバーで使用される形式に従い、有効な IAM のプリンシパルまたはメンバーである必要があります。また、引用符で囲まなければなりません。次の型がサポートされています。

    grantee_list 型
    user:{emailid}

    特定の Google アカウントを表すメールアドレス。

    例: user:alice@example.com

    serviceAccount:{emailid}

    サービス アカウントを表すメールアドレス。

    例: serviceAccount:my-other-app@appspot.gserviceaccount.com

    group:{emailid}

    Google グループを表すメールアドレス。

    例: group:admins@example.com

    domain:{domain}

    そのドメインのすべてのユーザーを表す Google Workspace ドメイン（プライマリ）。

    例: domain:example.com

    allAuthenticatedUsers すべてのサービス アカウントと、Google アカウントで認証されたユーザー全員を表す特殊な識別子。この ID には、個人用 Gmail アカウントなど、Google Workspace または Cloud Identity のドメインに接続していないアカウントも含まれます。認証されていないユーザー（匿名の訪問者など）は含まれません。
    allUsers インターネット上のすべてのユーザーを表す特殊な識別子。認証されたユーザーと認証されていないユーザーの両方を含みます。BigQuery では、ユーザーがサービスにアクセスする前に認証が必要になるため、allUsers には認証済みのユーザーのみが含まれます。

    一連の iam_member 値は、カンマ区切りにして引用符で囲むことで、組み合わせることができます。例: "user:alice@example.com","group:admins@example.com","user:sales@example.com"

  • filter_expression: grantee_list のメンバーにのみ表示するテーブル行のサブセットを定義します。filter_expression は、SELECT クエリの WHERE 句に似ています。

    有効なフィルタ式は次のとおりです。

    • BigQuery の標準 SQL スカラー関数、集計関数、分析関数。
    • SESSION_USER()。クエリを実行しているユーザーに属する行にのみアクセスを制限します。クエリを実行しているユーザーに行レベルのアクセス ポリシーを適用できない場合、ユーザーはテーブル内のデータにアクセスできません。
    • TRUE。grantee_list フィールドのプリンシパルに、テーブルのすべての行に対するアクセス権を付与します。

    次のものはフィルタ式に含めることはできません。

    • テーブルへの参照。
    • サブクエリ、または SELECT、CREATE、UPDATE などの SQL ステートメント。
    • ユーザー定義関数。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.rowAccessPolicies.create ターゲット テーブル。
bigquery.rowAccessPolicies.setIamPolicy ターゲット テーブル。
bigquery.tables.getData ターゲット テーブル。

Examples

CREATE CAPACITY ステートメント

新しい容量コミットメントを作成してスロットを購入します。

構文

CREATE CAPACITY
project_id.location_id.commitment_id
AS JSON
capacity_json_object

引数

  • project_id: このコミットメントのオーナー権限を保持する管理プロジェクトのプロジェクト ID。
  • location_id: プロジェクトの ロケーション。
  • commitment_id: コミットメントの ID。値は、プロジェクトとロケーションに対して一意である必要があります。先頭と末尾は英小文字または数字にしてください。使用できるのは英小文字、数字、ダッシュのみです。
  • capacity_json_object: 容量コミットメントを記述する JSON 文字列です。

capacity_json_object

次のフィールドを含む JSON オブジェクトを指定します。

NAME TYPE 詳細
plan 文字列 購入するコミットメント プラン。サポートされる値: FLEX、MONTHLY、ANNUAL。詳細については、コミットメント プランをご覧ください。
renewal_plan 文字列 コミットメント更新プラン。plan が ANNUAL の場合にのみ適用されます。詳細については、コミットメントの更新をご覧ください。
slot_count 整数 コミットメントのスロット数。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.capacityCommitments.create コミットメントの所有権を管理する管理プロジェクト。

例

次の例では、region-us リージョンにあり、プロジェクト admin_project で管理される 100 個の Flex Slots のスロットの容量コミットメントを作成します。

CREATE CAPACITY `admin_project.region-us.my-commitment`
AS JSON """{
 "slot_count": 100,
 "plan": "FLEX"
}"""

CREATE RESERVATION ステートメント

予約を作成します。詳細については、予約の概要をご覧ください。

構文

CREATE RESERVATION
project_id.location_id.reservation_id
AS JSON
reservation_json_object

引数

  • project_id: 容量コミットメントが作成された管理プロジェクトのプロジェクト ID。
  • location_id: プロジェクトの ロケーション。
  • reservation_id: 予約 ID。
  • reservation_json_object: 予約を記述する JSON 文字列。

reservation_json_object

次のフィールドを含む JSON オブジェクトを指定します。

NAME TYPE 詳細
ignore_idle_slots ブール値 値が true の場合、予約には、そこにプロビジョニングされているスロットのみが使用されます。デフォルト値は false です。詳細については、アイドル スロットをご覧ください。
slot_capacity 整数 予約に割り当てるスロットの数。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.reservations.create コミットメントの所有権を管理する管理プロジェクト。

例

次の例では、プロジェクト admin_project に 100 スロットの予約を作成しています。

CREATE RESERVATION `admin_project.region-us.prod`
AS JSON """{
 "slot_capacity": 100
}"""

CREATE ASSIGNMENT ステートメント

プロジェクト、フォルダ、または組織を予約に割り当てます。

構文

CREATE ASSIGNMENT
project_id.location_id.reservation_id.assignment_id
AS JSON
assignment_json_object

引数

  • project_id: 予約が作成された管理プロジェクトのプロジェクト ID。
  • location_id: プロジェクトの ロケーション。
  • reservation_id: 予約 ID。
  • assignment_id: 割り当ての ID。値は、プロジェクトとロケーションに対して一意である必要があります。先頭と末尾は英小文字または数字にしてください。使用できるのは英小文字、数字、ダッシュのみです。
  • assignment_json_object: 割り当てを記述する JSON 文字列です。

予約からプロジェクトを削除してオンデマンド課金を使用するには、reservation_id を none に設定します。

assignment_json_object

次のフィールドを含む JSON オブジェクトを指定します。

NAME TYPE 詳細
assignee 文字列 予約に割り当てるプロジェクト、フォルダまたは組織の ID。
job_type 文字列 この予約に割り当てるジョブの種類。サポートされている値には、QUERY、PIPELINE、ML_EXTERNAL があります。詳しくは、割り当てをご覧ください。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.reservationAssignments.create 管理プロジェクトとその割り当て先。

例

次の例では、プロジェクト my_project をクエリジョブの prod 予約に割り当てます。

CREATE ASSIGNMENT `admin_project.region-us.prod.my_assignment`
AS JSON """{
 "assignee": "projects/my_project",
 "job_type": "QUERY"
}"""

次の例では、読み込みジョブやエクスポート ジョブなどのパイプライン ジョブの prod 予約に組織を割り当てます。

CREATE ASSIGNMENT `admin_project.region-us.prod.my_assignment`
AS JSON """{
 "assignee": "organizations/1234",
 "job_type": "PIPELINE"
}"""

CREATE SEARCH INDEX ステートメント

テーブルの 1 つ以上の列に新しい検索インデックスを作成します。

検索インデックスにより、SEARCH 関数を使用した効率的なクエリが可能になります。

構文

CREATE SEARCH INDEX [ IF NOT EXISTS ] index_name
ON table_name({ALL COLUMNS | column_name [, ...]})

引数

  • IF NOT EXISTS: テーブルにその名前のインデックスがすでに存在する場合は、何も処理しません。テーブルに別の名前のインデックスが存在する場合は、エラーを返します。

  • index_name: 作成するインデックスの名前。インデックスは常にベーステーブルと同じプロジェクトとデータセットに作成されるため、名前にこれらを指定する必要はありません。

  • table_name: テーブルの名前。テーブルパスの構文をご覧ください。

  • ALL COLUMNS: STRING フィールドを含むテーブル内のすべての列にインデックスを作成します。

  • column_name: テーブル内の最上位列の名前。STRING であるか、STRING フィールドを含みます。列は次のいずれかの型であることが必要です。

    • STRING
    • ARRAY<STRING>
    • STRING 型または ARRAY<STRING> 型のネストされたフィールドを 1 つ以上含む STRUCT
    • JSON

詳細

ベーステーブルごとに 1 つのインデックスのみを作成できます。ビューまたはマテリアライズド ビューに対してインデックスを作成することはできません。インデックス登録される列を変更するには、現在のインデックスを DROP して新しい列を作成します。

column_name が STRING ではないか、STRING フィールドを含まない場合、または STRING フィールドを含まないテーブルの ALL COLUMNS に対して CREATE SEARCH INDEX を呼び出す場合、BigQuery はエラーを返します。

列 ACL または行フィルタが設定されたテーブルではインデックスの作成が失敗しますが、インデックスの作成後にそれらすべてがテーブルに追加される場合があります。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.tables.createIndex インデックスを作成するベーステーブル。

Examples

次の例では、my_table のすべての文字列の列に my_index というインデックスを作成します。この場合、インデックスは列 a にのみ作成されます。

CREATE TABLE dataset.my_table(a STRING, b INT64);

CREATE SEARCH INDEX my_index
ON dataset.my_table(ALL COLUMNS);

次の例では、列 a、my_struct.string_field、b にインデックスを作成します。

CREATE TABLE dataset.complex_table(
  a STRING,
  my_struct STRUCT<string_field STRING, int_field INT64>,
  b ARRAY<STRING>
);

CREATE SEARCH INDEX my_index
ON dataset.complex_table(a, my_struct, b);

ALTER SCHEMA SET DEFAULT COLLATE ステートメント

データセットに照合仕様を設定します。

構文

ALTER SCHEMA [IF EXISTS]
[project_name.]dataset_name
SET DEFAULT COLLATE collate_specification

引数

  • IF EXISTS: 同じ名前のデータセットが存在しない場合、ステートメントは無効になります。

  • DEFAULT COLLATE collate_specification: スキーマに新しいテーブルが作成されると、列 に対して照合仕様が明示的に指定されていない限り、テーブルに対してデフォルトの照合仕様が継承されます。

    更新された照合仕様は、以降に作成されるテーブルにのみ適用されます。既存の照合仕様を更新する場合は、仕様を含む列を変更する必要があります。

  • project_name: データセットを含むプロジェクトの名前デフォルトでは、この DDL ステートメントを実行するプロジェクトの名前が設定されます。

  • dataset_name: データセットの名前。

  • collate_specification: 設定する照合仕様を指定します。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.datasets.get 変更するデータセット。
bigquery.datasets.update 変更するデータセット。

例

mydataset というスキーマ内に mytable_a という既存のテーブルがあるとします。例:

CREATE SCHEMA mydataset

CREATE TABLE mydataset.mytable_a
(
  number INT64,
  word STRING
)

+----------------------+
| mydataset.mytable_a  |
|   number INT64       |
|   word STRING        |
+----------------------+

後で、照合仕様をスキーマに追加することにします。例:

ALTER SCHEMA mydataset
SET DEFAULT COLLATE 'und:ci'

スキーマに新しいテーブルを作成すると、すべての STRING 列で COLLATE 'und:ci' が継承されます。たとえば、mydataset スキーマで mytable_b テーブルを作成すると、characters に照合が追加されます。

CREATE TABLE mydataset.mytable_b
(
  amount INT64,
  characters STRING
)

+--------------------------------------+
| mydataset.mytable_b                  |
|   amount INT64                       |
|   characters STRING COLLATE 'und:ci' |
+--------------------------------------+

ただし、スキーマの照合仕様は更新されたものの、既存のテーブル mytable_a では前の照合仕様が引き続き使用されます。例:

+---------------------+
| mydataset.mytable_a |
|   number INT64      |
|   word STRING       |
+---------------------+

ALTER SCHEMA SET OPTIONS ステートメント

データセットのオプションを設定します。

データセットが存在する場合は、クエリの設定でロケーションを指定しない限り、データセットのロケーション内で実行されます。詳細については、ロケーションの指定をご覧ください。

構文

ALTER SCHEMA [IF EXISTS]
[project_name.]dataset_name
SET OPTIONS(schema_set_options_list)

引数

  • IF EXISTS: 同じ名前のデータセットが存在しない場合、ステートメントは無効になります。

  • project_name: データセットを含むプロジェクトの名前デフォルトでは、この DDL ステートメントを実行するプロジェクトの名前が設定されます。

  • dataset_name: データセットの名前。

  • schema_set_options_list: 設定するオプションのリスト。

schema_set_options_list

オプション リストは、データセットのオプションを指定します。NAME=VALUE, ... の形式でオプションを指定します。

次のオプションがサポートされています。

NAME VALUE 詳細
default_kms_key_name STRING このデータセット内のテーブルデータを暗号化するためのデフォルトの Cloud KMS 鍵を指定します。テーブルの作成時にこの値をオーバーライドできます。
default_partition_expiration_days FLOAT64 このデータセットのテーブル パーティションのデフォルトの有効期限を日数で指定します。テーブルの作成時にこの値をオーバーライドできます。
default_table_expiration_days FLOAT64 このデータセットのテーブルのデフォルトの有効期限を日数で指定します。テーブルの作成時にこの値をオーバーライドできます。
description STRING データセットの説明。
friendly_name STRING データセットのわかりやすい名前。
labels <ARRAY<STRUCT<STRING, STRING>>> Key-Value ペアで表現されるデータセットのラベルの配列。
location STRING データセットを作成するロケーション。このオプションを指定しない場合、クエリが実行されるロケーションにデータセットが作成されます。このオプションを指定してクエリジョブのロケーションを明示的に設定する場合は、2 つの値が一致する必要があります。それ以外の場合、クエリは失敗します。
max_time_travel_hours SMALLINT

プレビュー版

データセットのタイムトラベル期間を時間で指定します。max_time_travel_hours 値は、整数の 48（2 日）～168（7 日）にする必要があります。このフラグを指定しない場合のデフォルトは 168 時間です。

タイムトラベル期間の詳細については、タイムトラベル期間の構成をご覧ください。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.datasets.get 変更するデータセット。
bigquery.datasets.update 変更するデータセット。

例

次の例では、デフォルトのテーブルの有効期限を設定しています。

ALTER SCHEMA mydataset
SET OPTIONS(
  default_table_expiration_days=3.75
  )

ALTER TABLE SET OPTIONS ステートメント

テーブルのオプションを設定します。

構文

ALTER TABLE [IF EXISTS] table_name
SET OPTIONS(table_set_options_list)

引数

  • IF EXISTS: 同じ名前のテーブルが存在しない場合、ステートメントは無効になります。

  • table_name: 変更するテーブルの名前。テーブルパスの構文をご覧ください。

  • table_set_options_list: 設定するオプションのリスト。

詳細

このステートメントは、外部テーブルではサポートされていません。

table_set_options_list

オプション リストを使用すると、ラベルや有効期限などのテーブル オプションを設定できます。カンマ区切りのリストを使用して複数のオプションを含めることができます。

テーブル オプション リストは次の形式で指定します。

NAME=VALUE, ...

NAME と VALUE は、次のいずれかの組み合わせである必要があります。

NAME VALUE 詳細
expiration_timestamp TIMESTAMP

例: expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

このプロパティは、expirationTime テーブル リソース プロパティと同等です。
partition_expiration_days

FLOAT64

例: partition_expiration_days=7

パーティションの有効期限を日数で設定します。詳細については、パーティションの有効期限の設定をご覧ください。デフォルトでは、パーティションは期限切れになりません。

このプロパティは、timePartitioning.expirationMs テーブル リソース プロパティと同等ですが、単位はミリ秒ではなく日数です。1 日は 86,400,000 ミリ秒または 24 時間に相当します。

このプロパティは、テーブルが分割されている場合にのみ設定できます。
require_partition_filter

BOOL

例: require_partition_filter=true

このテーブルのクエリに、パーティショニングする列を除外する述語フィルタを含める必要があるかどうかを指定します。詳細については、パーティション フィルタの要件を設定するをご覧ください。デフォルト値は false です。

このプロパティは、timePartitioning.requirePartitionFilter テーブル リソース プロパティと同等です。

このプロパティは、テーブルが分割されている場合にのみ設定できます。
kms_key_name

STRING

例: kms_key_name="projects/project_id/locations/location/keyRings/keyring/cryptoKeys/key"

このプロパティは、encryptionConfiguration.kmsKeyName テーブル リソース プロパティと同等です。

詳細については、Cloud KMS 鍵によるデータの保護をご覧ください。
friendly_name

STRING

例: friendly_name="my_table"

このプロパティは、friendlyName テーブル リソース プロパティと同等です。
description

STRING

例: description="a table that expires in 2025"

このプロパティは、description テーブル リソース プロパティと同等です。
labels

ARRAY<STRUCT<STRING, STRING>>

例: labels=[("org_unit", "development")]

このプロパティは、labels テーブル リソース プロパティと同等です。

VALUE は、リテラル、クエリ パラメータ、スカラー関数のみを含む定数式です。

定数式には以下を含めることはできません。

  • テーブルへの参照
  • サブクエリ、または SELECT、CREATE、UPDATE などの SQL ステートメント。
  • ユーザー定義関数、集計関数、または分析関数
  • 以下のスカラー関数:
    • ARRAY_TO_STRING
    • REPLACE
    • REGEXP_REPLACE
    • RAND
    • FORMAT
    • LPAD
    • RPAD
    • REPEAT
    • SESSION_USER
    • GENERATE_ARRAY
    • GENERATE_DATE_ARRAY

VALUE を設定すると、オプションが存在する場合は、テーブルのそのオプションの既存の値が置き換えられます。VALUE を NULL に設定すると、テーブルのそのオプションの値が消去されます。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.tables.get 変更するテーブル。
bigquery.tables.update 変更するテーブル。

Examples

テーブルの有効期限タイムスタンプと説明の設定

次の例では、テーブルの有効期限タイムスタンプを ALTER TABLE ステートメントの実行時刻から 7 日後に設定し、説明も設定します。

ALTER TABLE mydataset.mytable
SET OPTIONS (
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 7 DAY),
  description="Table that expires seven days from now"
)

パーティション分割テーブルにパーティション フィルタ必須の属性を設定

次の例では、パーティション分割テーブルに timePartitioning.requirePartitionFilter 属性を設定しています。

ALTER TABLE mydataset.mypartitionedtable
SET OPTIONS (require_partition_filter=true)

このテーブルを参照するクエリではパーティショニング列に対するフィルタを使用する必要があります。そうしないと BigQuery はエラーを返します。このオプションを true に設定すると、意図したよりも多くのデータのクエリを行う際の間違いを防ぐことができます。

テーブルの有効期限タイムスタンプの消去

次の例では、期限切れにならないように、テーブルの有効期限タイムスタンプを消去します。

ALTER TABLE mydataset.mytable
SET OPTIONS (expiration_timestamp=NULL)

ALTER TABLE ADD COLUMN ステートメント

既存のテーブル スキーマに 1 つ以上の新しい列を追加します。

構文

ALTER TABLE table_name
ADD COLUMN [IF NOT EXISTS] column[, ...]

引数

  • table_name: テーブルの名前。テーブルパスの構文をご覧ください。

  • IF EXISTS: 列名がすでに存在する場合、ステートメントは無効になります。

  • column: 追加する列。これには、追加する列の名前とスキーマが含まれます。列名とスキーマは、CREATE TABLE ステートメントと同じ構文を使用します。

詳細

このステートメントで以下のものを作成することはできません。

  • パーティション分割テーブル。
  • クラスタリング列。
  • 既存の RECORD フィールド内にネストされた列。

REQUIRED 列を既存のテーブル スキーマに追加することはできません。ネストされた REQUIRED 列は、新しい RECORD フィールドの一部として作成します。

このステートメントは、外部テーブルではサポートされていません。

IF NOT EXISTS 句がなく、テーブルにその名前の列がすでに存在する場合は、ステートメントがエラーを返します。IF NOT EXISTS 句があり、列名がすでに存在する場合、エラーは返されず、アクションも実行されません。

既存の行の新しい列の値は、次のいずれかに設定されます。

  • 新しい列が NULLABLE モードで追加された場合は NULL。これがデフォルト モードです。
  • 新しい列が REPEATED モードで追加された場合は、空の ARRAY になります。

BigQuery でスキーマを変更する方法については、テーブル スキーマの変更をご覧ください。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.tables.get 変更するテーブル。
bigquery.tables.update 変更するテーブル。

Examples

列の追加

次の例では、mytable という名前の既存のテーブルに次の列を追加します。

  • STRING 型の列 A。
  • GEOGRAPHY 型の列 B。
  • NUMERIC 型で REPEATED モードの列 C。
  • DATE 型の列 D と説明。
ALTER TABLE mydataset.mytable
  ADD COLUMN A STRING,
  ADD COLUMN IF NOT EXISTS B GEOGRAPHY,
  ADD COLUMN C ARRAY<NUMERIC>,
  ADD COLUMN D DATE OPTIONS(description="my description")

A、C、D という名前の列のいずれかが存在する場合、ステートメントは失敗します。列 B が存在する場合、IF NOT EXISTS 句によりステートメントが成功します。

RECORD 列の追加

次の例では、次のネストされた列を含む STRUCT 型の A という列を追加します。

  • GEOGRAPHY 型の列 B。
  • INT64 型で REPEATED モードの列 C。
  • INT64 型で REQUIRED モードの列 D。
  • TIMESTAMP 型の列 E と説明。
ALTER TABLE mydataset.mytable
   ADD COLUMN A STRUCT<
       B GEOGRAPHY,
       C ARRAY<INT64>,
       D INT64 NOT NULL,
       E TIMESTAMP OPTIONS(description="creation time")
       >

指定した列がネストされていない場合でも、テーブルに A という名前の列が存在すると、クエリは失敗します。

A という新しい STRUCT は null 値を許容できますが、A 内のネストされた列 D は A のすべての STRUCT 値で必要になります。

列に照合サポートを追加する

テーブルに新しい列を作成する場合、その列に新しい照合仕様を明示的に割り当てることができます。

ALTER TABLE mydataset.mytable
ADD COLUMN word STRING COLLATE 'und:ci'

ALTER TABLE RENAME TO ステートメント

クローン、スナップショット、テーブルの名前を変更します。

構文

ALTER TABLE [IF EXISTS] table_name
RENAME TO new_table_name

引数

  • IF EXISTS: 同じ名前のテーブルが存在しない場合、ステートメントは無効になります。

  • table_name: 名前を変更するテーブルの名前。テーブルパスの構文をご覧ください。

  • new_table_name: テーブルの新しい名前。新しい名前に既存のテーブル名を使用することはできません。

詳細

  • このステートメントは、外部テーブルではサポートされていません。
  • テーブルの名前を変更するときにテーブル ポリシーまたは行レベルのアクセス ポリシーを変更すると、変更内容が反映されないことがあります。
  • データストリーミングを含むテーブルの名前を変更する場合は、ストリーミングを停止して、BigQuery がストリーミングを使用していないことを示すまで待つ必要があります。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.tables.get 変更するテーブル。
bigquery.tables.update 変更するテーブル。

Examples

テーブルの名前の変更

次の例では、テーブル mydataset.mytable の名前を mydataset.mynewtable に変更しています。

ALTER TABLE mydataset.mytable RENAME TO mynewtable

ALTER TABLE DROP COLUMN ステートメント

既存のテーブル スキーマから 1 つ以上の列をドロップします。

構文

ALTER TABLE table_name
DROP COLUMN [IF EXISTS] column_name [, ...]

引数

  • table_name: 変更するテーブルの名前。テーブルパスの構文をご覧ください。このテーブルはすでに存在し、スキーマが必要です。

  • IF EXISTS: 指定した列が存在しない場合、ステートメントは無効になります。

  • column_name: ドロップする列の名前。

詳細

このステートメントは、ドロップされた列に関連付けられたストレージをすぐには解放しません。ストレージは、列がドロップされた日から 7 日間にわたってバックグラウンドで要求されます。

ストレージの再利用については、テーブル スキーマからの列の削除をご覧ください。

このステートメントで次の列のドロップはできません。

  • パーティション分割列
  • クラスタリング列
  • 既存の RECORD フィールド内にネストされた列

このステートメントは、外部テーブルではサポートされていません。

IF EXISTS 句を使用しない場合、テーブルにその名前の列が含まれていなければ、ステートメントはエラーを返します。IF EXISTS 句が含まれ、かつ列名が存在しない場合は、エラーは返されず、アクションも実行されません。

このステートメントでは、テーブルからのみ列が削除されます。ビューやマテリアライズド ビューなど、列を参照するオブジェクトは、個別に更新または再作成する必要があります。

BigQuery でスキーマを変更する方法については、テーブル スキーマの変更をご覧ください。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.tables.get 変更するテーブル。
bigquery.tables.update 変更するテーブル。

Examples

列をドロップする

次の例では、mytable という名前の既存のテーブルから次の列をドロップします。

  • 列 A
  • 列 B
ALTER TABLE mydataset.mytable
  DROP COLUMN A,
  DROP COLUMN IF EXISTS B

A という名前の列が存在しない場合、ステートメントは失敗します。列 B が存在しない場合、このステートメントはIF EXISTS 句によって成功します。

ALTER TABLE SET DEFAULT COLLATE ステートメント

テーブルに照合仕様を設定します。

構文

ALTER TABLE
  table_name
  SET DEFAULT COLLATE collate_specification

引数

  • table_name: 変更するテーブルの名前。テーブルパスの構文をご覧ください。このテーブルはすでに存在し、スキーマが必要です。

  • SET DEFAULT COLLATE collate_specification: スキーマで新しい列が作成され、列に明示的な照合仕様が設定されていない場合、列は STRING 型に関するこの照合仕様を継承します。更新された照合仕様は、以降に追加される列にのみ適用されます。

    既存の照合仕様を更新する場合は、仕様を含む列を変更する必要があります。既存のテーブルの新しい列に照合仕様を追加する場合は、列を追加します。列に直接照合仕様を追加する場合、列の照合仕様はテーブルのデフォルトの照合仕様よりも優先されます。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.tables.get 変更するテーブル。
bigquery.tables.update 変更するテーブル。

例

mydataset というスキーマ内に mytable という既存のテーブルがあるとします。

CREATE TABLE mydataset.mytable
(
  number INT64,
  word STRING
) DEFAULT COLLATE 'und:ci'

mytable を作成すると、すべての STRING 列は COLLATE 'und:ci' を継承します。結果の表の構造は次のようになります。

+--------------------------------+
| mydataset.mytable              |
|   number INT64                 |
|   word STRING COLLATE 'und:ci' |
+--------------------------------+

後で、テーブルの照合仕様を変更することにします。

ALTER TABLE mydataset.mytable
SET DEFAULT COLLATE ''

照合順序は更新されたものの、既存の列 word では前の照合仕様が引き続き使用されます。

+--------------------------------+
| mydataset.mytable              |
|   number INT64                 |
|   word STRING COLLATE 'und:ci' |
+--------------------------------+

ただし、テーブルに新しい列を作成する場合は、新しい列に新しい照合仕様が含まれます。次の例では、name という列が追加されます。新しい照合仕様が空であるため、デフォルトの照合仕様が使用されます。

ALTER TABLE mydataset.mytable
ADD COLUMN name STRING

+--------------------------------+
| mydataset.mytable              |
|   number INT64                 |
|   word STRING COLLATE 'und:ci' |
|   name STRING COLLATE          |
+--------------------------------+

ALTER COLUMN SET OPTIONS ステートメント

BigQuery のテーブル内の列に、列の説明などのオプションを設定します。

構文

ALTER TABLE [IF EXISTS] table_name
ALTER COLUMN [IF EXISTS] column_name SET OPTIONS(column_set_options_list)

引数

  • (ALTER TABLE) IF EXISTS: 同じ名前のテーブルが存在しない場合、ステートメントは無効になります。

  • table_name: 変更するテーブルの名前。テーブルパスの構文をご覧ください。

  • (ALTER COLUMN) IF EXISTS: 指定した列が存在しない場合、ステートメントは無効になります。

  • column_name: 変更する最上位列の名前。STRUCT のネストされた列などのサブフィールドは変更できません。

  • column_set_options_list: 列に設定するオプションのリスト。

詳細

このステートメントは、外部テーブルではサポートされていません。

column_set_options_list

列オプション リストは次の形式で指定します。

NAME=VALUE, ...

NAME と VALUE は、次のいずれかの組み合わせである必要があります。

NAME VALUE 詳細
description

STRING

例: description="a table that expires in 2025"

VALUE は、リテラル、クエリ パラメータ、スカラー関数のみを含む定数式です。

定数式には以下を含めることはできません。

  • テーブルへの参照
  • サブクエリ、または SELECT、CREATE、UPDATE などの SQL ステートメント。
  • ユーザー定義関数、集計関数、または分析関数
  • 以下のスカラー関数:
    • ARRAY_TO_STRING
    • REPLACE
    • REGEXP_REPLACE
    • RAND
    • FORMAT
    • LPAD
    • RPAD
    • REPEAT
    • SESSION_USER
    • GENERATE_ARRAY
    • GENERATE_DATE_ARRAY

VALUE を設定すると、オプションが存在する場合は、列のそのオプションの既存の値が置き換えられます。VALUE を NULL に設定すると、列のそのオプションの値が消去されます。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.tables.get 変更するテーブル。
bigquery.tables.update 変更するテーブル。

Examples

次の例では、price という列に新しい説明を設定します。

ALTER TABLE mydataset.mytable
ALTER COLUMN price
SET OPTIONS (
  description="Price per unit"
)

ALTER COLUMN DROP NOT NULL ステートメント

BigQuery のテーブルの列から NOT NULL 制約を削除します。

構文

ALTER TABLE [IF EXISTS] table_name
ALTER COLUMN [IF EXISTS] column DROP NOT NULL

引数

  • (ALTER TABLE) IF EXISTS: 同じ名前のテーブルが存在しない場合、ステートメントは無効になります。

  • table_name: 変更するテーブルの名前。テーブルパスの構文をご覧ください。

  • (ALTER COLUMN) IF EXISTS: 指定した列が存在しない場合、ステートメントは無効になります。

  • column_name: 変更する最上位列の名前。サブフィールドの変更はサポートされていません。

詳細

列に NOT NULL 制約がない場合、クエリはエラーを返します。

このステートメントは、外部テーブルではサポートされていません。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.tables.get 変更するテーブル。
bigquery.tables.update 変更するテーブル。

Examples

次の例では、mycolumn という列から NOT NULL 制約を削除します。

ALTER TABLE mydataset.mytable
ALTER COLUMN mycolumn
DROP NOT NULL

ALTER COLUMN SET DATA TYPE ステートメント

BigQuery テーブル内の列のデータ型を制限の緩いデータ型に変更します。たとえば、NUMERIC データ型は BIGNUMERIC 型に変更できますが、その逆はできません。

構文

ALTER TABLE [IF EXISTS] table_name
ALTER COLUMN [IF EXISTS] column_name SET DATA TYPE column_schema

引数

  • (ALTER TABLE) IF EXISTS: 同じ名前のテーブルが存在しない場合、ステートメントは無効になります。

  • table_name: 変更するテーブルの名前。テーブルパスの構文をご覧ください。

  • (ALTER COLUMN) IF EXISTS: 指定した列が存在しない場合、ステートメントは無効になります。

  • column_name: 変更する最上位列の名前。サブフィールドの変更はサポートされていません。

  • column_schema: 列の変換後のスキーマ。このスキーマでは、CREATE TABLE ステートメントと同じ構文を使用します。

詳細

データ型の有効な強制変換については、標準 SQL の変換ルールページで変換前の列と強制型変換後の列をご覧ください。

次に、データ型の有効な強制変換の例を示します。

  • INT64 から NUMERIC、BIGNUMERIC、FLOAT64
  • NUMERIC から BIGNUMERIC、FLOAT64

このステートメントは、外部テーブルではサポートされていません。

IF EXISTS 句を使用しない場合、テーブルにその名前の列が含まれていなければ、ステートメントはエラーを返します。IF EXISTS 句が含まれ、かつ列名が存在しない場合は、エラーは返されず、アクションも実行されません。

データ型は、制限の緩いパラメータ化されたデータ型に強制変換することもできます。たとえば、文字列型の最大長を増やすことや、数値型の精度やスケールを拡大することが可能です。

パラメータ化されたデータ型の有効な変更例は次のとおりです。

  • NUMERIC(6,10) から NUMERIC(8,12)
  • NUMERIC から BIGNUMERIC(40, 20)
  • STRING(5) から STRING(7)

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.tables.get 変更するテーブル。
bigquery.tables.update 変更するテーブル。

Examples

列のデータ型を変更する

次の例では、列 c1 のデータ型を INT64 から NUMERIC に変更します。

CREATE TABLE dataset.table(c1 INT64);

ALTER TABLE dataset.table ALTER COLUMN c1 SET DATA TYPE NUMERIC;

フィールドのデータ型を変更する

次の例では、s1 列のフィールドの 1 つのデータ型を変更します。

CREATE TABLE dataset.table(s1 STRUCT<a INT64, b STRING>);

ALTER TABLE dataset.table ALTER COLUMN s1
SET DATA TYPE STRUCT<a NUMERIC, b STRING>;

精度の変更

次の例では、パラメータ化されたデータ型の列の精度を変更します。

CREATE TABLE dataset.table (pt NUMERIC(7,2));

ALTER TABLE dataset.table
ALTER COLUMN pt
SET DATA TYPE NUMERIC(8,2);

ALTER VIEW SET OPTIONS ステートメント

ビューのオプションを設定します。

構文

ALTER VIEW [IF EXISTS] view_name
SET OPTIONS(view_set_options_list)

引数

  • IF EXISTS: 指定した名前のビューが存在しない場合、ステートメントは無効になります。

  • view_name: 変更するビューの名前。テーブルパスの構文をご覧ください。

  • view_set_options_list: 設定するオプションのリスト。

view_set_options_list

オプション リストを使用すると、ラベルや有効期限などのビュー オプションを設定できます。カンマ区切りのリストを使用して複数のオプションを含めることができます。

ビュー オプション リストは次の形式で指定します。

NAME=VALUE, ...

NAME と VALUE は、次のいずれかの組み合わせである必要があります。

NAME VALUE 詳細
expiration_timestamp TIMESTAMP

例: expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

このプロパティは、expirationTime テーブル リソース プロパティと同等です。
friendly_name

STRING

例: friendly_name="my_view"

このプロパティは、friendlyName テーブル リソース プロパティと同等です。
description

STRING

例: description="a view that expires in 2025"

このプロパティは、description テーブル リソース プロパティと同等です。
labels

ARRAY<STRUCT<STRING, STRING>>

例: labels=[("org_unit", "development")]

このプロパティは、labels テーブル リソース プロパティと同等です。

VALUE は、リテラル、クエリ パラメータ、スカラー関数のみを含む定数式です。

定数式には以下を含めることはできません。

  • テーブルへの参照
  • サブクエリ、または SELECT、CREATE、UPDATE などの SQL ステートメント。
  • ユーザー定義関数、集計関数、または分析関数
  • 以下のスカラー関数:
    • ARRAY_TO_STRING
    • REPLACE
    • REGEXP_REPLACE
    • RAND
    • FORMAT
    • LPAD
    • RPAD
    • REPEAT
    • SESSION_USER
    • GENERATE_ARRAY
    • GENERATE_DATE_ARRAY

VALUE を設定すると、オプションが存在する場合は、ビューのそのオプションの既存の値が置き換えられます。VALUE を NULL に設定すると、ビューのそのオプションの値が消去されます。

必要な権限

このステートメントには、次の IAM 権限が必要です。

権限 リソース
bigquery.tables.get 変更するビュー。
bigquery.tables.update 変更するビュー。

Examples

ビューの有効期限タイムスタンプと説明の設定

次の例では、ビューの有効期限タイムスタンプを ALTER VIEW ステートメントの実行時刻から 7 日後に設定し、説明も設定します。

ALTER VIEW mydataset.myview
SET OPTIONS (
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 7 DAY),
  description="View that expires seven days from now"
)

ALTER MATERIALIZED VIEW SET OPTIONS ステートメント

マテリアライズド ビューのオプションを設定します。

構文

ALTER MATERIALIZED VIEW [IF EXISTS] materialized_view_name
SET OPTIONS(materialized_view_set_options_list)

引数

  • IF EXISTS: 指定した名前のマテリアライズド ビューが存在しない場合、ステートメントは無効になります。

  • materialized_view_name: 変更するマテリアライズド ビューの名前。