JSON_TABLE 表関数

JSON_TABLE 表関数は結果表を SQL/JSON パス式の評価から戻します。行 SQL/JSON パス式の結果シーケンス内の各項目は、結果表の 1 つ以上の行を表しています。

json-table-regular-column-definition

json-table-formatted-column-definition

data-type1

data-type2

スキーマは SYSIBM です。関数名を修飾名で指定することはできません。

JSON 式

以下のデータ・タイプを除く、組み込みストリング・データ・タイプである値を戻す式 (SQLSTATE 42815)。

GRAPHIC
VARGRAPHIC
DBCLOB
BINARY
CHAR FOR BIT DATA
VARCHAR FOR BIT DATA
上記のデータ・タイプに基づくユーザー定義タイプ

文字値が戻される場合は、正しい形式の JSON データが含まれている必要があります (SQLSTATE 22032)。バイナリー・データ・タイプが戻される場合は、明示的または暗黙的な FORMAT 節に従って解釈されます。

FORMAT JSON

JSON-expression は JSON データとして形式設定されています。

JSON-expression が文字ストリング・データ・タイプであれば、JSON データとして扱われます。

バイナリー・ストリング・データ・タイプの JSON-expression は、UTF-8 データとして解釈されます。

FORMAT BSON

JSON-expression が JSON データの BSON 表現として形式設定されていることを示します (SQLSTATE 22032)。 JSON-expression は、バイナリー・ストリング・データ・タイプでなければなりません (SQLSTATE 42815)。

'strict $'

指定されたパス式を使用してコンテキスト項目の開始点から現在の JSON 文書をナビゲートできない場合に、エラーを報告することを指定します。エラーは、現在の ON ERROR 節に従って処理されます。

COLUMNS

結果表の出力列を指定します。列名、データ・タイプ、各行の列値の計算方法などを指定します。結果列の長さの合計は 64 KB を超えてはなりません。

json-table-regular-column-definition

結果表の出力列を 1 つ指定します。列名、データ・タイプ、行のシーケンス項目から値を抽出するための SQL/JSON パス式などを指定します。これは、JSON_VALUE スカラー関数の出力と同等です。

column-name

結果表の列の名前を指定します。名前を修飾したり、結果表の複数の列に対して同じ名前を使用することはできません (SQLSTATE 42711)。

data-type1

列のデータ・タイプを指定します。

組み込みデータ・タイプの説明については、 CREATE TABLE ステートメントを参照してください。

PATH 列パス式定数 (column-path-expression-constant)

SQL/JSON パスとして解釈される文字ストリング定数を指定します。 column-path-expression-constant は SQL/JSON パス式を指定しますが、これは sql-json-path-expression 内の SQL/JSON パス式の評価の結果である項目に関連して列値を決定します。

SQL/JSON パス式の内容について詳しくは、 sql-json-path-expressionを参照してください。

外部で提供されたコンテキスト項目として sql-json-path-expression の処理の結果による項目がある場合、column-path-expression-constant が評価され、出力シーケンスが戻されます。列値は、以下のようにこの出力シーケンスに基づいて決定されます。

空シーケンスが戻された場合、列の値は ON EMPTY 節から取得されます。
ERROR ON EMPTY が指定されると、エラーが戻されます。
空シーケンスが戻され、ON EMPTY 節が指定されていない場合、列には NULL 値が割り当てられます。
単一エレメントのシーケンスが戻され、エレメントのタイプが JSON 配列でも JSON オブジェクトでもない場合、その値は列に指定されたデータ・タイプに変換されます。
単一エレメントのシーケンスが戻され、エレメントのタイプが JSON 配列または JSON オブジェクトである場合、エラーが戻されます。
複数のエレメントを含むシーケンスが戻された場合は、エラーが戻されます。
エラーが発生した場合、列の値は ON ERROR 節によって指定されます。

column-path-expression-constant の値は、空ストリングまたはすべてがブランクのストリングにすることはできません。 PATH 節が指定されていない場合、カラム-パス-式-定数 (列パス式定数) は列名の接頭部として '$.' として定義されます。

ON EMPTY

列で空シーケンスが戻された場合の動作を指定します。

NULL ON EMPTY: SQL NULL 値が戻されます。この節がデフォルトです。
ERROR ON EMPTY: エラーが戻されます。
DEFAULT default-expression ON EMPTY: default-expression で指定された値が戻されます。 default-expression のデータ・タイプは、戻りデータ・タイプと同じでなければなりません (SQLSTATE 42815)。

ON ERROR

列でエラーが戻された場合の動作を指定します。この節を指定しない場合は、表レベルの ON ERROR 節に指定された動作になります。

NULL ON ERROR: NULL 値が戻されます。
ERROR ON ERROR: エラーが戻されます。
DEFAULT default-expression ON ERROR: default-expression で指定された値が戻されます。 default-expression のデータ・タイプは、戻りデータ・タイプと同じでなければなりません (SQLSTATE 42815)。

json-table-formatted-column-definition

結果表の出力列を指定します。定義には、列名、データ・タイプ、および SQL/JSON パス式が含まれます。この定義は、行のシーケンス項目から値を抽出するために使用されます。抽出された値は、JSON 値として形式設定されます。これは、JSON_QUERY スカラー関数の出力と同等です。

column-name

結果表の列の名前を指定します。名前を修飾したり、結果表の複数の列に対して同じ名前を使用することはできません (SQLSTATE 42711)。

data-type2

列のデータ・タイプを指定します。データ・タイプは、CHAR、VARCHAR、CLOB、VARBINARY、または BLOB にすることができます (SQLSTATE 42815)。

組み込みデータ・タイプの説明については、 CREATE TABLE ステートメントを参照してください。

FORMAT JSON

取得されるデータが JSON ストリングとして形式設定されることを示します。

PATH 列パス式定数 (column-path-expression-constant)

SQL/JSON パスとして解釈される文字ストリング定数を指定します。

column-path-expression-constant は、sql-json-path-expression の SQL/JSON パス式の評価結果を基準として、列値を決定する SQL/JSON パス式を指定します。

SQL/JSON パス式の内容について詳しくは、 sql-json-path-expressionを参照してください。

空シーケンスが戻された場合、列の値は ON EMPTY 節から取得されます。
ERROR ON EMPTY が指定されると、エラーが戻されます。
空シーケンスが戻され、ON EMPTY 節が指定されていない場合、列には NULL 値が割り当てられます。
エラーが発生した場合、列の値は ON ERROR 節によって指定されます。

WITHOUT ARRAY WRAPPER または WITH ARRAY WRAPPER

JSON 配列内で出力値をラップするかどうかを指定します。

WITHOUT ARRAY WRAPPER

結果をラップしないことを示します。この節がデフォルトです。複数の SQL/JSON エレメントを含むシーケンスに解決される厳密 (strict) な SQL/JSON パス定義を使用すると、エラーになります (SQLSTATE 2203A)。複数の SQL/JSON エレメントを含むシーケンスに解決される寛容 (lax) な SQL/JSON パス定義を ON EMPTY を指定して使用すると、エラーになります (SQLSTATE 22035)。

WITH UNCONDITIONAL ARRAY WRAPPER

結果を大括弧で囲んで JSON 配列を作成することを示します。

WITH CONDITIONAL ARRAY WRAPPER

以下の状況の場合に、結果を大括弧で囲んで JSON 配列を作成することを示します。

複数の SQL/JSON エレメントが戻される。
JSON 配列でも JSON オブジェクトでもない単一の SQL/JSON エレメントが戻される。

KEEP QUOTES または OMIT QUOTES

スカラー・ストリングが戻された場合に、周囲の引用符を除去するかどうかを指定します。

KEEP QUOTES: スカラー・ストリングから引用符は除去されません。この節がデフォルトです。
OMIT QUOTES: スカラー・ストリングから引用符が除去されます。 OMIT QUOTES を指定した場合、WITH ARRAY WRAPPER 節は指定できません (SQLSTATE 42601)。

ON EMPTY

列で空シーケンスが戻された場合の動作を指定します。

NULL ON EMPTY: SQL NULL 値が戻されます。この節がデフォルトです。
ERROR ON EMPTY: エラーが戻されます。
EMPTY ARRAY ON EMPTY: 空の JSON 配列が戻されます。
EMPTY OBJECT ON EMPTY: 空の JSON オブジェクトが戻されます。

ON ERROR

列でエラーが戻された場合の動作を指定します。この節を指定しない場合は、表レベルの ON ERROR 節に指定された動作になります。

NULL ON ERROR: SQL NULL 値が戻されます。この節がデフォルトです。
ERROR ON ERROR: エラーが戻されます。
EMPTY ARRAY ON ERROR: 空の JSON 配列が戻されます。
EMPTY OBJECT ON ERROR: 空の JSON オブジェクトが戻されます。

ERROR ON ERROR

表レベルのエラーが発生すると、エラーが戻されます。

注

パラメーター・マーカーが、サポートされるデータ・タイプに明示的にキャストされない場合は、エラーが戻されます (SQLSTATE 42815)。

例

この例では、以下の JSON ドキュメントに基づいています。

{
  "id" : 901,
  "firstname" : "John",
  "lastname"  : "Doe",
  "phoneno"   : "555-3762"
}

従業員 ID、名、姓、および電話番号をリストします。

SELECT U."id", U."firstname", U."lastname", U."phoneno"
  FROM EMPLOYEE_TABLE E
    JSON_TABLE(E.jsondoc, 'strict $'
               COLUMNS( "id" INTEGER,
                        "firstname"  VARCHAR(20),
                        "lastname"   VARCHAR(20),
                        "phoneno"    VARCHAR(20))
                        ERROR ON ERROR) AS U

この照会は、次の表を戻します。

ID	firstname	lastname	phoneno
901	John	Doe	555-3762