データ型

Cloud Spanner は整数などのシンプルなデータ型と ARRAY や STRUCT などの複雑なデータ型をサポートします。このページでは許容値など各データ型の概要を記載します。

列の値の最大値は 10MiB で、スカラー型と配列型に適用されます。

利用可能なデータ型

型名 有効な列型 有効なキー列型 1 有効な SQL 型 ストレージ サイズ 2
ARRAY ○ × ○ 要素のサイズの合計
BOOL ○ ○ ○ 1 バイト
BYTES ○ ○ ○ バイト数
DATE ○ ○ ○ 4 バイト
FLOAT64 ○ ○ ○ 8 バイト
INT64 ○ ○ ○ 8 バイト
NUMERIC ○ × ○ 格納される値の精度とスケールの両方の関数。値 0 は 1 バイトとして保存されます。その他の値のストレージ サイズは 6 ～ 22 バイトの間で異なります。
STRING ○ ○ ○ UTF-8 エンコーディングのバイト数
STRUCT × × ○ 該当なし
タイムスタンプ ○ ○ ○ 12 バイト

1 主キー、外部キー、セカンダリ インデックス。
2また、各セルには、上記の値に加えて、8 バイトのストレージ オーバーヘッドも含まれます。

データ型の特性

クエリデータを保存する場合、以下のデータ型のプロパティを覚えておくと役に立ちます。

プロパティ 説明 対象
Nullable NULL は有効な値です。 すべてのデータ型。
Orderable ORDER BY 句で使用できます。 以下を除くすべてのデータ型:
  • ARRAY
  • STRUCT
Groupable 通常、
GROUP BY と DISTINCT
に続く式で使用できます。		 以下を除くすべてのデータ型:
  • ARRAY
  • STRUCT
Comparable 同じ型の値をお互いに比較できます。 以下の例外を除くすべてのデータ型: ARRAY の比較はサポートされていません。

STRUCT の値の等価性比較はフィールド順にフィールドごとにサポートされています。フィールド名は無視されます。比較値よりも小さい値と大きい値はサポートされません。

比較をサポートするすべての型が JOIN 条件で使用されます。結合条件の説明については、JOIN データ型をご覧ください。

配列型

名前 説明
ARRAY ARRAY 型ではないゼロ以上の要素の順序付きリスト。

ARRAY は、ARRAY 型ではない値のゼロ以上の要素の順序付きリストです。ARRAY からなる ARRAY は許可されません。ARRAY からなる ARRAY を生成するクエリはエラーを返します。そのような場合は、SELECT AS STRUCT コンストラクトを使用して ARRAY の間に STRUCT を挿入する必要があります。

空の ARRAY と NULL ARRAY は 2 つの異なる値です。ARRAY には NULL 要素を含めることができます。

ARRAY 型の宣言

ARRAY<T>

ARRAY 型は山括弧（< と > ）を使用して宣言されます。ARRAY 要素のデータ型は任意のコンプレックスにすることができますが、ARRAY に直接別の ARRAY を含めることはできません。

例

型の宣言 意味
ARRAY<INT64> 64 ビット整数のシンプルな ARRAY。
ARRAY<STRUCT<INT64, INT64>> STRUCT の ARRAY で、各 ARRAY には 64 ビット整数が 2 つ含まれます。
注: STRUCT 値の ARRAY は SQL 式で作成できますが、列型としてはサポートされていません。
ARRAY<ARRAY<INT64>>
（サポート対象外） 		これは無効な型の宣言です。マルチレベル ARRAY の作成方法を調べるためにこのページにアクセスした場合に備え、ここに記載しておきます。ARRAY には直接 ARRAY を含めることはできません。代わりに次の例をご覧ください。
ARRAY<STRUCT<ARRAY<INT64>>> 64 ビット整数の ARRAY の ARRAY。ARRAY には他の ARRAY を直接含めることができないため、2 つの ARRAY の間に STRUCT が入っていることがわかります。
注: STRUCT 値の ARRAY は SQL 式で作成できますが、列型としてはサポートされていません。

ブール型

名前 説明
BOOL ブール値はキーワード TRUE と FALSE（大文字と小文字の区別なし）で表されます。

ブール値は、小さい値から大きい値に並べ替えられます。

  1. NULL
  2. FALSE
  3. TRUE

バイト型

名前 説明
BYTES 可変長文字バイナリデータ。

STRING と BYTES は入れ替えて使用できない別々の型です。STRING を操作する大半の関数は BYTES に対しても定義されています。BYTES バージョンは Unicode 文字ではなく RAW バイトを操作します。STRING と BYTES の間でキャスティングを行うと、強制的に UTF-8 を使用してバイトがエンコードされます。

日付型

名前 範囲
DATE 0001-01-01～9999-12-31

DATE 型は、タイムゾーンに関係なく、論理カレンダー日を表します。DATE 型の値は特定の 24 時間の期間を表していません。所定の DATE 値は、解釈されるタイムゾーンによって異なる 24 時間の期間を表します。また、夏時間の移行期には 1 日が通常よりも短くなったり、長くなったりする場合があります。絶対的な時刻を表すには、タイムスタンプを使用します。

正規形式
'YYYY-[M]M-[D]D'
  • YYYY: 4 桁の年
  • [M]M: 1 桁または 2 桁の月
  • [D]D: 1 桁または 2 桁の日

数値型

数値型には次の種類があります。

  • INT64
  • NUMERIC
  • FLOAT64

整数型

整数は小数部分を持たない数値です。

名前 範囲
INT64 -9,223,372,036,854,775,808～9,223,372,036,854,775,807

固定小数点型

固定小数点型の値は、固定の精度とスケールを持つ数値です。精度は、数値に含まれる桁数です。スケールは小数点以下の桁数です。

この型は、小数部分を正確に表すことができ、財務計算に適しています。

名前 精度、スケール、範囲
NUMERIC 精度: 38
スケール: 9
最小: -9.9999999999999999999999999999999999999E+29
最大: 9.9999999999999999999999999999999999999E+29

浮動小数点型

浮動小数点の値は小数部分のある近似値です。

名前 説明
FLOAT64 倍精度（近似）数値。

浮動小数点セマンティクス

浮動小数点を扱う場合、NaN と +/-inf という考慮しなければならない特別な非数値があります。

Cloud Spanner REST と RPC API を使用するときには、TypeCode（REST）と TypeCode（RPC）で説明されているように、浮動小数点特殊値を Infinity、-Infinity、NaN としてフォーマットします。リテラル +inf、-inf、nan は、Cloud Spanner REST API と RPC API ではサポートされていません。

算術演算子は、有限出力を出すすべての有限入力値と、少なくとも 1 つの入力が非定形であるすべてのオペレーションに対し、標準 IEEE-754 動作を行えるようにします。

入力が有限値であっても出力が非定形の場合、関数呼び出しと演算子によってオーバーフロー エラーが返されます。入力に非定形値が含まれる場合、出力が非定形になる可能性があります。一般的な関数では NaN または +/-inf が使用されません。しかし、IEEE_DIVIDE のような特定の関数は有限入力に対し非定形値を返すことがあります。このような場合はすべて、数学的関数で明示的に表されます。

数学的関数の例
左の用語 演算子 右の用語 戻り値
任意値 + NaN NaN
1.0 + +inf +inf
1.0 + -inf -inf
-inf + +inf NaN
FLOAT64 の最大値 + FLOAT64 の最大値 オーバーフロー エラー
最小 FLOAT64 値 / 2.0 0.0
1.0 / 0.0 「ゼロ除算」エラー

比較演算子は浮動小数点入力に対し、標準 IEEE-754 動作を行えるようにします。

比較演算子の例
左の用語 演算子 右の用語 戻り値
NaN = 任意値 FALSE
NaN < 任意値 FALSE
任意値 < NaN FALSE
-0.0 = 0.0 TRUE
-0.0 < 0.0 FALSE

浮動小数点の値は小さい値から大きい値の順に並べ替えられます。

  1. NULL
  2. NaN - 並べ替えるときにすべての NaN 値は同じものとみなされます。
  3. -inf
  4. 負の数
  5. 0 または -0 - 並べ替えるときにすべてのゼロ値は同じものとみなされます。
  6. 正の数
  7. +inf

特定の浮動小数点の値は、GROUP BY 句を使ったグループ分けと DISTINCT キーワードでのグループ分けの両方を含め、次のようにグループ分けできます。

  • NULL
  • NaN - グループ分けするときにすべての NaN 値は同じものとみなされます。
  • -inf
  • 0 または -0 - グループ分けするときにすべてのゼロ値は同じものとみなされます。
  • +inf

文字列型

名前 説明
STRING 可変長文字（Unicode）データ。

入力 STRING 値は UTF-8 エンコードに変換する必要があります。また、出力 STRING 値は UTF-8 エンコードに変換されます。CESU-8 や修正 UTF-8 などの代替エンコーディングは有効な UTF-8 として扱われません。

STRING 値を操作するすべての関数と演算子は、バイトではなく Unicode 文字を処理します。たとえば、STRING 型の入力値に適用される SUBSTR や LENGTH のような関数は、バイトではなく文字数をカウントします。

各 Unicode 文字には、コードポイントと呼ばれる数値が割り当てられます。下位のコードポイントは下位の文字に割り当てられます。文字が比較されるとき、コードポイントは他の文字より小さい文字か大きい文字かを判断します。

STRING を操作する大半の関数は BYTES に対しても定義されています。BYTES バージョンは Unicode 文字ではなく RAW バイトを操作します。STRING と BYTES は入れ替えて使用できない別々の型です。いずれの方向にも暗黙的にキャスティングされません。STRING と BYTES との明示的なキャスティングでは UTF-8 エンコーディングとデコーディングが行われます。バイトが有効な UTF-8 ではない場合、BYTES から STRING へのキャスティングではエラーが返されます。

構造体型

SELECT ステートメントとサブクエリで STRUCT を使用する方法の詳細については、クエリ構文のページをご覧ください。

名前 説明
STRUCT 順序付きフィールドのコンテナ。各フィールドはデータ型（必須）とフィールド名（オプション）を持ちます。

STRUCT 型の宣言

STRUCT<T>

STRUCT 型は山括弧（< と >）を使用して宣言されます。STRUCT 要素のデータ型は任意のコンプレックスにすることができます。

注: STRUCT 値は SQL 式で作成できますが、列型としてはサポートされていません。

例

型の宣言 意味
STRUCT<INT64> 単一の名前の付いていない 64 ビット整数フィールドを持つシンプルな STRUCT。
STRUCT<x STRUCT<y INT64, z INT64>> x という名前のネストされた STRUCT を内部に持つ STRUCT。この STRUCT x には y と z という 2 つのフィールドがあり、その両方が 64 ビット整数です。
STRUCT<inner_array ARRAY<INT64>> 64 ビット整数要素を持つ inner_array という名前の ARRAY が含まれる STRUCT。

STRUCT の構成

タプル構文

(expr1, expr2 [, ... ])

出力データ型は、入力式のデータ型と一致する型の匿名フィールドのある匿名 STRUCT データ型です。少なくとも 2 つの指定された式が必要です。式がないと、構文は括弧で括られた式と区別できません。

例

構文 出力データ型 注
(x, x+y) STRUCT<?,?> 列名が使われている場合（文字列が引用されていない場合）、STRUCT フィールドのデータ型は列のデータ型から導出されます。x と y は列であるため、STRUCT フィールドのデータ型は列の型と追加演算子の出力データ型から導出されます。

WHERE 句などのマルチパート キーを使った比較式では、この構文を使用して STRUCT を比較することもできます。

WHERE (Key1,Key2) IN ( (12,34), (56,78) )

型のない STRUCT 構文

STRUCT( expr1 [AS field_name] [, ... ])

重複するフィールド名は許可されます。名前のないフィールドは匿名フィールドとみなされ、名前では参照できません。STRUCT の値は NULL か NULL フィールド値になります。

例

構文 出力データ型
STRUCT(1,2,3) STRUCT<int64,int64,int64>
STRUCT() STRUCT<>
STRUCT('abc') STRUCT<string>
STRUCT(1, t.str_col) STRUCT<int64, str_col string>
STRUCT(1 AS a, 'abc' AS b) STRUCT<a int64, b string>
STRUCT(str_col AS abc) STRUCT<abc string>

型のある STRUCT 構文

STRUCT<[field_name] field_type, ...>( expr1 [, ... ])

型のある構文で、明示的な STRUCT データ型を持つ STRUCT を構成できます。出力データ型は、指定された field_type と正確に同じものになります。2 つの型が同じではない場合、入力式は強制的に field_type となります。その 2 つの型に互換性がない場合はエラーとなります。AS alias は入力式で許可されません。式の数は型のフィールド数と一致しなければなりません。また、式のデータ型はフィールドのデータ型に従うように、強制的に変換できるか、リテラルを強制的に変換できる必要があります。

例

構文 出力データ型
STRUCT<int64>(5) STRUCT<int64>
STRUCT<date>("2011-05-05") STRUCT<date>
STRUCT<x int64, y string>(1, t.str_col) STRUCT<x int64, y string>
STRUCT<int64>(int_col) STRUCT<int64>
STRUCT<x int64>(5 AS x) エラー - 型のある構文では AS を使用できません。

STRUCT の制限付き比較

次の等価演算子を使用して、STRUCT 同士を直接比較できます。

  • 等号（=）
  • 不等号（!= または <>）
  • [NOT] IN

直接等価性比較では、フィールド名を無視して、元の順序で STRUCT のフィールドのペアを比較することにご注意ください。STRUCT 内で同じ名前のフィールドを比較する場合は、個々のフィールドを直接比較できます。

タイムスタンプ型

名前 範囲
TIMESTAMP 0001-01-01 00:00:00～9999-12-31 23:59:59.999999999 UTC.

TIMESTAMP オブジェクトは、タイムゾーンや夏時間などの慣習に関係なく、ナノ秒精度の絶対的な時刻を表します。

  • カレンダーに表示される日付を表すには、DATE オブジェクトを使用します。
正規形式

REST API と RPC API

TypeCode（RPC）と TypeCode（REST）で説明されている JSON 値のエンコードとデコードの規則に従ってください。特に、タイムスタンプ値の末尾はズールー（Zulu）時間（UTC-0）を指定する大文字のリテラル "Z" でなければなりません。

例:

2014-09-27T12:30:00.45Z

タイムスタンプの値はズールー時間で表現する必要があります。また、UTC オフセットを含むことはできません。たとえば、次のタイムスタンプはサポートされません。

-- NOT SUPPORTED! TIMESTAMPS CANNOT INCLUDE A UTC OFFSET WHEN USED WITH THE REST AND RPC APIS
2014-09-27 12:30:00.45-8:00

クライアント ライブラリ

言語固有のタイムスタンプ形式を使用します。

SQL クエリ

YYYY-[M]M-[D]D[( |T)[H]H:[M]M:[S]S[.DDDDDDDDD]][time zone]
  • YYYY: 4 桁の年
  • [M]M: 1 桁または 2 桁の月
  • [D]D: 1 桁または 2 桁の日
  • ( |T): スペースまたは区切り文字「T」
  • [H]H: 1 桁または 2 桁の時（有効な値は 00～23）
  • [M]M: 1 桁または 2 桁の分（有効な値は 00～59）
  • [S]S: 1 桁または 2 桁の秒（有効な値は 00～59）
  • [.DDDDDDDDD]: 小数 9 桁まで（ナノ秒の精度）
  • [time zone]: タイムゾーンを表す文字列。タイムゾーンが明示的に指定されていない場合、デフォルトのタイムゾーンである America/Los_Angeles が使用されます。詳しくは、タイムゾーンのセクションをご覧ください。

タイムゾーン

タイムゾーンは、タイムスタンプの構文を解析したり、タイムスタンプの形式を設定して表示したりするときに使用されます。タイムスタンプの値自体には、特定のタイムゾーンは格納されず、タイムゾーン オフセットを適用するときに変更されることもありません。

タイムゾーンは、次の 2 つの正規形式のいずれかで、文字列によって示されます。

  • 協定世界時（UTC）からのオフセット、または UTC を表す文字 Z
  • tz database からのタイムゾーン名

協定世界時（UTC）からのオフセット

(+|-)H[H][:M[M]]
Z

例

-08:00
-8:15
+3:00
+07:30
-7
Z

この形式を使用する場合、タイムゾーンと残りのタイムスタンプの間にスペースは使用できません。

2014-09-27 12:30:00.45-8:00
2014-09-27T12:30:00.45Z

タイムゾーン名

continent/[region/]city

タイムゾーン名は tz database から取得されます。あまり包括的ではありませんが簡潔な資料としては、Wikipedia の tz database のタイムゾーン一覧（英語）をご覧ください。

例

America/Los_Angeles
America/Argentina/Buenos_Aires

タイムゾーン名を使用する場合、名前と、残りのタイムスタンプの間にスペースが 1 つ必要です。

2014-09-27 12:30:00.45 America/Los_Angeles

タイムゾーン名によって 1 年の特定の期間に同じ時刻が偶然レポートされたとしても、すべてのタイムゾーン名が交換可能なわけではありません。たとえば、夏時間中に America/Los_Angeles が UTC-7:00 と同じ時刻をレポートしたとしても、夏時間以外では同じ時刻は UTC-8:00 としてレポートされます。

タイムゾーンが指定されていない場合、デフォルトのタイムゾーンが使用されます。

うるう秒

タイムスタンプは 1970-01-01 00:00:00 UTC からの単純なオフセットであり、1 分が正確に 60 秒であることを前提にしています。保存されたタイムスタンプには、うるう秒は表示されません。

うるう秒を表すために秒フィールドで「:60」を使用する値が入力値に含まれている場合、タイムスタンプ値に変換されると、そのうるう秒は表示されなくなります。代わりに、その値は次の分の秒フィールドで「:00」を含むタイムスタンプとして解釈されます。

うるう秒はタイムスタンプの計算に影響を及ぼしません。すべてのタイムスタンプの計算は、うるう秒が反映されない Unix スタイルのタイムスタンプを使用して行われます。うるう秒は、実際の世界の時刻を測定する関数を使用する場合にのみ認識されます。このような関数では、うるう秒が発生すると、タイムスタンプの秒をスキップしたり、繰り返したりできます。