DOC: improved descriptions of handling data types by SQL/JSON functions based on feedback from Nikita Glukhov

Author: Liudmila Mantrova

doc/src/sgml/biblio.sgml

@@ -136,7 +136,7 @@
     1988
    
 
-   sqltr17">
+   sqltr-19075-6">
     SQL Technical Report
     Part 6: SQL support for JavaScript Object
       Notation (JSON)

doc/src/sgml/func-sqljson.sgml

@@ -24,8 +24,9 @@
   
 
   
-    To learn more about the SQL/JSON standard, see .
-    For details on JSON types supported in PostgreSQL, see .
+    To learn more about the SQL/JSON standard, see .
+    For details on JSON types supported in PostgreSQL,
+    see .
   
 
  
@@ -1064,15 +1065,13 @@ SELECT JSON_EXISTS(jsonb '{"a": [1,2,3]}', 'strict $.a[5]');
     
     
      
-       The output clause that specifies the data type of the returned value.
-       Out of the box, PostgreSQL
-       supports the following types: json, jsonb,
-       bytea, and character string types (text, char,
-       varchar, and nchar).
-       The extracted value must be a single SQL/JSON scalar item
-       and have a cast to the specified type. Otherwise, an error occurs.
+       The output clause that specifies the SQL data type the extracted value
+       will be represented as. The extracted value must be a single
+       SQL/JSON scalar item and have a cast to the
+       specified type. Otherwise, an error occurs.
        By default, JSON_VALUE returns a string
-       of the text type.
+       of the text type. For details, see
+       .
      
      
    
@@ -1112,11 +1111,10 @@ SELECT JSON_EXISTS(jsonb '{"a": [1,2,3]}', 'strict $.a[5]');
      Examples
 
      
-      Extract an SQL/JSON value and return it as an SQL
-      scalar of the specified type. Note that
-      JSON_VALUE can only return a
-      single scalar, and the returned value must have a
-      cast to the specified return type:
+      Extract an SQL/JSON value and return it as an SQL scalar
+      of the specified type. Note that JSON_VALUE
+      can only return a single scalar, and the extracted value must have
+      a cast to the specified return type:
      
 
 
@@ -1226,7 +1224,12 @@ SELECT JSON_VALUE(jsonb '[1,2]', 'strict $[*]' DEFAULT 1 ON ERROR);
     
     
      
-       The output clause that specifies the data type of the returned value.
+       The output clause that specifies the SQL data type the extracted
+       SQL/JSON object or array will be represented as. By default,
+       JSON_QUERY returns a string of the
+       json type, unless the context item is explicitly
+       converted to another type. In this case, the return type corresponds
+       to the type of the context item.
        For details, see .
      
      
@@ -2032,19 +2035,127 @@ FROM
     
      
        The output clause that specifies the return type of the generated
-       JSON object. Out of the box, PostgreSQL
-       supports the following types: json, jsonb,
-       bytea, and character string types (text, char,
-       varchar, and nchar).
-       To use other types, you must create the CAST from json for this type.
-       By default, the json type is returned.
+       SQL/JSON item.
      
+
      
-       The optional FORMAT clause is provided to conform to the SQL/JSON standard.
-      
+       The RETURNING clause is common for both constructor
+       and query SQL/JSON functions. All functions rely on type casts
+       available in PostgreSQL, but have some
+       implementation specifics that determines which types can be used
+       by a particular function. Type casts supported by
+       PostgreSQL out of the box are listed
+       in .
+     
+
+     
+       Constructor functions support json, jsonb,
+       bytea, and any other types that have a cast from
+       the SQL type of the constructed item. By default,
+       the constructed item is represented as json.
+     
+
      
-       The output clause is common for both constructor and query SQL/JSON functions.
+       For the JSON_VALUE function, you can use
+       json, jsonb, or any other type that has
+       a cast from the SQL type that corresponds to the SQL/JSON type of the
+       extracted value. The output to json and jsonb
+       types will always work regardless of the type of the extracted value,
+       since SQL/JSON items are converted directly to json or
+       jsonb without casting. With other types, the result
+       depends on the combination of the type of the extracted value
+       and the specified return type: if no cast is found, an error occurs.
+       By default, the SQL/JSON item returned by
+       JSON_VALUE is represented as text.
      
+
+     
+       With the JSON_QUERY function, you can use any
+       return types. The implementation details are as follows:
+     
+      
+       
+        For SQL/JSON items of a scalar SQL type, a cast from json
+        or jsonb is searched, depending on the type of the context
+        item. If no cast is found, an input/output function is used for
+        conversion. As an exception, if you use the bytea return
+        type, the extracted SQL/JSON item is converted to the return type as
+        follows: convert_to(json[b]::text, 'UTF8').
+        If JSON_QUERY extracts an SQL/JSON string,
+        which is not wrapped using the WRAPPER clause,
+        and the OMIT QUOTES clause is specified, the string
+        contents is converted to the return type using the input/output
+        function that corresponds to this return type.
+       
+      
+      
+       
+        For SQL/JSON items of non-scalar SQL types (arrays, records, and
+        domains), the json[b]_populate_record() function
+        is used for conversion to the specified return type. This is a
+        PostgreSQL extension of the SQL/JSON standard.
+       
+      
+     
+       By default, JSON_QUERY returns a string of the
+       json type, unless the context item is is explicitly
+       converted to another type. In this case, the return type corresponds
+       to the type of the context item.
+     
+
+  2107+     Type Casts Supported by <productname>PostgreSQL</productname>2108+     2109+      2110+       2111+        SQL/JSON type2112+        SQL Type2113+       2114+      2115+      2116+       2117+        string2118+        text2119+       2120+       2121+        number2122+        numeric2123+       2124+       2125+        boolean2126+        boolean2127+       2128+       2129+        date2130+        date2131+       2132+       2133+        time2134+        time2135+       2136+       2137+        time with tz2138+        timetz2139+       2140+       2141+        timestamp2142+        timestamp2143+       2144+       2145+        timestamp with tz2146+        timestamptz2147+       2148+      2149+     2150+  
+     Type Casts Supported by <productname>PostgreSQL</productname>
+     
+      
+       
+        SQL/JSON type
+        SQL Type
+       
+      
+      
+       
+        string
+        text
+       
+       
+        number
+        numeric
+       
+       
+        boolean
+        boolean
+       
+       
+        date
+        date
+       
+       
+        time
+        time
+       
+       
+        time with tz
+        timetz
+       
+       
+        timestamp
+        timestamp
+       
+       
+        timestamp with tz
+        timestamptz
+       
+      
+     
+  
+
+     
+       The optional FORMAT clause is provided
+       to conform to the SQL/JSON standard and can only take the
+       json value as an argument.
+       PostgreSQL currently supports
+       only the UTF8 encoding.
+      
      
    
     
@@ -2067,18 +2178,18 @@ FROM
   
     The SQL/JSON query functions pass the provided path expression to
     the path engine for evaluation.
-    The path expression is evaluated from left to right.
-    You can use parentheses to change the order of operations.
-    If the evaluation is successful, an SQL/JSON sequence is produced.
-    The evaluation result is returned to the SQL/JSON query function
+    The path expression is evaluated from left to right, but
+    you can use parentheses to change the order of operations.
+    If the evaluation is successful, an SQL/JSON sequence is produced,
+    and the evaluation result is returned to the SQL/JSON query function
     that completes the specified computation. If the query result
     must be JSON text, you have to use the WITH WRAPPER clause
     or enclose the path expression in square brackets to ensure
     the evaluation result is an array.
   
 
   
-    A typical path expression has the following structure:
+    A path expression has the following structure:
   
 
   
@@ -2508,7 +2619,7 @@ FROM
        
        
         like_regex
-        Tests pattern matching with regular expressions
+        Tests pattern matching with POSIX regular expressions
         ["abc", "abd", "aBdC", "abdacb", "babc"]
         $[*] ? (@ like_regex "^ab.*c" flag "i")
         "abc", "aBdC", "abdacb"
@@ -3545,4 +3656,3 @@ FROM
  
 
 
-