SQL/JSON: Document behavior when input document is not jsonb

amitlan · amitlan · commit 473a352fb393 · 2024-06-28T09:45:03.000+09:00
The input document to functions JSON_EXISTS(), JSON_QUERY(), JSON_VALUE(), and JSON_TABLE() can be specified as character or UTF8-encoded bytea strings. These are automatically converted to jsonb with an implicit cast before being passed to the jsonpath machinery. In the current implementation, errors that occur when parsing the specified string into a valid JSON document are thrown unconditionally. This means they are not subject to the explicit or implicit ON ERROR clause of those functions, which is a standard- conforming behavior. Add a note to the documentation to mention that. Reported-by: Markus Winand Discussion: https://postgr.es/m/F7DD1442-265C-4220-A603-CB0DEB77E91D%40winand.at
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
@@ -18861,6 +18861,16 @@ DETAIL:  Missing "]" after array dimensions.
     </tbody>
    </tgroup>
   </table>
+  <note>
+   <para>
+    The <replaceable>context_item</replaceable> expression is converted to
+    <type>jsonb</type> by an implicit cast if the expression is not already of
+    type <type>jsonb</type>. Note, however, that any parsing errors that occur
+    during that conversion are thrown unconditionally, that is, are not
+    handled according to the (specified or implicit) <literal>ON ERROR</literal>
+    clause.
+   </para>
+  </note>
   </sect2>
 
  <sect2 id="functions-sqljson-table">
