コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

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

必要な権限

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

IAM 役割

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

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

DDL ステートメントの実行

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

コンソール

  1. Google Cloud Console の [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 データセットのわかりやすい名前。
is_case_insensitive BOOL

データセットとそのテーブル名で大文字と小文字を区別しない場合は TRUE、それ以外の場合は FALSE。デフォルトでは、FALSE です。つまり、データセットとそのテーブル名では大文字と小文字を区別します。

  • データセット: mydataset と MyDataset は、いずれかで大文字と小文字の区別が有効である限り、同じプロジェクトで共存できます。
  • テーブル: mytable と MyTable は、データセットで大文字と小文字の区別が有効な場合、同じデータセット内で共存できます。
labels <ARRAY<STRUCT<STRING, STRING>>> Key-Value ペアで表現されるデータセットのラベルの配列。
location STRING データセットを作成するロケーション。このオプションを指定しない場合、クエリが実行されるロケーションにデータセットが作成されます。このオプションを指定してクエリジョブのロケーションを明示的に設定する場合は、2 つの値が一致する必要があります。それ以外の場合、クエリは失敗します。
max_time_travel_hours SMALLINT

プレビュー版

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

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

storage_billing_model STRING

プレビュー版。

ストレージ変更の計算時に論理バイトではなく物理バイトを使用するように、データセットのストレージ課金モデルを変更します。この変更を行うには、storage_billing_model 値を physical に設定します。

データセットの課金モデルを変更する場合、変更が有効になるまで 24 時間かかります。

物理ストレージを使用するようにデータセットのストレージ課金モデルを変更した場合、論理バイトを使用するように変更することはできません。

必要な権限

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

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

例

新しいデータセットの作成

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

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

大文字と小文字を区別しないデータセットの作成

次の例では、大文字と小文字を区別しないデータセットを作成します。データセット名とデータセット名では、大文字と小文字が区別されません。

CREATE SCHEMA mydataset
OPTIONS(
  is_case_insensitive=TRUE
)

照合サポートを持つデータセットの作成

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

CREATE SCHEMA mydataset
DEFAULT COLLATE 'und:ci'

CREATE TABLE ステートメント

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

構文

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

column:=
column_definition

constraint_definition:=
[primary_key]
| [[CONSTRAINT constraint_name] foreign_key, ...]

primary_key :=
PRIMARY KEY (column_name[, ...]) NOT ENFORCED

foreign_key :=
FOREIGN KEY (column_name[, ...]) foreign_reference

foreign_reference :=
REFERENCES primary_key_table(column_name[, ...]) NOT ENFORCED

引数

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

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

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

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

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

  • constraint_definition: テーブル制約を定義する式。

  • collation_specification: 明示的に照合仕様なしで新しい列をテーブルに追加すると、列は、STRING 型に関するこの照合仕様を継承します。

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

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

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

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

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

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

  • primary_key: 主キーテーブル制約を定義する式。

  • foreign_key: 外部キーテーブル制約を定義する式。

詳細

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
     | STRUCT<field_list>
     | ARRAY<array_element_schema>
   }
   [PRIMARY KEY NOT ENFORCED | REFERENCES table_name(column_name) NOT ENFORCED]
   [DEFAULT default_expression]
   [NOT NULL]
   [OPTIONS(column_option_list)]

simple_type :=
  { data_type | STRING COLLATE collate_specification }

field_list :=
  field_name column_schema [, ...]

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

  • 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 がテーブルに割り当てられている場合は、列の照合仕様がテーブルの仕様をオーバーライドします。

  • default_expression: 列に割り当てられているデフォルト値。

  • 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

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

NAME=VALUE, ...

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

NAME VALUE 詳細
description

STRING

例: description="a unique id"

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

STRING

プレビュー版。

例: rounding_mode = "ROUND_HALF_EVEN"

パラメータ化された NUMERIC 型または BIGNUMERIC 型の列、または STRUCT フィールドに書き込まれる値に使用される丸めモードを指定します。次の値を使用できます。

  • "ROUND_HALF_AWAY_FROM_ZERO": 中間の値の場合は、ゼロから遠ざかるように丸められます。たとえば、2.5 は 3.0 に丸められ、-2.5 は -3 に丸められます。
  • "ROUND_HALF_EVEN": 中間値の場合は、最も近い偶数に丸められます。たとえば、2.5 は 2.0 に丸められ、-2.5 は -2.0 に丸められます。

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

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.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) OPTIONS(rounding_mode = 'ROUND_HALF_EVEN'),
    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: