データ定義言語

次の操作には Cloud Spanner のデータ定義言語(DDL)を使います。

  • データベースを作成します。
  • データベース内でテーブルを作成、変更、または削除します。
  • テーブルの列を追加、変更、または削除します。
  • データベースのインデックスを作成または削除します。

DDL 構文

statement:
    { create_database | create_table | create_index | alter_table | drop_table | drop_index }

create_database:
    CREATE DATABASE database_id

create_table:
    CREATE TABLE table_name (
    [column_def, ...] )
    primary_key [, cluster]

column_def:
    column_name {scalar_type | array_type} [NOT NULL] [options_def]

primary_key:
    PRIMARY KEY ( [key_part, ...] )

key_part:
    column_name [{ ASC | DESC }]

cluster:
    INTERLEAVE IN PARENT table_name [ ON DELETE { CASCADE | NO ACTION } ]

scalar_type:
    { BOOL | INT64 | FLOAT64 | STRING( length ) | BYTES( length ) | DATE | TIMESTAMP }

length:
    { int64_value | MAX }

array_type:
    ARRAY< scalar_type >

options_def:
  OPTIONS (allow_commit_timestamp = { true | null })

create_index:
    CREATE [UNIQUE] [NULL_FILTERED] INDEX index_name
    ON table_name ( key_part [, ...] ) [ storing_clause ] [ , interleave_clause ]

storing_clause:
    STORING ( column_name [, ...] )

interleave_clause:
    INTERLEAVE IN table_name

alter_table:
    ALTER TABLE table_name { table_alteration | table_column_alteration }

table_alteration:
{ ADD COLUMN column_def | DROP COLUMN column_name |
      SET ON DELETE { CASCADE | NO ACTION } }

table_column_alteration:
    ALTER COLUMN column_name { { scalar_type | array_type } [NOT NULL] | SET options_def }

drop_table:
    DROP TABLE table_name

drop_index:
    DROP INDEX index_name

int64_value:
    { decimal_value | hex_value }

decimal_value:
    [-]0—9+

hex_value:
    [-]0x{0—9|a—f|A—F}+

database_id:
    {a—z}[{a—z|0—9|_|-}+]{a—z|0—9}

table_name, column_name, index_name:
    {a—z|A—Z}[{a—z|A—Z|0—9|_}+]

表記:

  • 角括弧「[ ]」はオプションの句です。
  • 丸括弧「( )」はリテラルの括弧を表します。
  • 縦線「|」は論理 OR を表します。
  • 波括弧「{ }」ではオプションのセットを囲みます。
  • 省略記号に先立つカンマは、前の項目をカンマで区切ったリストに繰り返すことができることを示しています。item [, ...] は 1 つ以上の項目を示し、[item, ...] は 0 個以上の項目を示します。
  • カンマ「,」はリテラルなカンマを示します。
  • 山括弧「<>」はリテラルな山括弧を表します。
  • ダッシュ「—」は、2 つの値の間の範囲を示します。
  • プラス記号「+」は、前の項目を繰り返すことができることを表します。

予約済みキーワード

型名など、一部の単語は Cloud Spanner の DDL で予約されています。予約済みキーワードをスキーマの識別子として使用する場合、それをバッククォート(`)で囲んでください。Cloud Spanner での予約済みキーワードの一覧については、字句構造と構文をご覧ください。

例:

CREATE TABLE MyTable (
  RowId INT64 NOT NULL,
  `Int64` INT64
) PRIMARY KEY (RowId)

データベース ステートメント

データベースの作成

Cloud Spanner データベースを作成するときには、データベースの ID を定義する CREATE DATABASE ステートメントを指定する必要があります。

CREATE DATABASE database_id

database_id:
    {a—z}[{a—z|0—9|_|-}+]{a—z|0—9}

データベース ID:

  • 先頭は小文字にしてください。
  • 小文字、数字、アンダースコア、ハイフンは使用できますが、大文字は使用できません。
  • 末尾をアンダースコアまたはハイフンにすることはできません。
  • ハイフンを含む文字列または予約語は、バッククォート(`)で囲む必要があります。
  • 2~30 文字にする必要があります。
  • 作成後に変更することはできません。

データ型

スカラー

DDL でスカラー型を使用する構文は次のとおりです。

{ BOOL | INT64 | FLOAT64 | STRING( length ) | BYTES( length ) | DATE | TIMESTAMP }

length:
    { int64_value | MAX }

int64_value:
    { decimal_value | hex_value }

decimal_value:
    [-]0—9+

hex_value:
    [-]0x{0—9|a—f|A—F}+

int64_values:

  • -9,223,372,036,854,775,808 から 9,223,372,036,854,775,807 までの範囲になります。
  • 16 進数で、「0x」(大文字と小文字を区別)を先頭に付けることができます。

文字列

STRING は、可変長の Unicode 文字列です。その値は有効な Unicode 文字列でなければなりません。長さが必要で、フィールドに保管できる Unicode 文字の最大数(バイト数ではない)を表します。

注:

  • 列への書き込みは検証され、新しい値が有効な Unicode 文字列でない場合と、指定された長さを超えている場合には書き込みが拒否されます。

  • length は範囲 [1, 2621440](2.5 MB)で整数に設定できます。

  • 長さが予測できないフィールドや制約が不要なフィールドでは、length を値 MAX に設定すると便利です。この値は、検証目的の場合は 2621440 に該当します。

    保存される文字列の実際の長さだけがストレージ コストに影響します。MAX を使用しても、使用されるストレージ容量は増加しません。

  • Cloud Spanner ではサーバーで受信したときに Unicode 文字列を UTF-8 エンコードに変換する必要があります。

  • 照合は Unicode 文字の数値(厳密には、コードポイント文字が組み合わされるため、Unicode 文字の数値とは微妙に異なります)を基準にして行われます。ASCII 文字列の場合、従来の並べ替え順となります。

  • テーブルを作成した後で列の長さを短くできますが、その場合、Cloud Spanner で既存のデータが長さの制約に対応していることを確認しなければなりません。

バイト

BYTES は可変長のバイナリ文字列です。長さが必要で、フィールドに保管できる最大のバイト数を表します。

注:

  • 列への書き込みは検証され、新しい値が指定された長さを超えている場合には書き込みが拒否されます。

  • length は範囲 [1, 10485760](10 MB)の整数または便利な値である MAX に設定できます。この値は、検証目的の場合は 10485760 に該当します。

    保存される実際のバイト数だけがストレージ コストに影響します。MAX を使用しても、使用されるストレージ容量は増加しません。

  • テーブルを作成した後で列の長さを短くできますが、その場合、Cloud Spanner で既存のデータが長さの制約に対応していることを確認しなければなりません。

日付

  • タイムゾーンに依存しない日付。
  • 有効な日付の範囲は [0001-01-01, 9999-12-31] です。値がこの範囲外の場合、データ列への書き込みは拒否されます。
  • 詳細と正規形式については、データ型をご覧ください。

タイムスタンプ

  • ナノ秒精度のタイムスタンプ。
  • タイムゾーンに依存しません。範囲は [0001-01-01 00:00:00~10000-01-01 00:00:00] です。
  • 詳細と正規形式については、データ型をご覧ください。

配列

DDL で ARRAY データ型を使用する構文は次のようになります。

ARRAY< scalar_type >

Cloud Spanner はスカラーの配列をサポートします。配列の主な目的は、スペースを効率的に使用する方法で値のコレクションを保存することです。配列は個々の要素にアクセスできるように設計されていません。1 つの要素を読み書きするためには、配列全体を読み書きする必要があります。

アプリケーションがベクトルや繰り返しフィールドのようなデータ構造を使用する場合、Cloud Spanner 配列でその状態を容易に持続することができます。

ARRAY 型の複数の列を使用する Singers の代替定義は次のとおりです。

CREATE TABLE Singers (
  SingerId INT64,
  FeaturedSingerIds ARRAY<INT64>,
  SongNames ARRAY<STRING(MAX)>,
) PRIMARY KEY (SingerId) ...;

注:

  • サブタイプ ARRAY を持つ配列(ネストされた配列)はサポートされていません。
  • スカラー値のような配列は、合計 10 MiB 以下にする必要があります。
  • 配列はキー列として使用できません。

テーブル ステートメント

テーブルの作成

テーブルを定義するには、CREATE TABLE ステートメントを使用します。

CREATE TABLE table_name(
[column_def, ...] )
primary_key [, cluster]

column_def:
    column_name {scalar_type | array_type} [NOT NULL] [options_def]

primary_key:
    PRIMARY KEY ( [key_part, ...] )

key_part:
    column_name [{ ASC | DESC }]

cluster:
    INTERLEAVE IN PARENT table_name [ ON DELETE { CASCADE | NO ACTION } ]

table_name and column_name:
    {a—z|A—Z}[{a—z|A—Z|0—9|_}+]

options_def:
  OPTIONS (allow_commit_timestamp = { true | null })

注:

  • 主キー列に DESC 注釈を追加すると、昇順(デフォルト)から降順にデータの物理的なレイアウトが変更されます。

  • INTERLEAVE IN PARENT は子から親へのテーブル関係を定義します。結果として、親と子の行が物理的にインターリーブされます。名前とデータ型の両方において、親の主キー列は子の主キー列の接頭辞と位置的に一致しなければなりません。子テーブルに行を追加するときに、対応する親の行が存在しない場合は失敗します。親の行は、すでにデータベースに存在するものにするか、または子テーブルに行を追加する同じトランザクションで先行して追加できます。

  • ON DELETE 句は、ミューテーションで親の行の削除を試行するときの ChildTable 内の行の動作を定義します。この句は省略可能です。次のオプションを使用できます。

    • CASCADE: 子行が削除されます。
    • NO ACTION: 子行は削除されません。親を削除すると子行が残る場合、親子の参照整合性が失われ、書き込みに失敗します。

    ON DELETE 句は省略可能ですが、省略するとデフォルトの ON DELETE NO ACTION が使用されます。

  • NOT NULL アノテーションは、新しい行を挿入するすべてのミューテーションで列が必要であることを示します。既存のテーブルには NOT NULL 列を追加できません(ただし、その対処法として、NULL 値を指定できる列を追加し、すべての行に書き込みを実行してその列を埋めると、その列の NOT NULL アノテーションでスキーマを更新できます)。

  • テーブルと列の名前:

    • 1~128 文字にする必要があります。
    • 先頭は大文字または小文字にしてください。
    • 大文字、小文字、数字、アンダースコアは使用できますが、ハイフンは使用できません。
    • 大文字と小文字は区別されません。たとえば、同じデータベース内で mytableMyTable という名前のテーブルは作成できません。また、同じテーブル内に mycolumnMyColumn という名前の列は作成できません。
  • allow_commit_timestamp オプションを使用すると、挿入オペレーションと更新オペレーションで、Cloud Spanner がトランザクションの Commit タイムスタンプを列に書き込むようにリクエストできます。詳しくは、commit タイムスタンプをご覧ください。

テーブルの変更

テーブルの定義を変更するには、ALTER TABLE ステートメントを使用します。

ALTER TABLE table_name { table_alteration | table_column_alteration }

table_alteration:
{ ADD COLUMN column_def | DROP COLUMN column_name |
      SET ON DELETE { CASCADE | NO ACTION } }

table_column_alteration:
  ALTER COLUMN column_name { { scalar_type | array_type } [NOT NULL] | SET options_def }

options_def:
  OPTIONS (allow_commit_timestamp = { true | null })

(allow_commit_timestamp=true) オプションを使用すると、挿入オペレーションと更新オペレーションで、Cloud Spanner がトランザクションの commit タイムスタンプを列に書き込むようにリクエストできます。詳しくは、commit タイムスタンプをご覧ください。

テーブルの削除

テーブルを削除するには、DROP TABLE ステートメントを使用します。DROP TABLE は元に戻せません。

DROP TABLE table_name

INDEX ステートメント

インデックスの作成

セカンダリ インデックスを定義するには、CREATE INDEX ステートメントを使用します。

構文

CREATE [UNIQUE] [NULL_FILTERED] INDEX index_name
ON table_name ( key_part [, ...] ) [ storing_clause ] [ , interleave_clause ]

storing_clause:
    STORING ( column_name [, ...] )

interleave_clause:
    INTERLEAVE IN table_name

index_name:
    {a—z|A—Z}[{a—z|A—Z|0—9|_}+]

注:

  • UNIQUE は、このセカンダリ インデックスがインデックスされるデータを UNIQUE 制約することを表します。この UNIQUE 制約により、重複したインデックス キーとなるトランザクションが拒否されます。詳細については、独自のインデックスをご覧ください。

  • NULL_FILTERED は、このセカンダリ インデックスが NULL 値をインデックスしないことを表します。詳細については、NULL のインデックスをご覧ください。

  • INTERLEAVE IN はインデックスをインターリーブするテーブルを定義します。T がインデックスをインターリーブするテーブルの場合、以下を守らなければなりません。

    • T はインデックスされるテーブルの親でなければなりません。
    • T のプライマリキーはインデックスのキー接頭辞でなければなりません。

    いつインターリーブされたインデックスを作成すべきでしょうか。インデックス オペレーションに使用したいインデックス キーがテーブルのキーと一致し、そのテーブルの行が対応するインデックスされた行とデータの局所関連性を持つ場合、そのテーブルにインデックスをインターリーブする必要がある可能性があります。

    たとえば、インデックスからある歌手の歌をフェッチするときにその歌手に関する情報を頻繁にフェッチする場合、Singers の特定の行に対する Songs のすべての行をインデックスする必要があるとすると、インデックス キーには SingerIdSongName が含まれ、インデックスは Singers でインターリーブするための最適な候補となります。セカンダリ インデックスの作成に記載されている SongsBySingerSongName の定義は、こうしたインターリーブされるインデックスを作成する例です。

    インターリーブされたテーブルのように、インターリーブされたインデックスのエントリはその親テーブルの対応する行と一緒に保存されます。詳細はデータベースの分割をご覧ください。

  • DESC は、対応するインデックス列の降順のスキャンを定義します。DESC の印が付いたインデックス列を使ってテーブルをスキャンすると、スキャンされた行はそのインデックス列に対し降順で表示されます。並べ替えの順序を指定しない場合、昇順(ASC)がデフォルトとなります。

  • STORING は、テーブルにある 1 つ以上のセカンダリ インデックスにテーブルのデータを複製するためのメカニズムを提供します。インデックス内の要求されたエントリを探した後にメインテーブルからデータを取得する必要がなくなるため、追加のストレージは発生しますが、このメカニズムによりセカンダリ インデックスを使ってデータを探すときの読み込みレイテンシを減らすことができます。例については、STORING 句をご覧ください。

  • インデックス名:

    • 1~128 文字にする必要があります。
    • 先頭は大文字または小文字にしてください。
    • 大文字、小文字、数字、アンダースコアは使用できますが、ハイフンは使用できません。
    • 大文字と小文字は区別されません。たとえば、同じデータベース内に myindexMyIndex という名前のインデックスは作成できません。

インデックスの削除

セカンダリ インデックスを削除するには、DROP INDEX ステートメントを使用します。

DROP INDEX index_name
このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

Cloud Spanner のドキュメント