AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 云原生数据库 PolarDB 云原生数据库PolarDB PostgreSQL版（兼容Oracle） 开发指南 数据对象 数据类型 JSON复合类型

JSON复合类型

更新时间：
产品详情
我的收藏

PolarDB PostgreSQL版（兼容Oracle）提供了一组与JSON操作相关的扩展类型和方法，包括JSON_KEY_LIST、JSON_NKEY_LIST、JSON_ELEMENT_T、JSON_OBJECT_T和JSON_ARRAY_T类型，这些类型提供处理JSON对象和数组的接口。本文为您介绍这些类型的定义、功能及使用示例。

版本限制

仅支持Oracle语法兼容 2.0且内核小版本为2.0.14.17.32.0及以上。

说明

您可在控制台查看内核小版本号，也可以通过SHOW polardb_version;语句查看。如未满足内核小版本要求，请升级内核小版本。

集合类型

支持JSON_KEY_LIST和JSON_NKEY_LIST两个集合类型。它们通常与JSON_OBJECT_T类型一起使用，用于保存JSON_OBJECT_T的键。

  • JSON_KEY_LIST：VARCHAR2类型的变长数组，最大容量为32,767，单个键名最大长度为4,000字符。

  • JSON_NKEY_LIST：与JSON_KEY_LIST类似，但是它存储的是NVARCHAR2类型的键名，单个键名的最大长度为2,000字符。

JSON_ELEMENT_T

JSON_ELEMENT_T是一种基础类型，提供了一系列常用的JSON操作方法。在实际业务中，该类型的使用相对较少，更多情况下应用的是其派生类型JSON_OBJECT_T和JSON_ARRAY_T。

JSON_ELEMENT_T类型的方法概览如下：

方法

描述

parse

根据字符串构造一个JSON对象。

stringify

将JSON数据转换为字符串。

to_String

将JSON数据转换为字符串。

to_Clob

将JSON数据转换为字符串。

is_Object

判断是否为JSON对象。

is_Array

判断是否为JSON数组。

get_Type

获取JSON对象的类型。

get_Size

获取对象或数组的键/元素数量。

静态函数

静态函数parse根据JSON字符串创建 JSON_ELEMENT_T 对象，函数原型如下：

STATIC FUNCTION parse(jsn VARCHAR2) RETURN JSON_ELEMENT_T
STATIC FUNCTION parse(jsn CLOB) RETURN JSON_ELEMENT_T

示例

DECLARE
    element JSON_ELEMENT_T;
BEGIN
    element := JSON_ELEMENT_T.Parse('{"name": "Alice", "age": 30}');
END;
/

JSON转字符串

相关函数原型如下，用于将JSON_ELEMENT_T对象转换为字符串。

  • stringify

    MEMBER FUNCTION stringify(self IN JSON_ELEMENT_T) RETURN VARCHAR2

  • to_String

    MEMBER FUNCTION to_String(self IN JSON_ELEMENT_T) RETURN VARCHAR2

  • to_Clob

    MEMBER FUNCTION to_Clob(self IN JSON_ELEMENT_T) RETURN CLOB

示例

DECLARE
    element JSON_ELEMENT_T;
BEGIN
    element := JSON_ELEMENT_T.Parse('{"name": "Alice", "age": 30}');
    DBMS_OUTPUT.PUT_LINE(element.Stringify);
END;
/

返回结果如下：

{"age": 30, "name": "Alice"}

JSON类型与大小判断

相关函数原型如下：

  • is_Object：判断是否为JSON对象。

    MEMBER FUNCTION is_Object(self IN JSON_ELEMENT_T) RETURN BOOLEAN

  • is_Array：判断是否为JSON数组。

    MEMBER FUNCTION is_Array(self IN JSON_ELEMENT_T)  RETURN BOOLEAN

  • get_Type：此处分别用于判断当前JSON对象和JSON数组的单个元素的类型。

    MEMBER FUNCTION get_Type(self IN JSON_ELEMENT_T, pos NUMBER) RETURN VARCHAR2
MEMBER FUNCTION get_Type(self IN JSON_ELEMENT_T, key VARCHAR2) RETURN VARCHAR2

  • get_Size：获取对象或数组的键/元素数量。

    MEMBER FUNCTION get_Size(self IN JSON_ELEMENT_T) RETURN NUMBER

示例

  • is_Object

    DECLARE
    element JSON_ELEMENT_T;
BEGIN
    element := JSON_ELEMENT_T.Parse('{"name": "Alice", "age": 30}');
    IF element.is_Object THEN
        DBMS_OUTPUT.PUT_LINE('This is a JSON Object.');
    END IF;
END;
/

    返回结果如下：

    This is a JSON Object.

  • get_Type

    DECLARE
    element JSON_ELEMENT_T;
    element_type VARCHAR2(50);
BEGIN
    element := JSON_ELEMENT_T.Parse('{"name": {"first": "Alice"}, "age": 30}');
    element_type := element.get_Type('name');  -- 输出: OBJECT
    DBMS_OUTPUT.PUT_LINE('Type: ' || element_type);
END;
/

    返回结果如下：

    Type: OBJECT

  • get_Size

    DECLARE
    element JSON_ELEMENT_T;
BEGIN
    element := JSON_ELEMENT_T.Parse('{"name": "Alice", "age": 30}');
    DBMS_OUTPUT.PUT_LINE('Size: ' || element.get_Size()); -- 输出: Size: 2
END;
/

    返回结果如下：

    Size: 2

JSON_OBJECT_T

JSON_OBJECT_T是JSON_ELEMENT_T的派生类型，用于操作键值对形式的JSON数据。

JSON_OBJECT_T类型的方法概览如下：

说明

继承JSON_ELEMENT_T类型的全部方法，此处不再重复列出。

方法

描述

JSON_OBJECT_T

根据字符串构造一个JSON_OBJECT_T对象。

put

向JSON对象中插入键值对。

get

根据键获取对应的值。

get_Object

根据键获取对应的JSON对象。

get_Array

根据键获取对应的JSON数组。

get_String

根据键获取对应的字符串。

get_Clob

根据键获取对应的字符串。

get_Number

根据键获取对应的数字。

get_Date

根据键获取对应的日期。

get_Keys

获取所有键名，用JSON_KEY_LIST保存。

get_Keys_As_Nchar

获取所有键名，用JSON_NKEY_LIST保存。

构造函数

构造函数JSON_OBJECT_T原型如下，参数为空则构造一个不带键值对的空对象，带参数时则将字符串作为键值对构造JSON_OBJECT_T对象。

CONSTRUCTOR FUNCTION JSON_Object_T() RETURN SELF AS RESULT
CONSTRUCTOR FUNCTION JSON_Object_T(jsn VARCHAR2) RETURN SELF AS RESULT
CONSTRUCTOR FUNCTION JSON_Object_T(jsn CLOB) RETURN SELF AS RESULT

示例

  • 参数为空

    DECLARE
    json_obj JSON_OBJECT_T := JSON_OBJECT_T();
BEGIN
    DBMS_OUTPUT.PUT_LINE(json_obj.to_String());
END;
/

    返回结果如下：

    {}

  • 参数不为空

    DECLARE
    json_obj JSON_OBJECT_T := JSON_OBJECT_T('{"name": "Alice", "age": 30}');
BEGIN
    DBMS_OUTPUT.PUT_LINE(json_obj.to_String());
END;
/

    返回结果如下：

    {"age": 30, "name": "Alice"}

键值对读写

  • put：将给定键值对添加到 JSON 对象中，其中值的部分既可以是常见的基础类型，也可以是一个JSON对象。相关函数原型如下：

    MEMBER PROCEDURE put(self IN OUT NOCOPY JSON_OBJECT_T, key VARCHAR2, val VARCHAR2)
MEMBER PROCEDURE put(self IN OUT NOCOPY JSON_OBJECT_T, key VARCHAR2, val CLOB)
MEMBER PROCEDURE put(self IN OUT NOCOPY JSON_OBJECT_T, key VARCHAR2, val NUMBER)
MEMBER PROCEDURE put(self IN OUT NOCOPY JSON_OBJECT_T, key VARCHAR2, val DATE)
MEMBER PROCEDURE put(self IN OUT NOCOPY JSON_OBJECT_T, key VARCHAR2, val JSON_ELEMENT_T)

  • get：根据给定的键，获取对应的值，值也可以是不同的数据类型。相关函数原型如下：

    MEMBER FUNCTION get(self IN JSON_OBJECT_T, key VARCHAR2) RETURN JSON_ELEMENT_T
MEMBER FUNCTION get_String(self IN JSON_OBJECT_T, key VARCHAR2) RETURN VARCHAR2
MEMBER FUNCTION get_Clob(self IN JSON_OBJECT_T, key VARCHAR2) RETURN CLOB
MEMBER FUNCTION get_Number(self IN JSON_OBJECT_T, key VARCHAR2) RETURN NUMBER
MEMBER FUNCTION get_Date(self IN JSON_OBJECT_T, key VARCHAR2) RETURN DATE
MEMBER FUNCTION get_Object(self IN JSON_OBJECT_T, key VARCHAR2) RETURN JSON_OBJECT_T
MEMBER FUNCTION get_Array(self IN JSON_OBJECT_T, key VARCHAR2) RETURN JSON_ARRAY_T

示例

DECLARE
    json_obj JSON_OBJECT_T;
    age NUMBER;
BEGIN
    json_obj := JSON_OBJECT_T.Parse('{"name": "Alice"}');
    json_obj.put('age', 30);
    age := json_obj.get_number('age');
    DBMS_OUTPUT.PUT_LINE(age);
END;
/

返回结果如下：

30

获取所有键

  • get_Keys：返回一个包含所有键的JSON_KEY_LIST对象。相关函数原型如下：

    MEMBER FUNCTION get_Keys(self IN JSON_OBJECT_T) RETURN JSON_KEY_LIST

  • get_Keys_As_Nchar：返回一个包含所有键的JSON_NKEY_LIST对象。相关函数原型如下：

    MEMBER FUNCTION get_Keys_As_Nchar(self IN JSON_OBJECT_T) RETURN JSON_NKEY_LIST

示例

  • get_Keys

    DECLARE
    key_list JSON_KEY_LIST;
    obj JSON_OBJECT_T;
BEGIN
    obj := JSON_OBJECT_T.Parse('{"name": "Alice", "age": 30}');
    -- 提取键名
    key_list := obj.get_keys();
    DBMS_OUTPUT.PUT_LINE(key_list(1)); -- 输出: name
    DBMS_OUTPUT.PUT_LINE(key_list(2)); -- 输出: age
END;
/

    返回结果如下：

    age
name

  • get_Keys_As_Nchar

    DECLARE
    nkey_list JSON_NKEY_LIST;
    obj JSON_OBJECT_T;
BEGIN
    obj := JSON_OBJECT_T.Parse('{"姓名": "Alice", "年龄": 30}');
    -- 获取 JSON 键（作为 NVARCHAR2）
    nkey_list := obj.get_keys_as_nchar();
    DBMS_OUTPUT.PUT_LINE(nkey_list(1)); -- 输出: 姓名
    DBMS_OUTPUT.PUT_LINE(nkey_list(2)); -- 输出: 年龄
END;
/

    返回结果如下：

    姓名
年龄

JSON_ARRAY_T

JSON_ARRAY_T是JSON_ELEMENT_T的派生类型，用于操作JSON数组。

JSON_ARRAY_T类型的方法概览如下：

说明

继承JSON_ELEMENT_T类型的全部方法，此处不再重复列出。

方法

描述

JSON_ARRAY_T

根据字符串构造JSON_ARRAY_T数组。

put

向JSON数组中插入元素。

append

向JSON数组中追加元素。

get

根据键获取对应的值。

get_Boolean

根据键获取对应的布尔值。

get_String

根据键获取对应的字符串。

get_Clob

根据键获取对应的字符串。

get_Number

根据键获取对应的数字。

构造函数

构造函数JSON_ARRAY_T原型如下，参数为空则构造一个不带元组的空数组，带参数时则使用字符串构造JSON_OBJECT_T数组。

CONSTRUCTOR FUNCTION JSON_Array_T() RETURN SELF AS RESULT
CONSTRUCTOR FUNCTION JSON_Array_T(jsn VARCHAR2) RETURN SELF AS RESULT
CONSTRUCTOR FUNCTION JSON_Array_T(jsn CLOB) RETURN SELF AS RESULT

示例

  • 参数为空

    DECLARE
    json_array JSON_ARRAY_T := JSON_ARRAY_T();
BEGIN
    DBMS_OUTPUT.PUT_LINE(json_array.to_String());
END;
/

    返回结果如下：

    []

  • 参数不为空

    DECLARE
    json_array JSON_ARRAY_T := JSON_ARRAY_T('["Alice", 30]');
BEGIN
    DBMS_OUTPUT.PUT_LINE(json_array.to_String()); -- 输出: ["Alice", 30]
END;
/

    返回结果如下：

    ["Alice", 30]

数组读写

  • put

    将给定元素插入JSON数组，该元素既可以是常见的基础类型，也可以是一个JSON对象或数组。相关函数原型如下：

    MEMBER PROCEDURE put(self IN OUT NOCOPY JSON_ARRAY_T, pos NUMBER, val VARCHAR2, overwrite BOOLEAN DEFAULT FALSE)
MEMBER PROCEDURE put(self IN OUT NOCOPY JSON_ARRAY_T, pos NUMBER, val CLOB, overwrite BOOLEAN DEFAULT FALSE)
MEMBER PROCEDURE put(self IN OUT NOCOPY JSON_ARRAY_T, pos NUMBER, val NUMBER, overwrite BOOLEAN DEFAULT FALSE)
MEMBER PROCEDURE put(self IN OUT NOCOPY JSON_ARRAY_T, pos NUMBER, val JSON_ELEMENT_T, overwrite BOOLEAN DEFAULT FALSE)

  • append

    将给定元素追加到JSON数组，该元素既可以是常见的基础类型，也可以是一个 JSON 对象或数组。相关函数原型如下：

    MEMBER PROCEDURE append(self IN OUT NOCOPY JSON_ARRAY_T, val VARCHAR2)
MEMBER PROCEDURE append(self IN OUT NOCOPY JSON_ARRAY_T, val CLOB)
MEMBER PROCEDURE append(self IN OUT NOCOPY JSON_ARRAY_T, val NUMBER)
MEMBER PROCEDURE append(self IN OUT NOCOPY JSON_ARRAY_T, val JSON_ELEMENT_T)

  • get

    根据给定的键，获取对应的值，值也可以是不同的数据类型。相关函数原型如下：

    MEMBER FUNCTION get(self IN JSON_ARRAY_T, pos NUMBER) RETURN JSON_Element_T
MEMBER FUNCTION get_String(self IN JSON_ARRAY_T, pos NUMBER) RETURN VARCHAR2
MEMBER FUNCTION get_Clob(self IN JSON_ARRAY_T, pos NUMBER) RETURN CLOB
MEMBER FUNCTION get_Number(self IN JSON_ARRAY_T, pos NUMBER) RETURN NUMBER
MEMBER FUNCTION get_Boolean(self IN JSON_ARRAY_T, pos NUMBER) RETURN BOOLEAN

示例

DECLARE
    json_array JSON_ARRAY_T;
BEGIN
    json_array := JSON_ARRAY_T.Parse('["Alice"]');
    json_array.append(30);
    DBMS_OUTPUT.PUT_LINE(json_array.get_number(1)); -- 输出: 30
END;
/

返回结果如下：

30
上一篇：JSON类型下一篇：货币类型