From: | Andrew Dunstan <andrew(at)dunslane(dot)net> |
---|---|
To: | Erik Rijkers <er(at)xs4all(dot)nl> |
Cc: | PostgreSQL Hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org> |
Subject: | Re: SQL/JSON documentation JSON_TABLE |
Date: | 2022-07-14 15:45:52 |
Message-ID: | 10c997db-9270-bdd5-04d5-0ffc1eefcdb7@dunslane.net |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-hackers |
On 2022-07-08 Fr 16:20, Andrew Dunstan wrote:
> On 2022-07-08 Fr 16:03, Erik Rijkers wrote:
>> Hi,
>>
>> Attached are a few small changes to the JSON_TABLE section in func.sgml.
>>
>> The first two changes are simple typos.
>>
>> Then there was this line:
>>
>> ----
>> context_item, path_expression [ AS json_path_name ] [ PASSING { value
>> AS varname } [, ...]]
>> ----
>>
>> those are the parameters to JSON_TABLE() so I changed that line to:
>>
>> ----
>> JSON_TABLE(context_item, path_expression [ AS json_path_name ] [
>> PASSING { value AS varname } [, ...]])
>> ----
>>
>> Some parts of the JSON_TABLE text strike me as opaque. For instance,
>> there are paragraphs that more than once use the term:
>> json_api_common_syntax
>>
>> 'json_api_common_syntax' is not explained. It turns out it's a relic
>> from Nikita's original docs. I dug up a 2018 patch where the term is
>> used as:
>>
>> ---- 2018:
>> JSON_TABLE (
>> json_api_common_syntax [ AS path_name ]
>> COLUMNS ( json_table_column [, ...] )
>> (etc...)
>> ----
>>
>> with explanation:
>>
>> ---- 2018:
>> json_api_common_syntax:
>> The input data to query, the JSON path expression defining the
>> query, and an optional PASSING clause.
>> ----
>>
>> So that made sense then (input+jsonpath+params=api), but it doesn't
>> now fit as such in the current docs.
>>
>> I think it would be best to remove all uses of that compound term, and
>> rewrite the explanations using only the current parameter names
>> (context_item, path_expression, etc).
>>
>> But I wasn't sure and I haven't done any such changes in the attached.
>>
>> Perhaps I'll give it a try during the weekend.
>>
>>
>>
>
> Thanks for this. If you want to follow up that last sentence I will try
> to commit a single fix early next week.
>
>
Here's a patch that deals with most of this. There's one change you
wanted that I don't think is correct, which I omitted.
cheers
andrew
--
Andrew Dunstan
EDB: https://www.enterprisedb.com
Attachment | Content-Type | Size |
---|---|---|
json-docs-fix.patch | text/x-patch | 3.7 KB |
From | Date | Subject | |
---|---|---|---|
Next Message | Justin Pryzby | 2022-07-14 16:26:18 | MERGE and parsing with prepared statements |
Previous Message | Tom Lane | 2022-07-14 15:27:24 | Re: EINTR in ftruncate() |