JSON_TABLE 表函数

JSON_TABLE 表函数从 SQL/JSON 路径表达式的求值中返回结果表。行 SQL/JSON 路径表达式的结果序列中的每个项都表示结果表中的一行或多行。

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)。

' 严格 $'

指定当指定的路径表达式无法用于从上下文项开始浏览当前 JSON 文档时，将报告错误。根据当前 ON ERROR 子句处理错误。

列

指定结果表的输出列，包括列名，数据类型以及如何计算每行的列值。结果列长度之和不能超过 64 KB。

json-table-正则-column-definition

指定结果表的输出列，包括列名，数据类型和 SQL/JSON 路径表达式，以从行的序列项中抽取值。这相当于 JSON_VALUE 标量函数的输出。

列名称

指定结果表中的列名。不能限定该名称，并且不能将同一名称用于结果表的多列 (SQLSTATE 42711)。

data-type1

指定列的数据类型。

请参阅 CREATE TABLE 语句以获取内置数据类型的描述。

路径 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 子句，那么会将空值分配给该列。
如果返回单个元素序列，并且该元素的类型不是 JSON 数组或 JSON 对象，那么该值将转换为针对该列指定的数据类型。
如果返回单个元素序列，并且该元素的类型为 JSON 数组或 JSON 对象，那么将返回错误。
如果返回具有多个元素的序列，那么将返回错误。
如果发生错误，那么 ON ERROR 子句指定列的值。

column-path-expression-constant 的值不得为空字符串或所有空格的字符串。如果未指定 PATH 子句，那么 column-path-expression-constant 定义为 '$.' 前缀为 column-name。

空的

指定为列返回空序列时的行为。

空空空: 返回 SQL 空值。该值为缺省值。
EMPTY 上出错: 返回了错误。
缺省缺省-表达式 ON EMPTY: 将返回由 default-expression 指定的值。 default-expression 的数据类型必须与返回数据类型 (SQLSTATE 42815) 相同。

ON ERROR

指定对列返回错误时的行为。如果未指定此子句，那么将遵循为表级别 ON ERROR 子句指定的行为。

空开启错误: 送回空值。
ERROR ON ERROR: 返回了错误。
缺省值 default-expression ON 错误: 将返回由 default-expression 指定的值。 default-expression 的数据类型必须与返回数据类型 (SQLSTATE 42815) 相同。

json-table-格式化-column-definition

指定结果表的输出列。该定义包含列名，数据类型和 SQL/JSON 路径表达式。此定义用于从行的序列项中抽取值。抽取的值将格式化为 JSON 值。这相当于 JSON_QUERY 标量函数的输出。

列名称

指定结果表中的列名。不能限定该名称，并且不能将同一名称用于结果表的多列 (SQLSTATE 42711)。

data-type2

指定列的数据类型。数据类型可以是 CHAR ， VARCHAR ， CLOB ， VARBINARY 或 BLOB (SQLSTATE 42815)。

请参阅 CREATE TABLE 语句以获取内置数据类型的描述。

FORMAT JSON

指示将检索的数据格式化为 JSON 字符串。

路径 column-path-expression-constant

指定解释为 SQL/JSON 路径的字符串常量。

column-path-expression-constant 指定 SQL/JSON 路径表达式，该表达式确定与 sql-json-path-expression中的 SQL/JSON 路径表达式求值结果相关的列值。

有关 SQL/JSON 路径表达式的内容的更多信息，请参阅 sql-json-path-expression。

如果返回空序列，那么 ON EMPTY 子句将提供列的值。
如果指定了 ERROR ON EMPTY ，那么将返回错误。
如果返回空序列并且未指定 ON EMPTY 子句，那么会将空值分配给该列。
如果发生错误，那么 ON ERROR 子句指定列的值。

column-path-expression-constant 的值不得为空字符串或所有空格的字符串。如果未指定 PATH 子句，那么 column-path-expression-constant 定义为 '$.' 前缀为 column-name。

没有数组包装器或带有数组包装器

指定输出值是否包含在 JSON 数组中。

无数组包装程序

指示结果未回绕。该值为缺省值。使用解析为两个或更多 SQL/JSON 元素的序列的严格 SQL/JSON 路径定义会导致错误 (SQLSTATE 2203A)。将宽松的 SQL/JSON 路径定义与解析为两个或多个 SQL/JSON 元素的序列的 ON EMPTY 配合使用会导致错误 (SQLSTATE 22035)。

使用无条件数组包装程序

指示结果用方括号括起来以创建 JSON 数组。

使用条件数组包装程序

指示结果用方括号括起来，以便为以下任一场景创建 JSON 数组:

返回多个 SQL/JSON 元素。
返回不是 JSON 数组或 JSON 对象的单个 SQL/JSON 元素。

保留引号或省略引号

指定返回标量字符串时是否除去周围的引号。

保留引号: 不会从标量字符串中除去引号。该值为缺省值。
省略引号: 将从标量字符串中除去引号。当指定略去引号时，不能指定 WITH ARRAY WRAPPER 子句 (SQLSTATE 42601)。

空的

指定对列返回空序列时的行为。

空空空: 返回 SQL 空值。该值为缺省值。
EMPTY 上出错: 返回了错误。
空的数组: 返回空的 JSON 数组。
空对象: 返回空的 JSON 对象。

ON ERROR

指定对列返回错误时的行为。如果未指定此子句，那么将遵循为表级别 ON ERROR 子句指定的行为。

空开启错误: 返回 SQL 空值。该值为缺省值。
ERROR ON ERROR: 返回了错误。
出错时数组为空: 返回空的 JSON 数组。
出错时对象为空: 返回空的 JSON 对象。

ERROR ON ERROR

迂到表级别错误时，将返回错误。

注意

如果参数标记未显式转换为受支持的数据类型，那么将返回错误 (SQLSTATE 42815)

示例

此示例基于以下 JSON 文档:

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

列出员工标识，名字，姓氏和电话号码:

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

此查询返回下表:

标识	firstname	LASTNAME	PHONENO
901	John	Doe	555-3762