このページでは、Spanner を使用して JSON を操作する方法について説明します。
JSON データ型は、JSON(JavaScript Object Notation)データを保持するために使用される半構造化データ型です。JSON 形式の仕様については、RFC 7159 をご覧ください。
JSON は、スパースなデータ、大まかに定義されているデータ、構造が変化しているデータのリレーショナル スキーマを補足するのに便利です。ただし、クエリ オプティマイザーはリレーショナル モデルに依存して、大規模なフィルタリング、結合、集計、並べ替えを効率的に行います。JSON を介したクエリでは、組み込みの最適化が少なくなり、パフォーマンスを検査および調整するためのアフォーダンスが少なくなります。
仕様
Spanner の JSON 型は、入力 JSON ドキュメントの正規化表現を格納します。
- JSON は最大で 80 レベルまでネストできます。
- 空白文字は保持されません。
- コメントはサポートされません。コメント付きのトランザクションやクエリは失敗します。
- JSON オブジェクトのメンバーは辞書順に並べ替えられます。
- JSON 配列要素の順序は保持されます。
- 1 つの JSON オブジェクトに重複するキーがある場合、最初のキーだけが保持されます。
- プリミティブ型(文字列、ブール値、数値、null)は、その型と値が保持されます。
- 文字列型の値はそのまま保持されます。
- 数値型の値は保持されますが、正規化プロセスの結果としてテキスト表現が変更される場合があります。たとえば、入力値 10,000 は、正規化され 1e+4 で表現される場合があります。数値の保存セマンティクスは次のとおりです。
- [INT64_MIN, INT64_MAX] の範囲の符号付き整数は保持されます。
- [0, UINT64_MAX] の範囲の符号なし整数は保持されます。
- 精度を失うことなく文字列、double、文字列へのラウンドトリップが可能な double 値は保持されます。double 値をこのような方法でラウンドトリップできない場合、トランザクションまたはクエリは失敗します。
- たとえば、
SELECT JSON '2.2412421353246235436'
は失敗します。 - 実践的な回避策として、
JSON '2.2412421353246237'
を返すPARSE_JSON('2.2412421353246235436', wide_number_mode=>'round')
を使用できます。
- たとえば、
TO_JSON()
、JSON_OBJECT()
、JSON_ARRAY()
関数を使用して、SQL で JSON ドキュメントを作成します。これらの関数により、必要な引用符とエスケープ文字が実装されます。
正規化されたドキュメントの最大許容サイズは 10 MB です。
null 可能性
JSON の null
値は SQL 非 NULL として扱われます。
次に例を示します。
SELECT (JSON '{"a":null}').a IS NULL; -- Returns FALSE
SELECT (JSON '{"a":null}').b IS NULL; -- Returns TRUE
SELECT JSON_QUERY(JSON '{"a":null}', "$.a"); -- Returns a JSON 'null'
SELECT JSON_QUERY(JSON '{"a":null}', "$.b"); -- Returns a SQL NULL
エンコード
JSON ドキュメントは UTF-8 でエンコードする必要があります。他の形式でエンコードされた JSON ドキュメントを含むトランザクションやクエリはエラーを返します。
JSON 列があるテーブルを作成する
テーブルの作成時に JSON 列をテーブルに追加できます。JSON 型の値は null 値にできます。
CREATE TABLE Venues (
VenueId INT64 NOT NULL,
VenueName STRING(1024),
VenueAddress STRING(1024),
VenueFeatures JSON,
DateOpened DATE,
) PRIMARY KEY(VenueId);
既存のテーブルに JSON 列を追加する、あるいは JSON 列を削除する
既存のテーブルに JSON 列を追加することも、削除することもできます。
ALTER TABLE Venues ADD COLUMN VenueDetails JSON;
ALTER TABLE Venues DROP COLUMN VenueDetails;
次のサンプルで示すのは、Spanner クライアント ライブラリを使用して、VenueDetails
という JSON
列を Venues
テーブルに追加する方法です。
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
JSON データを変更する
次のサンプルで示すのは、Spanner クライアント ライブラリを使用して JSON
データを更新する方法です。
C++
Spanner 用のクライアント ライブラリをインストールして使用する方法については、Spanner クライアント ライブラリをご覧ください。
Spanner に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
C#
Spanner 用のクライアント ライブラリをインストールして使用する方法については、Spanner クライアント ライブラリをご覧ください。
Spanner に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Go
Spanner 用のクライアント ライブラリをインストールして使用する方法については、Spanner クライアント ライブラリをご覧ください。
Spanner に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Java
Spanner 用のクライアント ライブラリをインストールして使用する方法については、Spanner クライアント ライブラリをご覧ください。
Spanner に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
Spanner 用のクライアント ライブラリをインストールして使用する方法については、Spanner クライアント ライブラリをご覧ください。
Spanner に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
PHP
Spanner 用のクライアント ライブラリをインストールして使用する方法については、Spanner クライアント ライブラリをご覧ください。
Spanner に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Python
Spanner 用のクライアント ライブラリをインストールして使用する方法については、Spanner クライアント ライブラリをご覧ください。
Spanner に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Ruby
Spanner 用のクライアント ライブラリをインストールして使用する方法については、Spanner クライアント ライブラリをご覧ください。
Spanner に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
JSON データをインデックスに登録する
JSON データでセカンダリ インデックスと検索インデックスを使用すると、JSON データのクエリを高速化できます。Spanner では、セカンダリ インデックスのキーとして JSON 型の列を使用することはできません。
セカンダリ インデックスを使用する
セカンダリ インデックスは、JSON ドキュメント内のスカラー値に対してフィルタする場合に便利です。JSON でセカンダリ インデックスを使用するには、関連するスカラーデータを抽出し適切な SQL 型に変換する生成列を作成します。こうすることで、この生成された列にセカンダリ インデックスを作成できます。このインデックスにより、生成された列に対して実行される対象クエリが高速化されます。
次の例では、1,000 を超える収容人数の会場を見つけるためにデータベースが使用する VenuesByCapacity
インデックスを作成します。Spanner は、すべての行を確認するのではなくインデックスを使用して関連する行を見つけるため、特に大規模なテーブルでクエリのパフォーマンスが向上します。
ALTER TABLE Venues
ADD COLUMN VenueCapacity INT64 AS (INT64(VenueDetails.capacity));
CREATE INDEX VenuesByCapacity ON Venue (VenueCapacity);
SELECT VenueName
FROM Venues
WHERE VenueCapacity > 1000;
検索インデックスを使用する
検索インデックスは、動的または多様な JSON ドキュメントに対してクエリを実行する場合に便利です。セカンダリ インデックスとは異なり、JSON 列に保存されている任意の JSON ドキュメントに対して検索インデックスを作成できます。検索インデックスは、JSON ドキュメント間の相違、異なる行での相違、時間の経過に伴う変化に自動的に適応します。
次の例では、サイズや営業スケジュールといった特定の詳細情報を持つ会場をデータベースが見つけるために使用する VenuesByVenueDetails
検索インデックスを作成します。Spanner は、すべての行を確認するのではなくインデックスを使用して関連する行を見つけるため、特に大規模なテーブルでクエリのパフォーマンスが向上します。
ALTER TABLE Venues
ADD COLUMN VenueDetails_Tokens TOKENLIST AS (TOKENIZE_JSON(VenueDetails)) HIDDEN;
CREATE SEARCH INDEX VenuesByVenueDetails
ON Venue (VenueDetails_Tokens);
SELECT VenueName
FROM Venues
WHERE JSON_CONTAINS(VenueDetails, JSON '{"labels": ["large"], "open": {"Friday": true}}');
詳細については、JSON 検索インデックスをご覧ください。
JSON データをクエリする
以下のサンプルは、Spanner クライアント ライブラリを使用して JSON
データをクエリする方法を示したものです。
C++
Spanner 用のクライアント ライブラリをインストールして使用する方法については、Spanner クライアント ライブラリをご覧ください。
Spanner に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
C#
Spanner 用のクライアント ライブラリをインストールして使用する方法については、Spanner クライアント ライブラリをご覧ください。
Spanner に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Go
Spanner 用のクライアント ライブラリをインストールして使用する方法については、Spanner クライアント ライブラリをご覧ください。
Spanner に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Java
Spanner 用のクライアント ライブラリをインストールして使用する方法については、Spanner クライアント ライブラリをご覧ください。
Spanner に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
Spanner 用のクライアント ライブラリをインストールして使用する方法については、Spanner クライアント ライブラリをご覧ください。
Spanner に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
PHP
Spanner 用のクライアント ライブラリをインストールして使用する方法については、Spanner クライアント ライブラリをご覧ください。
Spanner に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Python
Spanner 用のクライアント ライブラリをインストールして使用する方法については、Spanner クライアント ライブラリをご覧ください。
Spanner に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Ruby
Spanner 用のクライアント ライブラリをインストールして使用する方法については、Spanner クライアント ライブラリをご覧ください。
Spanner に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
制限事項
ORDER BY
句で JSON 列を使用することはできません。- JSON 型の列を主キーとして、または副インデックスのキーとして使用することはできません。詳細については、JSON データをインデックスに登録するをご覧ください。