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.