Add docs for json_table

[michaeleby1]

Description

Additional context and related issues

Replaces #20338

First released in 435 with #18017
Fix for being able to test it at all is in 436 - #20122

Release notes

(x) This is not user-visible or is docs only, and no release notes are required.

[kasiafi]

@michaeleby1 great job! It will be very useful to have json_table finally documented.

I left a few comments.

Also, I'm not sure if it's clear to the reader how to use json_table in the context of a query. json_table is a lateral relation, and typically it will be used as part of a join:

SELECT * 
FROM orders, json_table(...)

It clarifies where the json_input and the PASSING parameters come from.

[kasiafi]

Hi @michaeleby1 and thank you for applying the comments.

There is one more issue regarding the taxonomy.
In SQL, json_table is not a table function. It is a clause, similar to lateral or unnest. It does not follow the syntactic rules for table functions.
As you noticed, json_table is indeed implemented using the table functions framework, but that should be considered an implementation detail.

That said, I wonder where json_table belongs in the docs.
I think we can keep it in the functions/json section but reword so that we call it a clause, not a table function. Keeping it there would be convenient to the reader.
Also, json_table should be mentioned in the SELECT section, along with unnest and lateral.

[michaeleby1]

@kasiafi I removed references to json_table as a "table function."

When you say "json_table should be mentioned in the SELECT section," can you confirm if you mean that you'd like me add a new section for json_table to select.md?

[kasiafi]

can you confirm if you mean that you'd like me add a new section for json_table to select.md?

@michaeleby1 yes, that is what I meant. json_table should be mentioned somewhere next to unnest or lateral. The mention does not have to be very verbose. A one-sentence summary and a link to the full description in functions/json.md should suffice.

[michaeleby1]

json_table should be mentioned somewhere next to unnest or lateral. The mention does not have to be very verbose. A one-sentence summary and a link to the full description in functions/json.md should suffice.

I added a short description to select.md

[kasiafi]

LGTM

@mosabua do you want to take a final look?

[mosabua]

Sure .. let me give it a final review

[mosabua]

Given that the next two examples use and empty array of input and the whole syntax is not really explained I think we either have to update these now .. or revisit in a follow up PR (I prefer that so we can ship this PR) .. but as it stands I think the two examples are basically a headscratcher for the reader and barely useful unless you know and understand already.

[mosabua]

Great job .. just a couple of small things and then we probably need a follow up PR or two to complete this.

[mosabua]

Let ship this!