データ型

• データ型
  • 利用可能なデータ型
  • データ型の特性
  • 数値型
    • 整数型
    • 浮動小数点型
      • 浮動小数点セマンティクス
        • 数学的関数の例
        • 比較演算子の例
  • ブール型
  • 文字列型
  • バイト型
  • 日付型
    • 正規形式
  • タイムスタンプ型
    • 正規形式
    • タイムゾーン
      • 協定世界時（UTC）からのオフセット
        • オフセットの形式
        • 例
      • タイムゾーン名
        • フォーマット
        • 例
      • うるう秒
  • 配列型
    • ARRAY 型の宣言
      • フォーマット
      • 例
  • 構造体型
    • STRUCT 型の宣言
      • フォーマット
      • 例
    • STRUCT の構成
      • タプル構文
        • フォーマット
        • 例
      • 型のない STRUCT 構文
        • フォーマット
        • 例
      • 型のある STRUCT 構文
        • フォーマット
        • 例
    • STRUCT の制限付き比較

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

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

利用可能なデータ型

型名	有効な列型	有効なキー列型	有効な SQL 型	ストレージ サイズ ^1
ARRAY	○	×	○	要素のサイズの合計
BOOL	○	○	○	1 バイト
BYTES	○	○	○	バイト数
DATE	○	○	○	4 バイト
FLOAT64	○	○	○	8 バイト
INT64	○	○	○	8 バイト
STRING	○	○	○	UTF-8 エンコーディングのバイト数
STRUCT	×	×	○	該当なし
TIMESTAMP	○	○	○	12 バイト

¹ 各セルには、上記の値に加えて、8 バイトのストレージ オーバーヘッドも含まれます。

データ型の特性

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

特性	説明	対象
Nullable	NULL は有効な値です。	すべてのデータ型。

Orderable ORDER BY 句で使用できます。以下を除くすべてのデータ型:

• ARRAY
• STRUCT

Groupable 一般に
GROUP BY、DISTINCT、PARTITION BY に続く式で使用できます。
ただし、PARTITION BY 式に
浮動小数点型 FLOAT と DOUBLE を使用することはできません。


以下を除くすべてのデータ型:

• ARRAY
• STRUCT

Comparable 同じ型の値をお互いに比較できます。次の例外を除く、すべてのデータ型:

ARRAY 比較はサポートされていません。

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

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

数値型

数値型には整数型と浮動小数点型があります。

整数型

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

名前	ストレージ サイズ	範囲
INT64	8 バイト	-9,223,372,036,854,775,808～9,223,372,036,854,775,807

浮動小数点型

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

名前	ストレージ サイズ	説明
FLOAT64	8 バイト	倍精度（近似）10 進値。

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

浮動小数点を扱う場合、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 のような特定の関数は有限入力に対し非定形値を返すことがあります。このような場合はすべて、数学的関数で明示的に表されます。

数学的関数の例

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

左の用語	演算子	右の用語	戻り値
任意値	+	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

ブール型

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

文字列型

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

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

STRING 値を操作するすべての関数と演算子は、バイトではなく Unicode 文字を処理します。たとえば、STRING 型の入力値に適用される SUBSTR や LENGTH のような関数は、バイトではなく Unicode 文字をカウントします。比較演算子は Unicode 文字に対して定義されています。小なりや ORDER BY の比較演算子は文字ごとに比較され、Unicode コードポイントの低い方が下位の文字とみなされます。

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

バイト型

名前	説明
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 桁の日

タイムスタンプ型

名前	説明	範囲
TIMESTAMP	ナノ秒の精度で、時間単位で絶対的な時刻を表します。	0001-01-01 00:00:00～9999-12-31 23:59:59.999999999 UTC.

タイムスタンプは、タイムゾーンや夏時間などの慣習に関係なく、絶対的な時刻を表します。

TIMESTAMP では、ナノ秒の精度が得られます。

正規形式

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

タイムゾーン名

タイムゾーン名は tz database から取得されます。すべてを網羅しているわけではありませんが、簡単な参考として、Wikipedia の tz database のタイムゾーン一覧が役立ちます。

フォーマット

continent/[region/]city

例

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 スタイルのタイムスタンプを使用して行われます。うるう秒は、実際の世界の時刻を測定する関数を使用する場合にのみ認識されます。このような関数では、うるう秒が発生すると、タイムスタンプの秒をスキップしたり、繰り返したりできます。

配列型

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

ARRAY は、ARRAY 型ではない値のゼロ以上の要素の順序付きリストです。ARRAY からなる ARRAY は許可されません。ARRAY からなる ARRAY を生成するクエリはエラーを返します。その代わり、ARRAY を SELECT AS STRUCT 構成概念を使って配列間に挿入しなければなりません。

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

ARRAY 型の宣言

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

フォーマット

ARRAY<T>

例

型の宣言	意味
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 式で作成できますが、列型としてはサポートされていません。

構造体型

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

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

STRUCT 型の宣言

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

フォーマット

STRUCT<T>

注: 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 の同じ名前が付いているフィールドを比較する場合は、個々のフィールドを直接比較できます。