Improved JSON_TABLE description based on Nikita Glukhov's input

Author: Liudmila Mantrova

doc/src/sgml/func-sqljson.sgml

@@ -902,8 +902,8 @@ INSERT INTO my_films VALUES (
        "director" : "Alfred Hitchcock" } ] },
    { "kind" : "thriller", "films" : [
      { "title" : "Vertigo",
-       "director" : "Hitchcock" } ] },
-   { "films" : [
+       "director" : "Alfred Hitchcock" } ] },
+   { "kind" : "drama", "films" : [
      { "title" : "Yojimbo",
        "director" : "Akira Kurosawa" } ] }
   ] }');
@@ -1339,7 +1339,7 @@ SELECT
 FROM my_films;
  json_query
 ------------
- ["comedy", "horror", "thriller"]
+ ["comedy", "horror", "thriller", "drama"]
 (1 row)
 
 
@@ -1402,7 +1402,7 @@ SELECT JSON_QUERY(jsonb '"aaa"', '$' RETURNING text OMIT QUOTES);
     
 
 JSON_TABLE (
- json_api_common_syntax [ AS json_path_name ]
+ json_api_common_syntax [ AS path_name ]
  COLUMNS ( json_table_column [, ...] )
  [ PLAN ( json_table_plan ) |
    PLAN DEFAULT ( { INNER | OUTER } [ , { CROSS | UNION } ]
@@ -1412,30 +1412,29 @@ JSON_TABLE (
 
 where json_table_column is:
 
-  { name type [ PATH json_path_specification ]
-          [ { ERROR | NULL | DEFAULT expression } ON EMPTY ]
-          [ { ERROR | NULL | DEFAULT expression } ON ERROR ]
-    | name type FORMAT json_representation
-          [ PATH json_path_specification ]
-          [ { WITHOUT | WITH { CONDITIONAL | [UNCONDITIONAL] } }
-            [ ARRAY ] WRAPPER ]
-          [ { KEEP | OMIT } QUOTES [ ON SCALAR STRING ] ]
-          [ { ERROR | NULL | EMPTY { ARRAY | OBJECT } } ON EMPTY ]
-          [ { ERROR | NULL | EMPTY { ARRAY | OBJECT } } ON ERROR ]
-    | NESTED PATH json_path_specification [ AS path_name ]
-          COLUMNS ( json_table_column [, ...] )
-    | name FOR ORDINALITY }
+    name type [ PATH json_path_specification ]
+        [ { ERROR | NULL | DEFAULT expression } ON EMPTY ]
+        [ { ERROR | NULL | DEFAULT expression } ON ERROR ]
+  | name type FORMAT json_representation
+        [ PATH json_path_specification ]
+        [ { WITHOUT | WITH { CONDITIONAL | [UNCONDITIONAL] } }
+          [ ARRAY ] WRAPPER ]
+        [ { KEEP | OMIT } QUOTES [ ON SCALAR STRING ] ]
+        [ { ERROR | NULL | EMPTY { ARRAY | OBJECT } } ON EMPTY ]
+        [ { ERROR | NULL | EMPTY { ARRAY | OBJECT } } ON ERROR ]
+  | NESTED PATH json_path_specification [ AS path_name ]
+        COLUMNS ( json_table_column [, ...] )
+  | name FOR ORDINALITY
 
 json_table_plan is:
 
-    path_name { OUTER | INNER | CROSS | UNION }
-  { path_name | ( nested_plan ) }
+    path_name [ { OUTER | INNER } json_table_plan_primary ]
+  | json_table_plan_primary { UNION json_table_plan_primary } [...]
+  | json_table_plan_primary { CROSS json_table_plan_primary } [...]
 
-nested_plan is:
+json_table_plan_primary is:
 
-    path_name { OUTER | INNER } { path_name | ( nested_plan ) }
-  | { path_name | ( nested_plan ) } 
-    { { UNION | CROSS } { path_name | ( nested_plan ) } }[...]
+    path_name | ( json_table_plan )
 
 
     
@@ -1453,9 +1452,9 @@ where json_table_column is:
 
      
       Taking JSON data as input, JSON_TABLE uses
-      a path expression to extract a part of the provided input that
+      a path expression to extract a part of the provided data that
       will be used as a row pattern for the
-      contructed view. Each SQL/JSON item at the top level of the row pattern serves
+      constructed view. Each SQL/JSON item at the top level of the row pattern serves
       as the source for a separate row in the constructed relational view.
      
 
@@ -1467,15 +1466,19 @@ where json_table_column is:
       the row pattern, extracts a JSON item, and returns it as a
       separate SQL value for the specified column. If the required value
       is stored in a nested level of the row pattern, it can be extracted
-      using the NESTED PATH subclause.
+      using the NESTED PATH subclause. Joining the
+      columns returned by NESTED PATH can add multiple
+      new rows to the constructed view. Such rows are called
+      child rows, as opposed to the parent row
+      that generates them.
      
 
      
       The rows produced by JSON_TABLE are laterally
       joined to the row that generated them, so you do not have to explicitly join
-      the constructed view with the original table. You can specify
-      how to handle empty rows returned from the nested levels of
-      the row pattern using the PLAN clause.
+      the constructed view with the original table holding JSON
+      data. Optionally, you can specify how to join the columns returned
+      by NESTED PATH using the PLAN clause.
      
 
     
@@ -1502,18 +1505,16 @@ where json_table_column is:
 
    
     
-     COLUMNS( { json_table_column } [, ...] ) 
+     COLUMNS( { json_table_column } [, ...] )
     
     
 
     
      The COLUMNS clause defining the schema of the
-     constructed table. In this clause, you must specify all the columns
-     to be filled with SQL/JSON items returned by JSON_TABLE.
-     You must provide the name and type for each column. Only scalar
-     types are supported.
+     constructed view. In this clause, you must specify all the columns
+     to be filled with SQL/JSON items. Only scalar column types are supported.
      The json_table_column
-     expression can use one of the following syntax options:
+     expression has the following syntax variants:
     
 
   
@@ -1601,14 +1602,13 @@ where json_table_column is:
      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
-     in a single function invocation rather than chaining several JSON_TABLE
-     expressions in an SQL statement.
+     in a single function invocation rather than chaining several
+     JSON_TABLE expressions in an SQL statement.
     
 
     
      You can use the PLAN clause to define how
-     to handle empty rows when joining the columns returned by
-     NESTED PATH clauses.
+     to join the columns returned by NESTED PATH clauses.
     
     
    
@@ -1622,7 +1622,8 @@ where json_table_column is:
     
      Adds an ordinality column that provides sequential row numbering.
      You can have only one ordinality column per table. Row numbering
-     is 1-based.
+     is 1-based. For child rows that result from the NESTED PATH
+     clauses, the parent row number is repeated.
     
     
    
@@ -1641,28 +1642,31 @@ where json_table_column is:
      The optional json_path_name serves as an
      identifier of the provided json_path_specification.
      The path name must be unique and cannot coincide with column names.
-     You must specify the path name when using the PLAN
-     clause.
+     When using the PLAN clause, you must specify the names
+     for all the paths, including the row pattern. Each path name can appear in
+     the PLAN clause only once.
     
     
    
 
    
     
-     PLAN json_table_plan
+     PLAN ( json_table_plan )
     
     
 
     
-     Defines how to handle empty rows when joining the columns
-     returned by NESTED PATH clauses.
+     Defines how to join the data returned by NESTED PATH
+     clauses to the constructed view.
     
     
-     In relation to the columns returned directly from the row expression
-     or by the NESTED PATH clause of a higher level, nested columns
-     are considered to be child columns.
-     Each NESTED PATH clause can include
-     several columns, which are called sibling columns.
+     Each NESTED PATH clause can generate one or more
+     columns, which are considered to be siblings
+     to each other. In relation to the columns returned directly from the row
+     expression or by the NESTED PATH clause of a
+     higher level, these columns are child columns.
+     Sibling columns are always joined first. Once they are processed,
+     the resulting rows are joined to the parent row.
     
     
      To join columns with parent/child relationship, you can use:
@@ -1675,9 +1679,9 @@ where json_table_column is:
     
 
     
-     Use INNER JOIN, so that the output includes
-     only those rows that have the corresponding values in both
-     columns.
+     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.
     
     
    
@@ -1689,10 +1693,11 @@ where json_table_column is:
     
 
     
-     Use LEFT OUTER JOIN, so that all rows of the
-     left-hand column must be included into the output at least once, while the rows of the right-hand
-     column are only included if they have a match in the left column. If the corresponding
-     value is missing from the right column, the NULL value is inserted into the right column.
+     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.
@@ -1713,10 +1718,9 @@ where json_table_column is:
     
 
     
-     Use FULL OUTER JOIN, so that all rows of the
-     left-hand and the right-hand columns are included into the output, with
-     NULL values inserted into either of the columns if the corresponding value
-     is missing.
+     Use FULL OUTER JOIN ON FALSE, so that both parent and child
+     rows are included into the output, with NULL values inserted
+     into both child and parrent columns for all missing values.
     
     
      This is the default option for joining sibling columns.
@@ -1745,11 +1749,17 @@ where json_table_column is:
 
    
     
-     PLAN DEFAULT
+     PLAN DEFAULT ( option [, ... ] )
     
     
      
-      Redefines the default behavior for all columns at once.
+      Overrides the default joining plans. The INNER and
+      OUTER options define the joining plan for parent/child
+      columns, while UNION and CROSS
+      affect the sibling columns. You can override the default plans for all columns at once.
+      Even though the path names are not incuded into the PLAN DEFAULT
+      clause, they must be provided for all the paths to conform to
+      the SQL/JSON standard.
      
     
    
@@ -1779,8 +1789,36 @@ SELECT jt.* FROM
  1  | comedy   | The Dinner Game  | Francis Veber
  2  | horror   | Psycho           | Alfred Hitchcock
  3  | thriller | Vertigo          | Hitchcock
- 4  | (null)   | Yojimbo          | Akira Kurosawa
+ 4  | drama    | Yojimbo          | Akira Kurosawa
  (5 rows)
+
+     
+
+     
+      Find a director that has done films in two different genres:
+
+SELECT
+  director1 AS director, title1, kind1, title2, kind2
+FROM
+  my_films,
+  JSON_TABLE ( js, '$.favorites' AS favs COLUMNS (
+    NESTED PATH '$[*]' AS films1 COLUMNS (
+      kind1 text PATH '$.kind',
+      NESTED PATH '$.films[*]' AS film1 COLUMNS (
+        title1 text PATH '$.title',
+        director1 text PATH '$.director')
+    ),
+    NESTED PATH '$[*]' AS films2 COLUMNS (
+      kind2 text PATH '$.kind',
+      NESTED PATH '$.films[*]' AS film2 COLUMNS (
+        title2 text PATH '$.title',
+        director2 text PATH '$.director'
+      )
+    )
+   )
+   PLAN (favs OUTER ((films1 INNER film1) CROSS (films2 INNER film2)))
+  ) AS jt
+ WHERE kind1 > kind2 AND director1 = director2;