JSON Containment, JSONPath, and Transforms are means to work with JSONB but not the actual datatype itself. Doc should be split into
1) Data type - how do declare, indexing, considerations when using it...
2) Ways to work with the data type - functions, containment, JSONPath...
These can be separate pages or on the same page but they need to be logically and physically separated
Thank you so much for putting so much work into the documentation! Please let me know if there are others way you would like to me help with the doc.
On Mon, Sep 23, 2019 at 1:03 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Alexander Korotkov <a.korotkov@postgrespro.ru> writes:
> > On Sun, Sep 22, 2019 at 9:18 PM Jeff Janes <jeff.janes@gmail.com> wrote:
> > Currently description of jsonpath is divided between datatypes section
> > and functions and operators section. And yes, this looks cumbersome.
>
> Agreed, but ...
>
> > I think we should move the whole description to the one section.
> > Probably we should move jsonpath description to datatypes section
> > (assuming jsonpath is a datatype) leaving functions and operators
> > section with just SQL-level functions and operators. What do you
> > think?
>
> ... I don't think that's an improvement. We don't document detailed
> behavior of a datatype's functions in datatype.sgml, and this seems
> like it would be contrary to that layout. If anything, I'd merge
> the other way, with only a very minimal description of jsonpath
> (perhaps none?) in datatype.sgml.
>
> While we're whining about this, I find it very off-putting that
> the jsonpath stuff was inserted in the JSON functions section
> ahead of the actual JSON functions. I think it should have
> gone after them, because it feels like a barely-related interjection
> as it stands. Maybe there's even a case that it should be
> its own <sect1>, after the "functions-json" section.
Yes, it think moving jsonpath description to own <sect1> is a good
idea. But I still think we should have complete jsonpath description
in the single place. What about joining jsonpath description from
both datatypes section and functions and operators section into this
<sect1>, leaving datatypes section with something very brief?
------
Alexander Korotkov
Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company