Re: Patch: Improve Boolean Predicate JSON Path Docs

On Jan 24, 2024, at 16:32, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> "David E. Wheeler" <david(at)justatheory(dot)com> writes:
>
>> In any event, something to do with @@, perhaps to have some compatibility with `jsonb @> jsonb`? I don’t know why @@ was important to have.
>
> Yeah, that's certainly under-explained. But it seems like I'm not
> getting traction for the idea of changing the behavior, so let's
> go back to just documenting it.

Curious about those discussions. On the one hand I find the distinction between the two behaviors to be odd, and to produce unexpected results when they’re not used in the proper context.

It’s reminds me of the Perl idea of context, where functions behave differently in scalar and list context, and if you expect list behavior on scalar context you’re gonna get a surprise. This is a bit of a challenge for those new to the language, as they’re not necessarily aware of the context.

> I spent some time going over your
> text and also cleaning up nearby shaky English, and ended with v8
> attached. I'd be content to commit this if it looks good to you.

This looks very nice, thank you. A couple of comments.

> + <para>
> + Predicate check expressions are required in the
> + <literal>@@</literal> operator (and the
> + <function>jsonb_path_match</function> function), and should not be used
> + with the <literal>@?</literal> operator (or the
> + <function>jsonb_path_exists</function> function).
> + </para>
> + </note>
> + </sect4>

I had this bit here:

<para>
Conversely, non-predicate <type>jsonpath</type> expressions should not be
used with the <literal>@@</literal> operator (or the
<function>jsonb_path_match</function> function).
</para>

I think it’s important to let people know what the difference is in the behavior of the two forms, in every spot it’s likely to come up. SQL-standard JSON Path expressions should never be used in contexts (functions, operators) only designed to work with predicate check expressions, and the docs should say so IMO.

> <para>
> - The lax mode facilitates matching of a JSON document structure and path
> - expression if the JSON data does not conform to the expected schema.
> + The lax mode facilitates matching of a JSON document and path
> + expression when the JSON data does not conform to the expected schema.

What do you think of also dropping the article from all the references to “the strict mode” or “the lax mode”, to make them “strict mode” and “lax mode”, respectively?

Thanks for the review!

Best,

David