Re: SQL/JSON query functions context_item doc entry and type requirement

On Mon, Jun 17, 2024 at 2:43 PM Amit Langote <amitlangote09@gmail.com> wrote:
>
> Hi,
>
> On Tue, Jun 4, 2024 at 12:11 AM jian he <jian.universality@gmail.com> wrote:
> >
> > hi
> > based on gram.y and function transformJsonValueExpr.
> >
> > gram.y:
> > | JSON_QUERY '('
> > json_value_expr ',' a_expr json_passing_clause_opt
> > json_returning_clause_opt
> > json_wrapper_behavior
> > json_quotes_clause_opt
> > json_behavior_clause_opt
> > ')'
> >
> > | JSON_EXISTS '('
> > json_value_expr ',' a_expr json_passing_clause_opt
> > json_on_error_clause_opt
> > ')'
> >
> > | JSON_VALUE '('
> > json_value_expr ',' a_expr json_passing_clause_opt
> > json_returning_clause_opt
> > json_behavior_clause_opt
> > ')'
> >
> > json_format_clause_opt contains:
> > | FORMAT_LA JSON
> > {
> > $$ = (Node *) makeJsonFormat(JS_FORMAT_JSON, JS_ENC_DEFAULT, @1);
> > }
> >
> >
> > That means, all the context_item can specify "FORMAT JSON" options,
> > in the meantime, do we need to update these functions
> > synopsis/signature in the doc?
> >

>
> If I understand correctly, you're suggesting that we add a line to the
> above paragraph to mention which types are appropriate for
> context_item.  How about we add the following:
>
> <replaceable>context_item</replaceable> expression can be a value of
> any type that can be cast to <type>jsonb</type>. This includes types
> such as <type>char</type>,  <type>text</type>, <type>bpchar</type>,
> <type>character varying</type>, and <type>bytea</type> (with
> <code>ENCODING UTF8</code>), as well as any domains over these types.

your wording looks ok to me. I want to add two sentences. so it becomes:

+   The <replaceable>context_item</replaceable> expression can be a value of
+    any type that can be cast to <type>jsonb</type>. This includes types
+   such as <type>char</type>,  <type>text</type>, <type>bpchar</type>,
+    <type>character varying</type>, and <type>bytea</type> (with
+    <code>ENCODING UTF8</code>), as well as any domains over these types.
+    The <replaceable>context_item</replaceable> expression can also
be followed with
+    <literal>FORMAT JSON</literal>, <literal>ENCODING UTF8</literal>.
+    These two options currently don't have actual meaning.
+    <literal>ENCODING UTF8</literal> can only be specified when
<replaceable>context_item</replaceable> type is <type>bytea</type>.

imho, "These two options currently don't have actual meaning." is accurate,
but still does not explain why we allow "FORMAT JSON ENCODING UTF8".
I think we may need an explanation for  "FORMAT JSON ENCODING UTF8".
because json_array, json_object, json_serialize, json all didn't
mention the meaning of "[ FORMAT JSON [ ENCODING UTF8 ] ] ".


I added "[ FORMAT JSON [ ENCODING UTF8 ] ] " to the function
signature/synopsis of json_exists, json_query, json_value.