JSON_OBJECT 标量函数

JSON_OBJECT 函数通过使用指定的 "键/值" 对来生成 JSON 对象。 如果未提供 "键: 值" 对，那么将返回空对象。

Read syntax diagramSkip visual syntax diagramJSON_OBJECT(,KEYkey-expressionVALUEJSON-expressionFORMATJSONBSONNULL ON NULLABSENT ON NULLWITHOUT UNIQUE KEYSWITH UNIQUE KEYSRETURNING CLOB(2G) FORMAT JSONRETURNINGdata-typeFORMAT JSONENCODING UTF8FORMAT BSON)
data-type
Read syntax diagramSkip visual syntax diagramCHARACTERCHAR(1)( integer)CHARACTERCHARVARYINGVARCHAR( integer)CHARACTERCHARLARGE OBJECTCLOB(1M)( integerKMG)BINARY VARYINGVARBINARY(integer)BINARY LARGE OBJECTBLOB(1M)( integerKMG)

虽然此函数的模式是 SYSIBM，但不能将该函数指定为限定名。

键表达式
JSON 密钥的名称。 名称不得为空 (SQLSTATE 22004)。 key-expression 的结果必须是内置字符串数据类型，但以下数据类型除外 (SQLSTATE 42815):
  • GRAPHIC
  • VARGRAPHIC
  • DBCLOB
  • CHAR FOR BIT DATA
  • VARCHAR FOR BIT DATA
JSON 表达式
用于生成与 key-expression关联的 JSON 值的表达式。
此表达式的结果类型可以是任何内置数据类型，但以下数据类型除外 (SQLSTATE 42815):
  • GRAPHIC
  • VARGRAPHIC
  • DBCLOB
  • BINARY
  • CHAR FOR BIT DATA
  • VARCHAR FOR BIT DATA
  • XML
  • 源自先前列示的任何数据类型的用户定义类型

如果生成的值是数字，那么它不能是 Infinity ， NaN或 sNaN (SQLSTATE 22023)。

如果未指定 FORMAT JSON 或 FORMAT BSON ，并且生成的值不是数字，那么将对结果字符串中的任何特殊字符 (例如，反斜杠或双引号) 进行转义。

如果未指定 FORMAT JSON 或 FORMAT BSON ，并且表达式是二进制字符串类型，那么会将其解释为 FORMAT BSON。

FORMAT JSON
JSON-expression 格式化为 JSON 数据。

如果 JSON-expression 是字符串数据类型，那么会将其视为 JSON 数据。

如果 JSON-expression 是二进制字符串数据类型，那么会将其解释为 UTF-8 数据。

FORMAT BSON
指定将 JSON-expression 格式化为 JSON 数据的 BSON 表示形式 (SQLSTATE 22032)。 JSON-expression 必须是二进制字符串数据类型 (SQLSTATE 42815)。
ON NULL
指定当 JSON-expression 为空值时要返回的内容。
NULL ON NULL
将返回表示空值的字符串。 该值为缺省值。
空的 ABSENT
JSON 对象中省略了 "键: 值" 对。
不带唯一键或 WITH UNIQUE KEYS
指定生成的 JSON 对象的键值是否必须唯一。
没有唯一键
不会检查生成的 JSON 对象是否存在重复键。 该值为缺省值。
使用唯一键
生成的 JSON 对象必须具有唯一键值 (SQLSTATE 22037)。

生成具有唯一键的 JSON 对象被视为最佳实践。 如果 key-expression 生成唯一键名称，请省略 WITH UNIQUE KEYS 以提高性能。

正在返回数据类型
结果的数据类型可以是 CHAR ， VARCHAR ， CLOB ， VARBINARY 或 BLOB (SQLSTATE 42815)。 缺省值为 CLOB (2 GB)。

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

FORMAT JSON
返回的数据将格式化为 JSON 数据。
编码 UTF8
指定当 数据类型 是二进制字符串类型时要使用的编码。 此子句仅允许用于二进制字符串类型。 二进制字符串的缺省值为 UTF-8。
FORMAT BSON
返回的数据将格式化为 JSON 数据的 BSON 表示 (SQLSTATE 22032)。 data-type 必须是二进制字符串数据类型 (SQLSTATE 42815)。

注意

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

示例

  1. 生成人员姓名的 JSON 对象。
    VALUES JSON_OBJECT(KEY 'first' VALUE 'John', KEY 'last' VALUE 'Doe')

1
-----------------------------
{"first":"John","last":"Doe"}
  2. 生成一个 JSON 对象，其中包含员工编号为 "000020" 的员工的姓氏，雇佣日期和工资。
    SELECT JSON_OBJECT(KEY 'Last name' VALUE LASTNAME, 
                   KEY 'Hire date' VALUE HIREDATE, 
                   KEY 'Salary' VALUE SALARY)
   FROM EMPLOYEE
   WHERE EMPNO  = '000020';

1
-------------------------------------------------------------------
{"Last name":"THOMPSON","Hire date":"1973-10-10","Salary":41250.00}