データ定義言語(DDL)ステートメントの使用

データ定義言語(DDL)ステートメントを使用すると、標準 SQL クエリ構文を使用して BigQuery リソースを作成および変更できます。現時点では、BigQuery で DDL コマンドを使用して次のことができます。

必要な権限

ジョブを作成して DDL ステートメントを実行するには、すべてのユーザーに bigquery.jobs.create 権限が必要です。また、DDL ステートメントの種類ごとに特定の実行権限が必要になります。このセクションでは、これらの権限を提供する Identity and Access Management(IAM)のロールと、ステートメントの種類ごとに必要な権限について説明します。

IAM ロール

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

bigquery.admin ロールと bigquery.dataOwner ロールには、DDL ステートメントの実行に必要な他のすべての権限が含まれています。次のセクションの表のように、bigquery.dataEditor ロールには必要な権限が含まれています。

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

DDL ステートメントの実行に必要な権限

DDL ステートメントの種類によって必要な実行権限が異なります。次の表をご覧ください。

SQL ステートメント 権限 IAM ロール 権限の詳細
CREATE EXTERNAL TABLE bigquery.tables.create bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
テーブルの権限
CREATE FUNCTION bigquery.routines.create bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
CREATE MATERIALIZED VIEW bigquery.tables.create bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
マテリアライズド ビューの権限
CREATE PROCEDURE bigquery.routines.create bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
CREATE SCHEMA bigquery.datasets.create bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
データセットの権限
CREATE TABLE bigquery.tables.create bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
テーブルの権限
CREATE VIEW bigquery.tables.create bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
表示権限
ALTER COLUMN
DROP NOT NULL
bigquery.tables.get
bigquery.tables.update
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
テーブルの権限
ALTER COLUMN
SET OPTIONS
bigquery.tables.get
bigquery.tables.update
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
テーブルの権限
ALTER MATERIALIZED VIEW
SET OPTIONS
bigquery.tables.get
bigquery.tables.update
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
マテリアライズド ビューの権限
ALTER SCHEMA
SET OPTIONS
bigquery.datasets.get
bigquery.datasets.update
bigquery.admin
bigquery.dataOwner
データセットの更新権限
ALTER TABLE
ADD COLUMN
bigquery.tables.get
bigquery.tables.update
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
テーブル管理の権限
ALTER TABLE
SET OPTIONS
bigquery.tables.get
bigquery.tables.update
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
テーブル管理の権限
ALTER TABLE
DROP COLUMN
bigquery.tables.get
bigquery.tables.update
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
テーブル管理の権限
ALTER VIEW
SET OPTIONS
bigquery.tables.get
bigquery.tables.update
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
テーブル管理の権限
DROP EXTERNAL TABLE bigquery.tables.delete
bigquery.tables.get
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
テーブル削除の権限
DROP FUNCTION bigquery.routines.delete bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
DROP MATERIALIZED VIEW bigquery.tables.delete
bigquery.tables.get
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
マテリアライズド ビューの権限
DROP PROCEDURE bigquery.routines.delete
bigquery.routines.get
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
DROP SCHEMA bigquery.datasets.delete
bigquery.tables.delete
*

* 空のスキーマには不要です。
bigquery.admin
bigquery.dataOwner
スキーマ削除の権限
DROP TABLE bigquery.tables.delete
bigquery.tables.get
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
テーブル削除の権限
DROP VIEW bigquery.tables.get
bigquery.tables.update
bigquery.admin
bigquery.dataEditor
bigquery.dataOwner
テーブル削除の権限

DDL ステートメントの実行

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

Console

  1. 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 クエリが完了するまで待ちます。

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

// 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 クエリが完了するまで待ちます。

# 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
[OPTIONS(schema_option_list)]

ここで

  • IF NOT EXISTS: この句を含み、なおかつデータセットがすでに存在する場合、ステートメントは成功し、アクションは実行されません。この句を省略して、データセットがすでに存在する場合、ステートメントはエラーを返します。
  • 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 つの値は一致する必要があります。それ以外の場合、クエリは失敗します。

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

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

CREATE TABLE ステートメント

BigQuery でテーブルを作成するには、CREATE TABLE DDL ステートメントを使用します。

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

ここで

  • IF NOT EXISTS: 指定されたデータセットにテーブルが存在しない場合にのみ新しいテーブルを作成します。OR REPLACE では表示できません。

  • TEMP | TEMPORARY: 一時テーブルを作成します。詳細については、一時テーブルをご覧ください。

  • OR REPLACE。同じ名前のテーブルが存在する場合は、置き換えます。IF NOT EXISTS では表示できません。

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 LIKE: 既存のテーブルと同じスキーマを持つテーブルを作成します。
  • CREATE TABLE COPY: 既存のテーブルからスキーマとデータをコピーして、テーブルを作成します。

テーブルパス

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

dataset_name は、テーブルを作成するデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

table_name は、作成するテーブルの名前です。

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

  • 1,024 文字以内。
  • カテゴリ L(文字)、M(マーク)、N(数字)、Pc(コネクタ、アンダースコアを含む)、Pd(ダッシュ)、Zs(スペース)の Unicode 文字を含む。詳しくは、一般カテゴリをご覧ください。

たとえば、table 01ग्राहक00_お客様étudiant-01 はすべて有効なテーブル名です。

一部のテーブル名とテーブル名の接頭辞は予約済みです。テーブル名または接頭辞が予約されているというエラーが表示された場合は、別の名前を選択して、もう試してください。

column

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]

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

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

    • 英字(大文字または小文字)、数字(0~9)、アンダースコア(_)だけが含まれている
    • 英字またはアンダースコアで始まっている
    • 300 文字以内である
  • column_schemaデータ型に似ていますが、ARRAY 以外の型に対してはオプションの NOT NULL 制約をサポートします。column_schema は、トップレベルの列と STRUCT フィールドに対するオプションもサポートします。

    column_schema は、CREATE TABLE ステートメントの列定義リストでのみ使用できます。式の中の型として使用することはできません。たとえば、CAST(1 AS INT64 NOT NULL) は無効です。

  • simple_type は、サポートされている任意のデータ型です(STRUCTARRAY は除きます)。

  • 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_schemaNOT NULL 属性は、テーブルに対するクエリを通じて伝播されません。たとえば、テーブル Tx INT64 NOT NULL として宣言されている列がある場合、CREATE TABLE dataset.newtable AS SELECT x FROM T によって xNULLABLE である 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, ...

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

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 は、リテラル、クエリ パラメータ、スカラー関数のみを含む定数式です。定数式が null と評価された場合、対応するオプション NAME は無視されます。

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

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

column_option_list

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

NAME VALUE 詳細
description

STRING

例: description="a unique id"

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

query_statement

AS query_statement 句は、作成されるテーブルからのクエリを指定します。query_statement でサポートされている形式については、SQL 構文リファレンスをご覧ください。

既知の制限事項:

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

CREATE TABLE LIKE

別のテーブルの同じメタデータをすべて含む新しいテーブルを作成するには、CREATE TABLE ステートメントを使用するときに、列リストを LIKE 句に置き換えます。

構文

{CREATE TABLE | CREATE TABLE IF NOT EXISTS | CREATE OR REPLACE TABLE}
[[project_name.]dataset_name.]table_name
LIKE [[project_name.]dataset_name.]source_table_name
[PARTITION BY partition_expression]
[CLUSTER BY clustering_column_list]
[OPTIONS(table_option_list)]
[AS query_statement]

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

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

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

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

CREATE TABLE COPY

別のテーブルの同じメタデータとデータを含む新しいテーブルを作成するには、CREATE TABLE ステートメントを使用するときに、列リストを COPY 句に置き換えます。

構文

{CREATE TABLE | CREATE TABLE IF NOT EXISTS | CREATE OR REPLACE TABLE}
[[project_name.]dataset_name.]table_name
COPY [[project_name.]dataset_name.]source_table_name
[OPTIONS(table_option_list)]

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

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

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

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

新しいテーブルの作成

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

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: wordSTRING)と word_count(単語数を表す INT64)の 2 つのフィールドを持つ STRUCTARRAY

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

  • 説明: 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 列を持つテーブルを作成する

次の例では、mydatasetnewtable という名前のテーブルが作成されます。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 の浮動小数点数)を持つ REQUIRED の STRUCT
  • z: NULLABLE の文字列

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

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

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

CREATE SNAPSHOT TABLE ステートメント

標準テーブルのテーブル スナップショットを作成するか、テーブル スナップショットのコピーを作成するには、CREATE SNAPSHOT TABLE DDL ステートメントを使用します。

{CREATE SNAPSHOT TABLE | CREATE SNAPSHOT TABLE IF NOT EXISTS}
[[snapshot_project_name.]snapshot_dataset_name.]table_snapshot_name
CLONE [[source_project_name.]source_dataset_name.]source_table_name
[FOR SYSTEM_TIME AS OF time_expression]
[OPTIONS(snapshot_option_list)]

ここで

{CREATE SNAPSHOT TABLE | CREATE SNAPSHOT TABLE IF NOT EXISTS} は、次のステートメントのいずれかです。

  • CREATE SNAPSHOT TABLE: 指定されたテーブル スナップショット名が存在しない場合は、新しいテーブル スナップショットを作成します。指定されたテーブル スナップショット名がすでに存在する場合は、エラーが返されます。
  • CREATE SNAPSHOT TABLE IF NOT EXISTS: 指定されたテーブル スナップショット名が存在しない場合は、新しいテーブル スナップショットを作成します。指定されたテーブル スナップショットの名前がすでに存在する場合は、アクションは実行されず、エラーは返されません。

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

snapshot_dataset_name は、テーブル スナップショットを作成するデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

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

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

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

CLONE は、スナップショットを作成するテーブルを指定するか、コピーするテーブル スナップショットを指定します。

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

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

source_dataset_name は、スナップショットを作成するテーブルを含むデータセットの名前か、コピーするテーブル スナップショットを含むデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

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

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

  • 使用できる CREATE ステートメントは 1 つのみです。
  • クローンを作成するテーブルは、次のいずれかである必要があります。
    • 標準のテーブル(ビューまたはマテリアライズド ビューではない)
    • テーブル スナップショット
  • FOR SYSTEM_TIME AS OF 句は、テーブル スナップショットを作成する場合にのみ使用できます。テーブル スナップショットのコピーを作成する場合は使用できません。

snapshot_option_list

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

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

NAME=VALUE, ...

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

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 は、リテラル、クエリ パラメータ、スカラー関数のみを含む定数式です。定数式が null と評価された場合、対応するオプション NAME は無視されます。

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

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

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

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

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 のテーブル スナップショットを作成します。テーブル スナップショットは、データセット mydatasetmytablesnapshot という名前で作成されます。

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 ステートメント

テーブル スナップショットを BigQuery の標準テーブルに復元するには、CREATE TABLE CLONE DDL ステートメントを使用します。

{CREATE TABLE | CREATE TABLE IF NOT EXISTS | CREATE OR REPLACE TABLE}
[[destination_project_name.]destination_dataset_name.]destination_table_name
CLONE [[snapshot_project_name.]snapshot_dataset_name.]table_snapshot_name
[OPTIONS(table_option_list)]

ここで

{CREATE TABLE | CREATE TABLE IF NOT EXISTS | CREATE OR REPLACE TABLE} は、次のステートメントのいずれかです。

  • CREATE TABLE: 指定された宛先テーブル名が存在しない場合は、テーブル スナップショットから新しいテーブルを作成します。指定された宛先テーブル名が存在する場合は、エラーが返されます。
  • CREATE TABLE IF NOT EXISTS: 指定された宛先テーブル名が存在しない場合は、テーブル スナップショットから新しいテーブルを作成します。指定された宛先テーブル名がすでに存在する場合、アクションは実行されず、エラーも返されません。
  • CREATE OR REPLACE TABLE: テーブルを作成し、既存のテーブルを指定されたデータセット内の同じ名前に置き換えます。

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

destination_dataset_name は、テーブルを作成するデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

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

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

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

CLONE では、復元するテーブル スナップショットを指定します。

snapshot_project_name は、復元するテーブル スナップショットを含むプロジェクトの名前です。デフォルトでは、この DDL クエリを実行するプロジェクトの名前が設定されます。プロジェクト名にコロンなどの特殊文字が含まれている場合は、バッククォート ` で囲む必要があります(例: `google.com:my_project`)。

snapshot_dataset_name は、復元するテーブル スナップショットを含むデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

table_snapshot_name は、復元するテーブル スナップショットの名前です。

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

  • 使用できる CREATE ステートメントは 1 つのみです。
  • クローンを作成するテーブルは、テーブル スナップショットでなければなりません。

OPTIONS

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

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

次の例では、テーブル スナップショット 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.mytableshapshot からテーブル myproject.mydataset.mytable を作成します。

CREATE TABLE IF NOT EXISTS `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")]
)
CLONE `myproject.mydataset.mytablesnapshot`

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

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

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

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

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

一時テーブルを作成する

次の例では、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

例 1

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

CREATE TABLE mydataset.newtable
LIKE mydataset.newtable
例 2

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

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

CREATE VIEW ステートメント

BigQuery でビューを作成するには、CREATE VIEW DDL ステートメントを使用します。

{CREATE VIEW | CREATE VIEW IF NOT EXISTS | CREATE OR REPLACE VIEW}
[[project_name.]dataset_name.]view_name [(view_column_name_list)]
[OPTIONS(view_option_list)]
AS query_expression

ここで

{CREATE VIEW | CREATE VIEW IF NOT EXISTS | CREATE OR REPLACE VIEW} は、次のステートメントのいずれかです。

  • CREATE VIEW: 新しいビューを作成します。
  • CREATE VIEW IF NOT EXISTS: 指定されたデータセット内に現在ビューが存在しない場合にのみ、新しいビューを作成します。
  • CREATE OR REPLACE VIEW: 指定したデータセット内にビューを作成し、同じ名前のビューが存在する場合は置き換えます。

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

dataset_name は、ビューを作成するデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

view_name は、作成するビューの名前です。

BigQuery でビューを作成する場合、ビュー名はデータセットごとに一意にする必要があります。ビュー名には次の制限があります。

  • 1,024 文字以内。
  • カテゴリ L(文字)、M(マーク)、N(数字)、Pc(コネクタ、アンダースコアを含む)、Pd(ダッシュ)、Zs(スペース)の Unicode 文字を含む。詳しくは、一般カテゴリをご覧ください。

たとえば、view 01ग्राहक00_お客様étudiant-01 はすべて有効なビュー名です。

一部のビュー名とビュー名の接頭辞は予約されています。ビュー名または接頭辞が予約されているというエラーが表示された場合は、別の名前を選択して、もう一度試してください。

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

view_option_list を使用すると、ラベルや有効期限などのビュー作成オプションを追加で指定できます。

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

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

query_expression は、ビューの定義に使用される標準 SQL クエリ式です。

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, ...

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

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 は、リテラル、クエリ パラメータ、スカラー関数のみを含む定数式です。定数式が null と評価された場合、対応するオプション NAME は無視されます。

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

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

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

ビューが 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 と異なるプロジェクトで実行される場合は無効になります。

新しいビューの作成

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

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 ステートメント

BigQuery で実体化されたビューを作成するには、CREATE MATERIALIZED VIEW DDL ステートメントを使用します。

{CREATE MATERIALIZED VIEW | CREATE MATERIALIZED VIEW IF NOT EXISTS }
[[project_name.]dataset_name.]materialized_view_name
[PARTITION BY partition_expression]
[CLUSTER BY clustering_column_list]
[OPTIONS(materialized_view_option_list)]
AS query_expression

ここで

{CREATE MATERIALIZED VIEW | CREATE MATERIALIZED VIEW IF NOT EXISTS } は、次のステートメントのいずれかです。

  • CREATE MATERIALIZED VIEW: 新しい実体化されたビューを作成します。

  • CREATE MATERIALIZED VIEW IF NOT EXISTS: 指定されたデータセット内に現在実体化されたビューが存在しない場合にのみ、新しい実体化されたビューを作成します。

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

project_name が省略されているか、この DDL クエリを実行するプロジェクトと同じである場合、後者は query_expression のテーブル、関数などへの参照のデフォルト プロジェクトとしても使用されます(参照のデフォルト プロジェクトは固定され、今後新しく実体化されるビューを起動するクエリに依存しません)。それ以外の場合は、query_expression 内のすべての参照をプロジェクトで修飾する必要があります。

dataset_name は、実体化されたビューを作成するデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

materialized_view_name は、作成する実体化されたビューの名前です。実体化されたビュー名は、データセット内で一意である必要があります。実体化されたビュー名には次の制限があります。

  • 1,024 文字以内
  • 英字(大文字または小文字)、数字、アンダースコアだけが含まれている

PARTITION BY 句と CLUSTER BY 句は、CREATE TABLE ステートメントの場合と同様に使用します。マテリアライズド ビューは、query expression(ベーステーブル)内のテーブルと同じ方法で分割できます。

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

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

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

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

materialized_view_option_list

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

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

NAME=VALUE, ...

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

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 テーブル リソース プロパティと同等です。

実体化されたビュー本文のデフォルト プロジェクト

実体化されたビューが 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 と異なるプロジェクトで実行される場合は無効になります。

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

次の例では、mydatasetnew_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

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

次の例では、mydatasetnew_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_tablecol_datetime 列で分割する必要があります。詳細については、パーティション分割テーブルとクラスタ化テーブルの操作をご覧ください。

CREATE EXTERNAL TABLE ステートメント

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

CREATE [OR REPLACE] EXTERNAL TABLE [IF NOT EXISTS] [[project_name.]dataset_name.]table_name
[(
  column_name column_schema,
  ...
)]

[WITH PARTITION COLUMNS
  [(
      partition_column_name partition_column_type,
      ...
  )]
]
OPTIONS (
  external_table_option_list,
  ...
);

ここで

  • project_name は、テーブルを作成するプロジェクトの名前です。デフォルトでは、この DDL クエリを実行するプロジェクトの名前が設定されます。

  • dataset_name は、テーブルを作成するデータセットの名前です。

  • table_name は外部テーブルの名前です。

  • column_name はテーブルの列の名前です。

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

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

  • partition_column_type はパーティション列のタイプです。

  • external_table_option_list には、外部テーブルを作成するためのオプションのリストを指定します。

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 データに適用されます。

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

外部データの形式。サポートされる値: AVROCSVDATASTORE_BACKUPGOOGLE_SHEETSNEWLINE_DELIMITED_JSON(または JSON)、ORCPARQUET

JSONNEWLINE_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 データに適用されます。

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/*"]

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

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

次の例では、複数の 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_1STRING)と field_2INT64)になります。

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 をサポートしています。UDF の詳細については、標準 SQL ユーザー定義関数をご覧ください。

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

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

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 }

この構文は、次のコンポーネントで構成されています。

  • IF NOT EXISTS。指定されたデータセットに関数が存在しない場合にのみ、新しい関数を作成します。OR REPLACE では表示できません。

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

  • OR REPLACE。同じ名前の関数が存在する場合は、置き換えます。IF NOT EXISTS では表示できません。

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

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

  • function_name。関数名。

  • named_parameter。カンマで区切られた param_nameparam_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 UDF にのみ適用されます。

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

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

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"]

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

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

ここで

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

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

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

詳細については、テーブル関数をご覧ください。

次のテーブル関数は、クエリ結果のフィルタに使用する 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
statement_list
END;

procedure_argument: [procedure_argument_mode] argument_name argument_type

procedure_argument_mode: IN | OUT | INOUT

説明

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

dataset_name は、プロシージャを作成するデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

statement_list は、BigQuery のステートメント リストです。ステートメント リストは、それぞれがセミコロンで終わる一連のステートメントです。

argument_type は、任意の有効な BigQuery のタイプです。

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

プロシージャは、それ自体を再帰的に呼び出すことができます。

procedure_option_list

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

NAME VALUE 詳細
strict_mode

BOOL

例: strict_mode=FALSE

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

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

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

デフォルト値は TRUE です。

引数モード

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

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

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

INOUTINOUT のいずれも指定されていない場合、引数は 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 に対して解決されます。

次の例では、入力引数として 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 ステートメント

DDL ステートメントで次のコマンドを使用して、行レベルのアクセス ポリシーを作成または置換します。テーブルの行レベルのアクセス ポリシーには一意の名前を付ける必要があります。

構文

  {CREATE ROW ACCESS POLICY | CREATE ROW ACCESS POLICY IF NOT EXISTS |
  CREATE OR REPLACE ROW ACCESS POLICY}
  row_access_policy_name ON table_name
  [GRANT TO (grantee_list)]
  FILTER USING (filter_expression);
要素名 要素の説明

row_access_policy_name

作成する行レベルのアクセス ポリシーの名前。行レベルのアクセス ポリシー名は、テーブルごとに一意である必要があります。行レベルのアクセス ポリシー名には次のものを含めることができます。
  • 256 文字以内。
  • 英字(大文字または小文字)、数字、アンダースコアだけが含まれている。先頭は英字でなければなりません。
My_row_filter

table_name

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

grantee_list
grantee_list := iam_member [, ...]

GRANT TO は、行レベルのアクセス ポリシーを作成する必要がある初期メンバーを指定します。これはオプションの句です。

grantee_listiam_member のユーザーまたはグループのリストです。

文字列は、IAM ポリシー バインディング メンバーの形式に従う有効な IAM メンバーで、引用符で囲まれている必要があります。

次のタイプがサポートされています。
  • user:{emailid}: 特定の Google アカウントを表すメールアドレス。
  • serviceAccount:{emailid}: サービス アカウントを表すメールアドレス。
  • group:{emailid}: Google グループを表すメールアドレス。
  • domain:{domain}: そのドメインのすべてのユーザーを表す Google Workspace ドメイン(プライマリ)。
  • allAuthenticatedUsers: すべてのサービス アカウントと、Google アカウントで認証されたユーザー全員を表す特殊な識別子。この ID には、個人用 Gmail アカウントなど、Google Workspace または Cloud Identity のドメインに接続していないアカウントも含まれます。認証されていないユーザー(匿名の訪問者など)は含まれません。
  • allUsers: インターネット上のすべてのユーザーを表す特殊な識別子。認証されたユーザーと認証されていないユーザーの両方を含みます。BigQuery では、ユーザーがサービスにアクセスする前に認証が必要になるため、allUsers には認証済みのユーザーのみが含まれます。


一連の iam_member は、カンマ区切りで引用符で囲むことで、組み合わせることができます。
user:alice@example.com

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

group:admins@example.com

domain:example.com







"user:alice@example.com","user:amir@example.com","user:maya@example.com","group:admins@example.com","sales@example.com"

filter_expression

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

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

次のものはフィルタ式に含めることはできません。
  • テーブルへの参照。
  • サブクエリ、または SELECTCREATEUPDATE などの SQL ステートメント。
  • ユーザー定義関数。
region="us"

first_name="Robert"

行アクセス ポリシーを作成し、後で付与対象を変更する

   CREATE ROW ACCESS POLICY My_apac_filter
   ON project.dataset.My_table
   GRANT TO ("user:abc@example.com")
   FILTER USING (region = "apac");
   CREATE OR REPLACE ROW ACCESS POLICY My_apac_filter
   ON project.dataset.My_table
   GRANT TO ("user:xyz@example.com")
   FILTER USING (region = "apac");

複数の付与対象を使用して行アクセス ポリシーを作成する

   CREATE ROW ACCESS POLICY My_us_filter
   ON project.dataset.My_table
   GRANT TO ("user:john@example.com", "group:sales-us@example.com", "group:sales-managers@example.com")
   FILTER USING (region = "us");

付与対象として allAuthenticatedUsers を使用して行アクセス ポリシーを作成する

   CREATE ROW ACCESS POLICY My_us_filter
   ON project.dataset.My_table
   GRANT TO ("allAuthenticatedUsers")
   FILTER USING (region = "us");

現在のユーザーに基づくフィルタを使用して、行アクセス ポリシーを作成する

   CREATE ROW ACCESS POLICY My_row_filter
   ON dataset.My_table
   GRANT TO ("domain:example.com")
   FILTER USING (email = SESSION_USER());

ARRAY 型の列にフィルタを使用して行アクセス ポリシーを作成する

   CREATE ROW ACCESS POLICY My_reports_filter
   ON project.dataset.My_table
   GRANT TO ("domain:example.com")
   FILTER USING (SESSION_USER() IN UNNEST(reporting_chain));

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 つの値は一致する必要があります。それ以外の場合、クエリは失敗します。

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

ALTER SCHEMA mydataset
SET OPTIONS(
  default_table_expiration_days=3.75
  )

ALTER TABLE SET OPTIONS ステートメント

BigQuery のテーブルに対するオプションを設定するには、ALTER TABLE SET OPTIONS DDL ステートメントを使用します。

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

ここで

IF EXISTS: 指定されている場合、指定したテーブルが存在しなければクエリは成功します。指定されていない場合、指定したテーブルが存在しなければクエリは失敗します。

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

dataset_name は、変更するテーブルを含むデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

table_name は、変更するテーブルの名前です。

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

table_set_options_list

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

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

NAME=VALUE, ...

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

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 は、リテラル、クエリ パラメータ、スカラー関数のみを含む定数式です。定数式が null と評価された場合、対応するオプション NAME は無視されます。

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

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

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

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

次の例では、テーブルの有効期限タイムスタンプを 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 ステートメント

ALTER TABLE ADD COLUMN ステートメントは、既存のテーブル スキーマに 1 つ以上の新しい列を追加します。BigQuery でスキーマを変更する方法については、テーブル スキーマの変更をご覧ください。

ALTER TABLE [[project_name.]dataset_name.]table_name
ADD COLUMN [IF NOT EXISTS] column_name column_schema [, ...]

ここで

  • project_name は、テーブルを含むプロジェクトの名前です。デフォルトでは、この DDL クエリを実行するプロジェクトの名前が設定されます。

  • dataset_name は、テーブルを含むデータセットの名前です。

  • table_name は、変更するテーブルの名前です。このテーブルはすでに存在し、スキーマが必要です。

  • column_name は、追加する列の名前です。

  • column_schema は列のスキーマです。このスキーマでは、CREATE TABLE ステートメントの列スキーマと同じ構文を使用します。

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

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

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

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

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

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

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

列の追加

次の例では、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")

ACD という名前の列のいずれかが存在する場合、ステートメントは失敗します。列 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 内のネストされた列 DA のすべての STRUCT 値で必要になります。

ALTER TABLE RENAME TO ステートメント

BigQuery でテーブルを作成するには、ALTER TABLE RENAME TO DDL ステートメントを使用します。

ALTER TABLE [IF EXISTS] [[project_name.]dataset_name.]table_name
RENAME TO new_table_name

ここで

  • project_name は、テーブルを含むプロジェクトの名前です。デフォルトでは、この DDL クエリを実行するプロジェクトの名前が設定されます。
  • dataset_name は、テーブルを含むデータセットの名前です。
  • table_name は、名前を変更するテーブルの名前です。
  • new_table_name は、テーブルの新しい名前です。新しい名前に既存のテーブル名を使用することはできません。

IF EXISTS が存在する場合は、指定したテーブルが存在しないときにクエリが成功します。IF EXISTS が存在しない場合は、指定したテーブルが存在しないとクエリが失敗します。

注意点:

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

テーブルの名前の変更

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

ALTER TABLE mydataset.mytable RENAME TO mynewtable

ALTER TABLE DROP COLUMN ステートメント

ALTER TABLE DROP COLUMN ステートメントは、既存のテーブル スキーマから 1 つ以上の列をドロップします。このステートメントは、ドロップされた列に関連付けられたストレージをすぐには解放しません。ストレージは、列がドロップされた日から 7 日間にわたってバックグラウンドで要求されます。

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

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

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

ここで

  • project_name は、テーブルを含むプロジェクトの名前です。デフォルトでは、この DDL クエリを実行するプロジェクトの名前が設定されます。

  • dataset_name は、テーブルを含むデータセットの名前です。

  • table_name は、変更するテーブルの名前です。このテーブルはすでに存在し、スキーマが必要です。

  • column_name は、ドロップする列の名前です。

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

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

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

IF EXISTS 句を使用しない場合、テーブルにその名前の列が含まれていなければ、ステートメントはエラーを返します。IF EXISTS 句が含まれ、かつ列名が存在しない場合は、エラーは返されず、アクションも実行されません。

このステートメントでは、テーブルからのみ列が削除されます。ビューや実体化されたビューなど、列を参照するオブジェクトは、個別に更新または再作成する必要があります。

列をドロップする

次の例では、mytable という名前の既存のテーブルから次の列をドロップします。

  • A
  • B
ALTER TABLE mydataset.mytable
  DROP COLUMN A,
  DROP COLUMN IF EXISTS B

A という名前の列が存在しない場合、ステートメントは失敗します。列 B が存在しない場合、このステートメントはIF EXISTS 句によって成功します。

ALTER COLUMN SET OPTIONS ステートメント

BigQuery のテーブル内の列に、列の説明などのオプションを設定します。

ALTER TABLE [IF EXISTS] [[project_name.]dataset_name.]table_name
ALTER COLUMN [IF EXISTS] column_name SET OPTIONS(column_set_options_list)

ここで

(ALTER TABLE) IF EXISTS: 指定されている場合、指定したテーブルが存在しなければクエリは成功します。指定されていない場合、指定したテーブルが存在しなければクエリは失敗します。

(ALTER COLUMN) IF EXISTS: 指定されている場合、指定した列が存在しなければクエリは成功します。指定されていない場合、指定した列が存在しなければクエリは失敗します。

project_name は、変更するテーブルを含むプロジェクトの名前です。デフォルトでは、このクエリを実行するプロジェクトの名前が設定されます。プロジェクト名にコロンなどの特殊文字が含まれている場合は、名前をバッククォート ` で囲みます(例: `google.com:my_project`)。

dataset_name は、変更するテーブルを含むデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

table_name は、変更するテーブルの名前です。

column_name は、変更する最上位の列の名前です。STRUCT のネストされた列などのサブフィールドは変更できません。

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

column_set_options_list

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

NAME=VALUE, ...

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

NAME VALUE 詳細
description

STRING

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

VALUE は、リテラル、クエリ パラメータ、スカラー関数のみを含む定数式です。定数式が null と評価された場合、対応するオプション NAME は削除されます。

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

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

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

次の例では、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] [[project_name.]dataset_name.]table_name
ALTER COLUMN [IF EXISTS] column DROP NOT NULL

ここで

(ALTER TABLE) IF EXISTS: 指定されている場合、指定したテーブルが存在しなければクエリは成功します。指定されていない場合、指定したテーブルが存在しなければクエリは失敗します。

(ALTER COLUMN) IF EXISTS: 指定されている場合、指定した列が存在しなければクエリは成功します。指定されていない場合、指定した列が存在しなければクエリは失敗します。

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

dataset_name は、変更するテーブルを含むデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

table_name は、変更するテーブルの名前です。

column_name は、変更する最上位の列の名前です。サブフィールドの変更はサポートされていません。

列に NOT NULL 制約がない場合、クエリはエラーを返します。

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

次の例では、mycolumn という列から NOT NULL 制約を削除します。

ALTER TABLE mydataset.mytable
ALTER COLUMN mycolumn
DROP NOT NULL

ALTER COLUMN SET DATA TYPE ステートメント

BigQuery テーブル内の列のデータ型を制限の緩いデータ型に変更します。たとえば、NUMERIC データ型は BIGNUMERIC 型に変更できますが、その逆はできません。データ型の有効な強制変換については、標準 SQL の変換ルールページで変換前の列と強制型変換後の列をご覧ください。

次に、データ型の有効な強制変換の例を示します。

  • INT64 から NUMERIC、BIGNUMERIC、FLOAT64
  • NUMERIC から BIGNUMERIC、FLOAT64
ALTER TABLE [IF EXISTS] [[project_name.]dataset_name.]table_name
ALTER COLUMN [IF EXISTS] column_name SET DATA TYPE data_type

ここで

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

  • dataset_name は、変更するテーブルを含むデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

  • table_name は、変更するテーブルの名前です。

  • column_name は、変更する最上位の列の名前です。サブフィールドの変更はサポートされていません。

  • data_type は列の変換後の型です。

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

IF EXISTS 句を使用しない場合、テーブルにその名前の列が含まれていなければ、ステートメントはエラーを返します。IF EXISTS 句が含まれ、かつ列名が存在しない場合は、エラーは返されず、アクションも実行されません。

データ型は、制限の緩いパラメータ化されたデータ型に強制変換することもできます。たとえば、文字列型の最大長を増やすことや、数値型の精度やスケールを拡大することが可能です。

パラメータ化されたデータ型の有効な変更例は次のとおりです。

  • NUMERIC(6,10) から NUMERIC(8,12)
  • NUMERIC から BIGNUMERIC(40, 20)
  • STRING(5) から STRING(7)

次の例では、列 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 ステートメント

BigQuery のビューのオプションを設定するには、ALTER VIEW SET OPTIONS DDL ステートメントを使用します。

ALTER VIEW [IF EXISTS] [[project_name.]dataset_name.]view_name
SET OPTIONS(view_set_options_list)

ここで

IF EXISTS: 指定されている場合、指定したビューが存在しなければクエリは成功します。指定されていない場合、指定したビューが存在しなければクエリは失敗します。

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

dataset_name は、変更するビューを含むデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

view_name は、変更するビューの名前です。

view_set_options_list

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

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

NAME=VALUE, ...

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

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 は、リテラル、クエリ パラメータ、スカラー関数のみを含む定数式です。定数式が null と評価された場合、対応するオプション NAME は無視されます。

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

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

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

ビューの有効期限タイムスタンプと説明の設定

次の例では、ビューの有効期限タイムスタンプを 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 ステートメント

BigQuery の実体化されたビューのオプションを設定するには、ALTER MATERIALIZED VIEW SET OPTIONS DDL ステートメントを使用します。

ALTER MATERIALIZED VIEW [IF EXISTS] [[project_name.]dataset_name.]materialized_view_name
SET OPTIONS(materialized_view_set_options_list)

ここで

IF EXISTS: 指定されている場合、指定したビューが存在しなければクエリは成功します。指定されていない場合、指定したビューが存在しなければクエリは失敗します。

project_name は、変更する実体化されたビューを含むプロジェクトの名前です。デフォルトでは、この DDL クエリを実行するプロジェクトの名前が設定されます。プロジェクト名にコロンなどの特殊文字が含まれている場合は、バッククォート ` で囲む必要があります(例: `google.com:my_project`)。

dataset_name は、変更する実体化されたビューを含むデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

materialized_view_name は、変更するマテリアライズド ビューの名前です。

materialized_view_set_options_list

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

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

NAME=VALUE, ...

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

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 テーブル リソース プロパティと同等です。

VALUE を設定すると、オプションが存在する場合は、実体化されたビューのそのオプションの既存の値が置き換えられます。VALUENULL に設定すると、マテリアライズド ビューのそのオプションの値が消去されます。

実体化されたビューでの更新状態の有効化と更新間隔の設定

次の例では、更新を有効にし、更新間隔を 20 分に設定しています。

ALTER MATERIALIZED VIEW mydataset.my_mv
SET OPTIONS (
  enable_refresh=true,
  refresh_interval_minutes=20
)

DROP SCHEMA ステートメント

データセットを削除します。

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

DROP SCHEMA [IF EXISTS]
[project_name.]dataset_name
[ CASCADE | RESTRICT ]

ここで

  • IF EXISTS: この句を含み、かつ指定したデータセットが存在しない場合、ステートメントは成功し、アクションは実行されません。この句を省略し、かつデータセットが存在しない場合、ステートメントはエラーを返します。

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

  • dataset_name は、削除するデータセットの名前です。

  • CASCADE: データセット、データセット内のすべてのテーブル(テーブル、ビュー、関数など)を削除します。リソースを削除するには、リソースの削除権限が必要です。権限がないと、ステートメントからエラーが返されます。BigQuery の権限の一覧については、事前定義されたロールと権限をご覧ください。

  • RESTRICT: データセットが空の場合にのみ、そのデータセットを削除します。それ以外の場合はエラーを返します。

CASCADERESTRICT のどちらも指定されていない場合、デフォルトの動作は RESTRICT です。

次の例では、mydataset という名前のデータセットを削除します。データセットが存在しない場合または空でない場合、ステートメントはエラーを返します。

DROP SCHEMA mydataset

次の例では、mydataset という名前のデータセットとそのデータセット内のすべてのリソースをドロップします。データセットが存在しない場合、エラーは返されません。

DROP SCHEMA IF EXISTS mydataset CASCADE

DROP TABLE ステートメント

BigQuery でテーブルを削除するには、DROP TABLE DDL ステートメントを使用します。

DROP TABLE [IF EXISTS] [[project_name.]dataset_name.]table_name

ここで

IF EXISTS: 指定されている場合、指定したテーブルが存在しなければクエリは成功します。指定されていない場合、指定したテーブルが存在しなければクエリは失敗します。

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

dataset_name は、削除するテーブルを含むデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

table_name: 削除するテーブルの名前です。

テーブルの削除

次の例では、mydataset 内の mytable という名前のテーブルを削除します。

DROP TABLE mydataset.mytable

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

Error: Not found: Table myproject:mydataset.mytable

テーブルが存在する場合にのみテーブルを削除

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

DROP TABLE IF EXISTS mydataset.mytable

DROP SNAPSHOT TABLE ステートメント

BigQuery のテーブル スナップショットを削除するには、DROP SNAPSHOT TABLE DDL ステートメントを使用します。

DROP SNAPSHOT TABLE [IF EXISTS]
[[project_name.]dataset_name.]table_snapshot_name

ここで

IF EXISTS: 指定されている場合、指定したテーブル スナップショットが存在しなければクエリは成功します。指定されていない場合、指定したテーブル スナップショットが存在しなければクエリは失敗します。

project_name は、削除するテーブル スナップショットを含むプロジェクトの名前です。デフォルトでは、この DDL クエリを実行するプロジェクトの名前が設定されます。プロジェクト名にコロンなどの特殊文字が含まれている場合は、名前をバッククォート ` で囲みます(例: `google.com:my_project`)。

dataset_name は、削除するテーブル スナップショットを含むデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset データセットが使用されます。

table_snapshot_name: 削除するテーブル スナップショットの名前。

テーブル スナップショットの削除: 存在しない場合は失敗する

次の例では、mydataset データセットの mytablesnapshot という名前のテーブル スナップショットを削除します。

DROP SNAPSHOT TABLE mydataset.mytablesnapshot

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

Error: Not found: Table snapshot myproject:mydataset.mytablesnapshot

テーブル スナップショットの削除: 存在しない場合は無視する

次の例では、mydataset データセットの mytablesnapshot という名前のテーブル スナップショットを削除します。

DROP SNAPSHOT TABLE IF EXISTS mydataset.mytablesnapshot

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

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

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

DROP EXTERNAL TABLE ステートメント

DROP EXTERNAL TABLE ステートメントは、外部テーブルを削除します。

DROP EXTERNAL TABLE [IF EXISTS] [[project_name.]dataset_name.]table_name

ここで

  • project_name は、テーブルを含むプロジェクトの名前です。デフォルトでは、この DDL クエリを実行するプロジェクトの名前が設定されます。

  • dataset_name は、テーブルを含むデータセットの名前です。

  • table_name は、削除するテーブルの名前です。

IF EXISTS 句を使用しない場合、外部テーブルが存在しないと、ステートメントはエラーを返します。IF EXISTS 句を使用して、テーブルが存在しない場合は、エラーは返されず、アクションも実行されません。

table_name は存在していても、外部テーブルでない場合は、次のエラーが返されます。

Cannot drop table_name which has type TYPE. An external table was expected.

DROP EXTERNAL ステートメントは BigQuery から外部テーブル定義のみを削除します。外部に保存されているデータは影響を受けません。

次の例では、external_table という名前の外部テーブルをデータセット mydataset から削除します。外部テーブルが存在しない場合、エラーを返します。

DROP EXTERNAL TABLE mydataset.external_table

次の例では、external_table という名前の外部テーブルをデータセット mydataset から削除します。外部テーブルが存在しない場合、エラーは返されません。

DROP EXTERNAL TABLE IF EXISTS mydataset.external_table

DROP VIEW ステートメント

BigQuery でビューを削除するには、DROP VIEW DDL ステートメントを使用します。

DROP VIEW [IF EXISTS] [[project_name.]dataset_name.]view_name

ここで

IF EXISTS: 指定されている場合、指定したビューが存在しなければクエリは成功します。指定されていない場合、指定したビューが存在しなければクエリは失敗します。

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

dataset_name は、削除するビューを含むデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

view_name は、削除するビューの名前です。

ビューの削除

次の例では、mydataset にある myview という名前のビューを削除します。

DROP VIEW mydataset.myview

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

Error: Not found: Table myproject:mydataset.myview

ビューが存在する場合にのみビューを削除

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

DROP VIEW IF EXISTS mydataset.myview

DROP MATERIALIZED VIEW ステートメント

BigQuery で実体化されたビューを削除するには、DROP MATERIALIZED VIEW DDL ステートメントを使用します。

DROP MATERIALIZED VIEW [IF EXISTS] [[project_name.]dataset_name.]mv_name

ここで

IF EXISTS: 指定されている場合、指定したマテリアライズド ビューが存在しなければクエリは成功します。指定されていない場合、指定した実体化されたビューが存在しなければクエリは失敗します。

project_name は、削除する実体化されたビューを含むプロジェクトの名前です。デフォルトでは、この DDL クエリを実行するプロジェクトの名前が設定されます。プロジェクト名にコロンなどの特殊文字が含まれている場合は、バッククォート ` で囲む必要があります(例: `google.com:my_project`)。

dataset_name は、削除する実体化されたビューを含むデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

mv_name は、削除する実体化されたビューの名前です。

実体化されたビューの削除

次の例では、mydataset にある my_mv という名前の実体化されたビューを削除します。

DROP MATERIALIZED VIEW mydataset.my_mv

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

Error: Not found: Table myproject:mydataset.my_mv

別のプロジェクトの実体化されたビューを削除する場合は、`project_id.dataset.materialized_view`project_id に特殊文字が含まれる場合、バッククォートを含む)の形式でプロジェクト、データセット、実体化されたビューを指定する必要があります(例: `myproject.mydataset.my_mv`)。

実体化されたビューが存在する場合にのみ実体化されたビューを削除

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

DROP MATERIALIZED VIEW IF EXISTS mydataset.my_mv

別のプロジェクトの実体化されたビューを削除する場合は、`project_id.dataset.materialized_view`,project_id に特殊文字が含まれる場合、バッククォートを含む)の形式でプロジェクト、データセット、実体化されたビューを指定する必要があります(例: `myproject.mydataset.my_mv`)。

DROP FUNCTION ステートメント

DROP FUNCTION [IF EXISTS] [[project_name.]dataset_name.]function_name

ここで

IF EXISTS: 指定されている場合、指定した関数が存在しなければクエリは成功します。指定されていない場合、指定した関数が存在しなければクエリは失敗します。

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

dataset_name は、削除する関数を含むデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

function_name は、削除する関数の名前です。

次のステートメントの例では、mydataset データセットに含まれる parseJsonAsStruct 関数を削除します。

DROP FUNCTION mydataset.parseJsonAsStruct;

次のステートメントの例では、プロジェクト other_project 内のデータセット sample_dataset から関数 parseJsonAsStruct を削除します。

DROP FUNCTION `other_project`.sample_dataset.parseJsonAsStruct;

DROP TABLE FUNCTION

テーブル関数を削除します。

DROP TABLE FUNCTION [IF EXISTS] [[project_name.]dataset_name.]function_name

ここで

  • IF EXISTS: この名前のテーブル関数が存在しない場合、ステートメントは何もしません。

  • project_name: 削除するテーブル関数を含むプロジェクトの名前。デフォルトでは、この DDL クエリを実行するプロジェクトの名前が設定されます。

  • dataset_name: 削除するテーブル関数を含むデータセットの名前。

  • function_name: 削除するテーブル関数の名前。

次の例では、my_table_function という名前のテーブル関数を削除します。

DROP TABLE FUNCTION mydataset.my_table_function;

DROP PROCEDURE ステートメント

DROP PROCEDURE [IF EXISTS] [[project_name.]dataset_name.]procedure_name

ここで

IF EXISTS: 指定されている場合、指定したプロシージャが存在しなければクエリは成功します。指定されていない場合、指定したプロシージャが存在しなければクエリは失敗します。

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

dataset_name は、削除するプロシージャを含むデータセットの名前です。デフォルトでは、リクエスト内の defaultDataset が使用されます。

procedure_name は、削除するプロシージャの名前です。

次の例のステートメントは、mydataset データセットに含まれるプロシージャ myprocedure を削除します。

DROP PROCEDURE mydataset.myProcedure;

次のステートメントの例では、プロジェクト other_project 内のデータセット sample_dataset からプロシージャ myProcedure を削除します。

DROP PROCEDURE `other-project`.sample_dataset.myprocedure;

DROP ROW ACCESS POLICY ステートメント

行レベルのアクセス ポリシーを削除するには、DDL ステートメントで次のコマンドを使用します。

構文

{DROP ROW ACCESS POLICY | DROP ROW ACCESS POLICY IF EXISTS}
row_access_policy_name ON table_name;
DROP ALL ROW ACCESS POLICIES ON table_name;
要素名 要素の説明

row_access_policy_name

削除する行レベルのアクセス ポリシーの名前。
テーブルの行レベルのアクセス ポリシーには一意の名前が付いています。
My_row_filter

table_name

行レベルのアクセス ポリシー
または削除するポリシーを含むテーブルの名前。
My_table

テーブルからの行レベルのアクセス ポリシーの削除

   DROP ROW ACCESS POLICY My_row_filter ON project.dataset.My_table;

テーブルからのすべての行レベルのアクセス ポリシーの削除

   DROP ALL ROW ACCESS POLICIES ON project.dataset.My_table;