From 710905356c55388d28a7a9b2f90c3f8adf7cefac Mon Sep 17 00:00:00 2001 From: Thom Brown Date: Fri, 10 Jul 2026 19:21:54 +0300 Subject: [PATCH v2 4/4] Fix and polish JSON_TABLE documentation Correct the JSON_TABLE synopsis to place the ON ERROR clause after the PLAN clause, matching the grammar (the previous order could not be typed). Replace a dangling reference to json_path_specification with path_expression, the term the synopsis actually defines. Mark up the PLAN DEFAULT keywords with and fix a couple of wording issues. Also list OUTER before INNER consistently, including in the parent/child join description, where OUTER is the default. Author: Thom Brown Discussion: https://postgr.es/m/CAA-aLv5PGAFmAEpbhKQz8wppoOOTHfo-=LJb2sAB3974-9QtOw@mail.gmail.com --- doc/src/sgml/func/func-json.sgml | 42 ++++++++++++++++---------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/doc/src/sgml/func/func-json.sgml b/doc/src/sgml/func/func-json.sgml index 541d02d4a6e..0763ec81ed8 100644 --- a/doc/src/sgml/func/func-json.sgml +++ b/doc/src/sgml/func/func-json.sgml @@ -3640,8 +3640,8 @@ DETAIL: Missing "]" after array dimensions. against the row constructed from the columns specified in the parent COLUMNS clause to get the row in the final view. Child columns themselves may contain a NESTED PATH - specification thus allowing to extract data located at arbitrary nesting - levels. Columns produced by multiple NESTED PATHs at the + specification, thus allowing extraction of data located at arbitrary + nesting levels. Columns produced by multiple NESTED PATHs at the same level are considered to be siblings of each other and their rows after joining with the parent row are combined using UNION. @@ -3662,12 +3662,12 @@ DETAIL: Missing "]" after array dimensions. JSON_TABLE ( context_item, path_expression AS json_path_name PASSING { value AS varname } , ... COLUMNS ( json_table_column , ... ) - { ERROR | EMPTY ARRAY} ON ERROR PLAN ( json_table_plan ) | - PLAN DEFAULT ( { INNER | OUTER } , { CROSS | UNION } - | { CROSS | UNION } , { INNER | OUTER } ) + PLAN DEFAULT ( { OUTER | INNER } , { CROSS | UNION } + | { CROSS | UNION } , { OUTER | INNER } ) + { ERROR | EMPTY ARRAY} ON ERROR ) @@ -3853,7 +3853,7 @@ where json_table_column is: The NESTED PATH syntax is recursive, so you can go down multiple nested levels by specifying several NESTED PATH subclauses within each other. - It allows to unnest the hierarchy of JSON objects and arrays + It allows you to unnest the hierarchy of JSON objects and arrays in a single function invocation rather than chaining several JSON_TABLE expressions in an SQL statement. @@ -3886,7 +3886,7 @@ where json_table_column is: The optional json_path_name serves as an - identifier of the provided json_path_specification. + identifier of the provided path_expression. The path name must be unique and distinct from the column names. Each path name can appear in the PLAN clause only once. @@ -3920,33 +3920,33 @@ where json_table_column is: - INNER + OUTER - Use INNER JOIN, so that the parent row - is omitted from the output if it does not have any child rows - after joining the data returned by NESTED PATH. + Use LEFT OUTER JOIN, so that the parent row + is always included into the output even if it does not have any child rows + after joining the data returned by NESTED PATH, with NULL values + inserted into the child columns if the corresponding + values are missing. + + + This is the default option for joining columns with parent/child relationship. - OUTER + INNER - Use LEFT OUTER JOIN, so that the parent row - is always included into the output even if it does not have any child rows - after joining the data returned by NESTED PATH, with NULL values - inserted into the child columns if the corresponding - values are missing. - - - This is the default option for joining columns with parent/child relationship. + Use INNER JOIN, so that the parent row + is omitted from the output if it does not have any child rows + after joining the data returned by NESTED PATH. @@ -3991,7 +3991,7 @@ where json_table_column is: - PLAN DEFAULT ( OUTER | INNER , UNION | CROSS ) + PLAN DEFAULT ( { OUTER | INNER } , { UNION | CROSS } ) -- 2.50.1 (Apple Git-155)