On Mon, Jun 17, 2024 at 2:43 PM Amit Langote <amitlangot...@gmail.com> wrote:
>
> Hi,
>
> On Tue, Jun 4, 2024 at 12:11 AM jian he <jian.universal...@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.
From c5e2b51d351c3987e96290363288499f1a369e49 Mon Sep 17 00:00:00 2001
From: jian he <jian.universal...@gmail.com>
Date: Mon, 17 Jun 2024 17:35:01 +0800
Subject: [PATCH v1 1/1] minor SQL/JSON Query Functions doc fix
main fix doc context_item description.
---
doc/src/sgml/func.sgml | 21 +++++++++++++++++----
1 file changed, 17 insertions(+), 4 deletions(-)
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 17c44bc3..18db4a5b 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -18663,7 +18663,17 @@ $.* ? (@ like_regex "^\\d+$")
described in <xref linkend="functions-sqljson-querying"/> can be used
to query JSON documents. Each of these functions apply a
<replaceable>path_expression</replaceable> (the query) to a
- <replaceable>context_item</replaceable> (the document); see
+ <replaceable>context_item</replaceable> (the document).
+ 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>.
+ See
<xref linkend="functions-sqljson-path"/> for more details on what
<replaceable>path_expression</replaceable> can contain.
</para>
@@ -18689,7 +18699,8 @@ $.* ? (@ like_regex "^\\d+$")
<entry role="func_table_entry"><para role="func_signature">
<indexterm><primary>json_exists</primary></indexterm>
<function>json_exists</function> (
- <replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable> <optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
+ <replaceable>context_item</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional>,
+ <replaceable>path_expression</replaceable> <optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
<optional> { <literal>TRUE</literal> | <literal>FALSE</literal> |<literal> UNKNOWN</literal> | <literal>ERROR</literal> } <literal>ON ERROR</literal> </optional>)
</para>
<para>
@@ -18729,7 +18740,8 @@ ERROR: jsonpath array subscript is out of bounds
<entry role="func_table_entry"><para role="func_signature">
<indexterm><primary>json_query</primary></indexterm>
<function>json_query</function> (
- <replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable> <optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
+ <replaceable>context_item</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional>,
+ <replaceable>path_expression</replaceable> <optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
<optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional> </optional>
<optional> { <literal>WITHOUT</literal> | <literal>WITH</literal> { <literal>CONDITIONAL</literal> | <optional><literal>UNCONDITIONAL</literal></optional> } } <optional> <literal>ARRAY</literal> </optional> <literal>WRAPPER</literal> </optional>
<optional> { <literal>KEEP</literal> | <literal>OMIT</literal> } <literal>QUOTES</literal> <optional> <literal>ON SCALAR STRING</literal> </optional> </optional>
@@ -18806,7 +18818,8 @@ DETAIL: Missing "]" after array dimensions.
<entry role="func_table_entry"><para role="func_signature">
<indexterm><primary>json_value</primary></indexterm>
<function>json_value</function> (
- <replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable>
+ <replaceable>context_item</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional>,
+ <replaceable>path_expression</replaceable>
<optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
<optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> </optional>
<optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>DEFAULT</literal> <replaceable>expression</replaceable> } <literal>ON EMPTY</literal> </optional>
--
2.34.1
