peter-toth commented on code in PR #57724:
URL: https://github.com/apache/spark/pull/57724#discussion_r3713210374
##########
docs/sql-ref-syntax-dml-insert-table.md:
##########
@@ -88,6 +97,14 @@ INSERT [ WITH SCHEMA EVOLUTION ] INTO [ TABLE ]
table_identifier [ BY NAME ] REP
#### Insert Into
+##### Insert Using Dynamic Table Options
Review Comment:
**Finding 1.** Agreed, and there is more than ordering here: `students` is
created *inside* the next example. `##### Single Row Insert Using a VALUES
Clause` at `docs/sql-ref-syntax-dml-insert-table.md:108` holds the `CREATE
TABLE students (...) USING PARQUET PARTITIONED BY (student_id INT)`, and every
later example in the `#### Insert Into` group shows a `SELECT * FROM students`
whose rows accumulate from the ones before it. So as placed, this example
inserts into a table that does not exist yet.
It also inserts that next example's exact row -- `('Amy Smith', '123 Park
Ave, San Jose', 111111)` -- so a reader working down the page ends up with two
Amy Smith rows and the single-row output shown at `:121` no longer matches.
So moving it to the end of the `#### Insert Into` group fixes both only if
the row changes too: by that point `students` already holds four rows, so it
needs its own distinct row, and ideally the resulting `SELECT *` like its
neighbours have.
##########
docs/sql-ref-syntax-dml-merge-into.md:
##########
@@ -149,6 +158,17 @@ SELECT * FROM source;
+--+------+-----+
```
+#### Merge Using Dynamic Table Options
Review Comment:
**Finding 3.** Same conclusion, plus two things that moving it does not fix.
It is `#### Update Matched Rows and Insert New Rows`
(`docs/sql-ref-syntax-dml-merge-into.md:172`) verbatim with two `WITH (...)`
clauses added -- same target, same source, same `ON`, same two `WHEN` clauses.
And it is the only `####` example on the page without a result block: `:181`,
`:204`, `:224` and `:242` all show the resulting `SELECT * FROM target`, and
the preamble at `:138-139` promises "Each example starts from this initial
state", which only means something if the end state is shown.
The cheapest fix that keeps the page's shape is to drop the standalone
example and add the two `WITH (...)` clauses to `#### Update Matched Rows and
Insert New Rows` itself -- the options do not change its output, so its
existing result block stays correct and the reader sees the clause in context.
If you would rather keep it separate, it needs a statement that differs from
its neighbour and its own result block.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
