Re: Patch: Improve Boolean Predicate JSON Path Docs - Mailing list pgsql-hackers

From Erik Wienhold
Subject Re: Patch: Improve Boolean Predicate JSON Path Docs
Date
Msg-id j2sqxxa2tyembatdd6yktv2mwp2mww7mx4wtng2j7vovsshzan@oesa2vtzalde
Whole thread Raw
In response to Re: Patch: Improve Boolean Predicate JSON Path Docs  ("David Wheeler" <david@justatheory.com>)
Responses Re: Patch: Improve Boolean Predicate JSON Path Docs
List pgsql-hackers
On 2023-10-20 15:49 +0200, David Wheeler wrote:
> On Oct 19, 2023, at 23:49, Erik Wienhold <ewie@ewie.name> wrote:
> 
> > I don't even know what that represents, probably not some fancy file
> > compression.

That's an AppleSingle file according to [1][2].  It only contains the
resource fork and file name but no data fork.

> Oh, weird. Trying from a webmail client instead.

Thanks.

> +        Does JSON path return any item for the specified JSON value? Use only
> +        SQL-standard JSON path expressions, not
> +        <link linkend="boolean-predicate-path-expressions">predicate check
> +        expressions.</link>

Any reason for calling it "predicate check expressions" (e.g. the link
text) and sometimes "predicate path expressions" (e.g. the linked
section title)?  I think it should be named consistently to avoid
confusion and also to simplify searching.

> +        Returns the result of a JSON path
> +        <link linkend="boolean-predicate-path-expressions">predicate
> +        check</link> for the specified JSON value. If the result is not Boolean,
> +        then <literal>NULL</literal> is returned. Use only with
> +        <link linkend="boolean-predicate-path-expressions">predicate check
> +        expressions.</link>

Linking the same section twice in the same paragraph seems excessive.

> +<prompt>=></prompt> <userinput>select jsonb_path_query(:'json', '$.track.segments');</userinput>
> +select jsonb_path_query(:'json', '$.track.segments');

Please remove the second SELECT.

> +<prompt>=></prompt> <userinput>select jsonb_path_query(:'json', 'strict
$.track.segments[0].location');</userinput>
> + jsonb_path_query
> +-------------------
> + [47.763, 13.4034]

Strict mode is unnecessary to get that result and I'd omit it because
the different modes are not introduced yet at this point.

> +<prompt>=></prompt> <userinput>select jsonb_path_query(:'json', 'strict $.track.segments.size()');</userinput>
> + jsonb_path_query
> +------------------
> + 2

Strict mode is unnecessary here as well.

> +     using the lax mode. To avoid surprising results, we recommend using
> +     the <literal>.**</literal> accessor only in the strict mode. The

Please change to "in strict mode" (without "the").

[1] https://www.rfc-editor.org/rfc/rfc1740.txt
[2] https://web.archive.org/web/20180311140826/http://kaiser-edv.de/documents/AppleSingle_AppleDouble.pdf

-- 
Erik



pgsql-hackers by date:

Previous
From: Tom Lane
Date:
Subject: Re: Show version of OpenSSL in ./configure output
Next
From: Andres Freund
Date:
Subject: Re: Casual Meson fixups