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

On Thu, Jun 20, 2024 at 1:03 AM David G. Johnston
<david(dot)g(dot)johnston(at)gmail(dot)com> wrote:
> On Wed, Jun 19, 2024 at 8:29 AM jian he <jian(dot)universality(at)gmail(dot)com> wrote:
>>
>> On Mon, Jun 17, 2024 at 9:05 PM Chapman Flack <jcflack(at)acm(dot)org> wrote:
>> >
>> > Hi,
>> >
>> > On 06/17/24 02:43, Amit Langote wrote:
>> > > <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.
>> >
>> > Reading this message in conjunction with [0] makes me think that we are
>> > really talking about a function that takes a first parameter of type jsonb,
>> > and behaves exactly that way (so any cast required is applied by the system
>> > ahead of the call). Under those conditions, this seems like an unusual
>> > sentence to add in the docs, at least until we have also documented that
>> > tan's argument can be of any type that can be cast to double precision.
>> >
>>
>> I guess it would be fine to add an unusual sentence to the docs.
>>
>> imagine a function: array_avg(anyarray) returns anyelement.
>> array_avg calculate an array's elements's avg. like
>> array('{1,2,3}'::int[]) returns 2.
>> but array_avg won't make sense if the input argument is a date array.
>> so mentioning in the doc: array_avg can accept anyarray, but anyarray
>> cannot date array.
>> seems ok.
>
>
> There is existing wording for this:
>
> "The expression can be of any JSON type, any character string type, or bytea in UTF8 encoding."
>
> If you add this sentence to the paragraph the link that already exists, which simply points the reader to this sentence, becomes redundant and should be removed.

I've just posted a patch in the other thread [1] to restrict
context_item to be of jsonb type, which users would need to ensure by
adding an explicit cast if needed. I think that makes this
clarification unnecessary.

> As for table 9.16.3 - it is unwieldy already. Lets try and make the core syntax shorter, not longer. We already have precedence in the subsequent json_table section - give each major clause item a name then below the table define the syntax and meaning for those names. Unlike in that section - which probably should be modified too - context_item should have its own description line.

I had posted a patch a little while ago at [1] to render the syntax a
bit differently with each function getting its own syntax synopsis.
Resending it here; have addressed Jian He's comments.

--
Thanks, Amit Langote
[1] https://www.postgresql.org/message-id/CA%2BHiwqF2Z6FATWQV6bG9NeKYf%3D%2B%2BfOgmdbYc9gWSNJ81jfqCuA%40mail.gmail.com