openGauss插件使用指南:函数和操作符—JSON-JSONB函数和操作符（中）

• json_extract(json_doc, path[, path] …)

  描述：在 JSON 文档提取路径表达式指定的数据并返回。

  返回类型：json

  示例：

  opengauss=# select json_extract('{"f2":{"f3":1},"f4":{"f5":99,"f6":"stringy"}}', '$.f4.f6');
   json_extract 
  --------------
   "stringy"
  (1 row)
  

• json_unquote(json_val)

  描述：去除文本中的引号，对转义符有所处理，或者舍弃 JSON 值中的引号。

  返回类型：text

  示例：

  opengauss=# select json_unquote('"dajifa\\tIMIDF"');
   json_unquote  
  ---------------
   dajifa  IMIDF
  (1 row)
  

• json_unquote(json_extract(column, path))

  描述：去除文本中的引号，对转义符有所处理，或者舍弃 JSON 值中的引号。

  返回类型：text

  示例：

  opengauss=# select json_unquote(json_extract('{"a": "lihua"}', '$.a'));
   json_unquote 
  --------------
   lihua
  (1 row)
  

• json_keys(json_doc[, path])

  描述：将 JSON 对象的顶级值中的键作为 JSON 数组返回，如果给定了路径参数，则返回路径所指示 JSON 对象的顶级键。

  返回类型：json

  示例：

  opengauss=# SELECT JSON_KEYS('{"a":123,"b":{"c":"qwe"}}');
  
   json_keys 
  -----------
  
   ["a","b"]
  (1 row)
  

• json_search(json_doc，one_or_all，search_str [，escape_char [，path] …])

  描述：可传入一个或多个路径参数，根据转义符和one_or_all模式，返回目标字符串在路径限定下对应目标文件中的所在位置。

  返回类型：text

  备注：

  • 转义符如果为boolean型相当于 NULL，默认"\"为转义符，可以直接输入个位数整型作为转义符。
  • 目标json文件和目标字符串不能为空，路径不能含空，如果path不存在则返回空。
  • one_or_all只能输入one或all。
  • search_str可以直接输入整型、浮点型、boolean型进行匹配，但是只能匹配目标文件中的字符串。
  • search_str可以使用模糊匹配，path中可以使用通配符进行匹配。

  示例：

  opengauss=# select json_search('"abc"','one','abc',true);    
   json_search 
  -------------
   "$"
  (1 row)
  
  opengauss=# select json_search('"a%c"','all','a1%c',1);
   json_search 
  -------------
   "$"
  (1 row)
  
  opengauss=# select json_search('"abc"','one','abc','&','$',null);
   json_search 
  -------------
  
  (1 row)
  
  opengauss=# select json_search('"1.2"','one',1.2);
   json_search 
  -------------
   "$"
  (1 row)
  
  opengauss=# select json_search('{"a":[{"b":["abc","abc"]},"ac"],"c":["abbc","abcc"]}','all','a%c',null,'$.*[*]');
                           json_search                          
  --------------------------------------------------------------
   ["$.a[0].b[0]", "$.a[0].b[1]", "$.a[1]", "$.c[0]", "$.c[1]"]
  (1 row)
  

• json_array_append(json, path, value[, path2, value2] …)

  描述：用来修改 JSON 文档，它向指定的数组节点中追加一个元素，并返回修改后的 JSON 文档。

  返回类型：json

  opengauss=# select JSON_ARRAY_APPEND('{"name": "Tim", "hobby": "car"}', '$.name', 'food');
  
               json_array_append             
  -------------------------------------------
  
   {"name": ["Tim", "food"], "hobby": "car"}
  (1 row)
  

• json_append(json_doc, path, val[, path, val] …) 描述：功能同json_array_append函数。

  返回类型：json

  备注： json_append() 函数可能在将来的版本中被删除，推荐使用json_array_append函数。 示例：

  opengauss=# select JSON_ARRAY_APPEND('{"name": "Tim", "hobby": "car"}', '$.name', 'food');
  
               json_array_append             
  -------------------------------------------
  
   {"name": ["Tim", "food"], "hobby": "car"}
  (1 row)
  

• json_array_insert(json, path, value[, path2, value2] …)

  描述：函数用来修改 JSON 文档，它向 JSON 文档中的指定的数组中的指定位置插入一个值并返回新的 JSON 文档。

  返回类型：json

  备注：

  • 如果路径表达式指示的数组元素超过了数组的长度，那么新元素将插入到数组的尾部。
  • 如果 JSON 文档或者路径为 NULL，此函数将返回 NULL。

  示例：

  opengauss=# select json_array_insert('[1, [2, 3], {"a": [4, 5]}]', '$[0]', 0);
        json_array_insert       
  -------------------------------
  [0, 1, [2, 3], {"a": [4, 5]}]
  (1 row)
  
  opengauss=# select json_array_insert('[1, [2, 3], {"a": [4, 5]}]', '$[9]', 4);
        json_array_insert       
  -------------------------------
  [1, [2, 3], {"a": [4, 5]}, 4]
  (1 row)
  

• json_insert(json_doc, path, val[, path, val] …)

  描述：向一个 JSON 文档中插入数据并返回新的 JSON 文档。

  返回类型：json

  备注：当 JSON 文档或path为空时，返回空。

  示例：

  opengauss=# select json_insert('{"x": 1}','$.y',true);
       json_insert     
  ---------------------
   {"x": 1, "y": true}
  (1 row)
  

• json_merge(json_doc, json_doc[, json_doc] …)

  描述：功能同json_merge_preserve函数。

  返回类型：json

  备注： JSON_MERGE() 函数可能在将来的版本中被删除，推荐使用json_merge_preserve函数。

  示例：

  openGauss=# select json_merge('"opengauss"', '[[1,2],3,"test"]');
              json_merge            
  ----------------------------------
   ["opengauss", [1, 2], 3, "test"]
  (1 row)
  

• json_merge_preserve(json_doc, json_doc[, json_doc] …)

  描述：合并两个及以上的 JSON，相同键值合并为一个数组。

  返回类型：json

  备注：

  • 如果任何参数为NULL则返回NULL。
  • 合并规范：
    • 若相邻的两个 JSON 参数一个为scalar或对象，一个为数组。将scalar或对象，作为数组元素，按照参数的先后顺序，加入数组参数中，合并为单个数组。
    • 若相邻的两个 JSON 参数都是scalar或对象。将scalar或对象按照参数的先后顺序，合并为单个数组。
    • 若相邻的两个 JSON 参数都是数组。将两个数组的各个元素，按照参数的先后顺序，合并为单个数组。
    • 若相邻的两个 JSON 参数都是对象。将两个对象的各个成员，按照key的顺序，合并为单个对象。
    • 合并 JSON 后的对象成员返回值，全部符合key的顺序。

  示例：

  openGauss=# select json_merge_preserve('{"a":"abc"}', '[1,true,null]');
        json_merge_preserve      
  -------------------------------
   [{"a": "abc"}, 1, true, null]
  (1 row)
  
  openGauss=# select json_merge_preserve('1', '"b"', 'true');
   json_merge_preserve 
  ---------------------
   [1, "b", true]
  (1 row)
  
  openGauss=# select json_merge_preserve('[1,{"a":"abc"}]', '["b",false]');
        json_merge_preserve      
  -------------------------------
   [1, {"a": "abc"}, "b", false]
  (1 row)
  
  openGauss=# select json_merge_preserve('{"b":"abc"}', '{"a":"jks"}');
     json_merge_preserve    
  --------------------------
   {"a": "jks", "b": "abc"}
  (1 row)
  
  openGauss=# select json_merge_preserve(NULL, '1');
   json_merge_preserve 
  ---------------------
  
  (1 row)
  

• json_merge_patch(json_doc, json_doc[, json_doc] …)

  描述：合并两个及以上的 JSON ，相同键值保留后者 JSON 对象键值成员。

  返回类型：json

  备注：

  • 若任一参数为NULL，则之前的参数和该参数的合并结果为 NULL。
  • NULL 参数后面一个参数若非 NULL，则：
    • 后面参数为数组、scalar，合并结果为后面参数本身。
    • 后面参数为对象，合并结果为 NULL。
  • 合并规范：
    • 若相邻的两个 JSON 参数都是对象，则合并结果为单个对象。
      • 若一个 JSON 对象的某一成员键在另一个 JSON 对象中没有重复，则在合并结果中保留该成员。
      • 若前一个 JSON 对象的某一成员键在后一个 JSON 对象中重复，则在合并结果中，保留后者 JSON 对象中重复键成员。特别地，当后一个相同键对应对象成员的value为 NULL 时，在结果中删除该键成员。
    • 若相邻的两个 JSON 参数存在一个参数不是对象，则合并的结果直接为第二个 JSON 参数。
    • 若任一参数为NULL，则位于该参数之前的参数和该参数的合并结果为 NULL
    • NULL 参数后面一个参数若非 NULL ，则：
      • 后者参数为数组或scalar，合并结果为后面参数本身。
      • 后者参数为对象，合并结果为 NULL 。

  示例：

  openGauss=# select json_merge_patch('{"a":1}', '{"b":2}');
   json_merge_patch 
  ------------------
   {"a": 1, "b": 2}
  (1 row)
  
  openGauss=# select json_merge_patch('{"a":1}', '{"a":2}');
   json_merge_patch 
  ------------------
   {"a": 2}
  (1 row)
  
  openGauss=# select json_merge_patch('{"a":{"b":"abc"}}', '{"a":{"b":null}}');
   json_merge_patch 
  ------------------
   {"a": {}}
  (1 row)
  
  openGauss=# select json_merge_patch('{"a":1}', 'true');
   json_merge_patch 
  ------------------
   true
  (1 row)
  
  openGauss=# select json_merge_patch('{"a":1}', NULL);
   json_merge_patch 
  ------------------
  
  (1 row)
  
  openGauss=# select json_merge_patch(NULL, '{"a":1}');
   json_merge_patch 
  ------------------
  
  (1 row)
  
  openGauss=# select json_merge_patch(NULL, '[1,2,3]');
   json_merge_patch 
  ------------------
   [1, 2, 3]
  (1 row)