json_populate_record
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/12/functions-json.html
Description:
It is not clear what the parameter `base` means
On Thursday, August 13, 2020, PG Doc comments form <noreply@postgresql.org>
wrote:
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/12/functions-json.html
Description:It is not clear what the parameter `base` means
I agree there is room for improvement here. The referenced note does’t use
the term “base” which making finding the correct note among the various
possibilities more difficult. The example seems sufficiently illustrative
though. Those functions convert json to SQL composite types. You need to
pass in which composite type to convert to. That is the “base” type. One
normally does this by casting SQL null to the desired composite type;
usually one associated with an existing table.
David J.
"David G. Johnston" <david.g.johnston@gmail.com> writes:
On Thursday, August 13, 2020, PG Doc comments form <noreply@postgresql.org>
wrote:It is not clear what the parameter `base` means
I agree there is room for improvement here. The referenced note does’t use
the term “base” which making finding the correct note among the various
possibilities more difficult.
Yeah, that used to be pretty unreadable. I think the reformatting of
these tables that I did for v13 helps a lot, though:
https://www.postgresql.org/docs/devel/functions-json.html
regards, tom lane
Thank you for those helpful observations.
“The example seems sufficiently illustrative though.”
I'm not sure what other readers have experienced, but I can say I definitely tried to understand the example, and I wasn't able to piece together what it means. Namely, I had no idea what `null::myrowtype` was supposed to mean. (Not to mention that I wasn't familiar with composite types at all)
“One normally does this by casting SQL null to the desired composite type; usually one associated with an existing table.”
I literally learned this while reading your reply! It would have been really helpful for that to be included in the docs.
One side note: The "Note" layout to expand on functions seems suboptimal to me. It is not easy to discern among the notes which belongs to which. It would probably be helpful to have better fledged sections under the form (function_name => more notes).
"David G. Johnston" <david.g.johnston@gmail.com> wrote:
“On Thursday, August 13, 2020, PG Doc comments form <noreply@postgresql.org> wrote:
“The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/12/functions-json.html
Description:
It is not clear what the parameter `base` means”
I agree there is room for improvement here. The referenced note does’t use the term “base” which making finding the correct note among the various possibilities more difficult. The example seems sufficiently illustrative though. Those functions convert json to SQL composite types. You need to pass in which composite type to convert to. That is the “base” type. One normally does this by casting SQL null to the desired composite type; usually one associated with an existing table.
David J.”
On Thu, Aug 13, 2020 at 5:42 PM Jonathan Allard <jonathan.allard@hey.com>
wrote:
One side note: The "Note" layout to expand on functions seems suboptimal
to me. It is not easy to discern among the notes which belongs to which. It
would probably be helpful to have better fledged sections under the form
(function_name => more notes).
As Tom mentions nearby this has been significantly improved upon in the
upcoming version. While v13 is still in Beta you will find that for
reference tables its documentation is far superior. And given the nature
of these changes, i.e., non-bugfix, enhancements to older versions are not
likely to be forthcoming for this particular observation.
David J.