From 3dc8da62f9136a66d921f817abb06fabc601d573 Mon Sep 17 00:00:00 2001 From: jackfoxy Date: Mon, 29 May 2023 13:31:01 -0700 Subject: [PATCH] merge doc --- docs/ref-ch01-introduction.md | 2 + docs/ref-ch06-merge.md | 223 +++++++++++++++++++--------------- docs/ref-ch07-transform.md | 10 +- 3 files changed, 135 insertions(+), 100 deletions(-) diff --git a/docs/ref-ch01-introduction.md b/docs/ref-ch01-introduction.md index 754dd12..4da0d95 100755 --- a/docs/ref-ch01-introduction.md +++ b/docs/ref-ch01-introduction.md @@ -127,3 +127,5 @@ Similarly `*` as the output of `DELETE`, `INSERT`, `MERGE` creates a pass-thru v 10. Custom types and support for arbitrary noun columns - TBD 11. Pivoting and windowing will be implemented in a future release. 12. `` not implemented in parser and caching is TBD +13. `` pre-built library of ``, TBD. +14. Option in `` to replicate ``'s ``s and/or unique indices when new `` created. diff --git a/docs/ref-ch06-merge.md b/docs/ref-ch06-merge.md index dcceca2..d1f675e 100755 --- a/docs/ref-ch06-merge.md +++ b/docs/ref-ch06-merge.md @@ -1,37 +1,35 @@ # MERGE -`MERGE` provides a single SQL statement that can conditionally `INSERT`, `UPDATE` or `DELETE` rows, a task that would otherwise require multiple procedural language statements. It modifies the content of the ``, using data from the `` and static `` sources. +`MERGE` is a statement that conditionally performs `INSERT`, `UPDATE`, or `DELETE` operations. It modifies the content of the ``, merging data from the `` and static `` sources. -First, the MERGE command performs a join from `` to `` using `ON ` producing zero or more candidate change rows. +First, the MERGE command performs an outer join from `` to `` using `ON ` producing candidate change rows. -For each candidate change row, the status of `MATCHED` or `NOT MATCHED` is set just once. +For each candidate change row, the `MATCHED` or `NOT MATCHED` status is determined. If applicable, `NOT MATCHED` on `` or `` is set. -If applicable, `NOT MATCHED` on `` or `` is set once. +Finally, for each candidate change row, the first `WHEN` clause under the applicable `MATCHED`/`NOT MATCHED` condition is executed. -Finally for each candidate change row the first `WHEN` under the applicable `MATCHED`/`NOT MATCHED` clause is executed. +A `WHEN` clause without `AND ` implies unconditional execution. Subsequent `WHEN` clauses for the same target/source matching condition are not allowed. -A `WHEN` clause with no `AND ` implies unconditional execution. There can be no following `WHEN` clauses for that target/source matching condition. +If no `WHEN` clause evaluates as true, the target row remains unchanged, which is equivalent to specifying `NOP`. -When no `WHEN` clause evaluates as true the state remains unchanged (same as specifying `NOP`). +`MERGE` actions have the same effect as the standard `UPDATE`, `INSERT`, or `DELETE` commands. -MERGE actions have the same effect as `UPDATE`, `INSERT`, or `DELETE` commands of the same names. +`MERGE` can update the contents of an existing target `
`, produce a new `
`, or produce a new virtual ``. -`MERGE` can either update the contents of an existing `
`, produce a new `
`, or produce a new (virtual) ``. +When `MERGE INTO` is specified or implied, `` must be a base `
` and contents are updated in place. `PRODUCING NEW` may not be specified. -When `MERGE INTO` is specified or implied `` must be a base `
` and contents are updated in place. `PRODUCING NEW` may not be specified. +When `MERGE FROM` is specified, `PRODUCING NEW` must also be specified. `` can be a base `
` or any virtual table (i.e. `` or `PASS-THRU` ``). -When `MERGE FROM` is specified then `PRODUCING NEW` must also be specified. `` can be `
` or any virtual table (i.e. `` or pass-thru ``). +If `` is specified, it will be created as a new `
` and populated in the same way as when `` is updated with `MERGE INTO`. -If `` is specfied, it will be created as a new `
` and populated the same as when `` is updated with `MERGE INTO`. +The output ``'s row type will correspond to the row type of ``. And its primary index (in the case when `` is produced) will correspond to the primary index of ``. The ``'s ``s are not replicated. -The output ``'s row type will correspond to the row type of ``. And its primary index (in the case when `` is produced) will correspond to the primary index of ``. - -If the resulting virtual-table row type is a union type, then the output must be a virtual-table pass-thru, not an update to `` or creation of ``. +If the resulting virtual-table row type is a union type, then the output must be a virtual-table `PASS-THRU`, not an update to `` or creation of `` as base `
`. ``` ::= MERGE [ { INTO | FROM } ] [ [ AS ] ] - [ PRODUCING NEW [ [ AS ] ] ] + [ PRODUCING NEW ] USING [ [ AS ] ] [ [ SCALAR ] [ ,...n ] ] [ ON ] @@ -60,6 +58,25 @@ If the resulting virtual-table row type is a union type, then the output must be } ``` +Specifies the update or delete action that is applied to all rows of `` that don't match the rows returned by `` ON ``, and which satisfy any additional predicate. + +**``** + +Identifies column in ``. Each column may be referenced once. + +**``** + +Aura must match corresponding aura in ``. + +**DELETE** + +Delete the matched target row. + +**NOP** + +No operation performed. + + ``` ::= INSERT [ ( [ ,...n ] ) ] @@ -67,6 +84,21 @@ If the resulting virtual-table row type is a union type, then the output must be | NOP ``` +**``** + +Identifies column in ``. Each column may be referenced once. + +**``** + +Aura must match corresponding aura in ``. + +The count out `INSERT` columns and `VALUES` must match. + +**NOP** + +No operation performed. + + ## API ``` +$ merge @@ -82,117 +114,112 @@ If the resulting virtual-table row type is a union type, then the output must be == ``` -## TO DO: evaluate decision tree of target/source singleton/union type - ## Arguments -**`[ { INTO | FROM } ] [ [ AS ] \ ]`** -`` An alternative name to reference ``. -* If `{ INTO | FROM }` is not specified default to `INTO`. -* If `` is a virtual-table -- any `` other than a base-table, i.e. qualified ``, ``, `*`, or `( column-1 [,...column-n] )` -- then `FROM` is required. -* `INTO` must not accompany `PRODUCING NEW` argument. -* `FROM` must accompany `PRODUCING NEW` argument. -* `` is the table, view, or CTE against which the data rows from `` are matched based on ``. -* If `` is not specifiec, `` must have the same row type as `` and matching requires every column in a given subtype. -* If `INTO` is specified then `` is a base-table target of any and all insert, update, or delete operations specified by the `WHEN` clauses. -* If `FROM` is specified then any insert, update, or delete operations specified by the `WHEN` clauses as well as matched but otherwise unaffected target table rows produce a new `` as specified by the `PRODUCING NEW` clause. +**`[ { INTO | FROM } ] [ [ AS ] ]`** +`` is alternative name to reference `` in `WHEN` clauses and predicates. -**`[ PRODUCING NEW [ [ AS ] \ ] ]`** -`` An alternative name to reference ``. +If `{ INTO | FROM }` is not specified, `INTO` is the default. -* Required when `FROM` specified. -* Prohibited when `INTO` implied or specified. -* If `` has a row type which is a union type, `` cannot be a base-table. +If `INTO` is specified (or implied) then `` is a base-table -**`[ WITH [ ,...n ] ]`** -Specifies the temporary named result set or view, also known as common table expression, that's defined within the scope of the MERGE statement. The result set derives from a simple query and is referenced by the MERGE statement. +If `` is a virtual-table -- any `` other than a base-table, i.e. qualified ``, ``, `*`, or `( column-1 [,...column-n] )` -- then `FROM` is required. -**`USING [ [ AS ] \ ]`** -`` An alternative name to reference ``. +`INTO` must not accompany `PRODUCING NEW` argument. -Specifies the data source that's matched with the data rows in `` joining on ``. -`` can be a remote table or a derived table that accesses remote tables. +`FROM` must accompany `PRODUCING NEW` argument. + +`` is the table, view, or CTE against which the data rows from `` are matched based on ``. + +If `FROM` is specified, any `INSERT`, `UPDATE`, or `DELETE` operations specified by the `WHEN` clauses, as well as matched but otherwise unaffected target table rows, produce a new `` as specified by the `PRODUCING NEW` clause. + +**`[ PRODUCING NEW ` ]** + +Required when `FROM` is specified. + +Prohibited when `INTO` is specified or implied. + +If `` has the syntax of a qualified `
`, it cannot already exist. + +If `` has a row type which is a union type, `` cannot be a base `
`. + +**`USING [ [ AS ] ]`** + +Specifies the data source that is matched with the data rows in `` joining on ``. `` can be any ``. + +`` is an alternative name to reference `` in `WHEN` clauses and predicates. -<`table-source>` can be a derived table that uses the Transact-SQL table value constructor to construct a table by specifying multiple rows. **`[ [ SCALAR ] [ ,...n ] ]`** TBD **`ON `** -Specifies the conditions on which `` joins with ``, determining the matching. -* Any valid `` not resulting in cartesian join. -* Resolves for any row sub-type between the target and source. -* If not specified, source and target must share row type and matching implies rows equal by value. +Specifies the conditions on which `` joins with ``, determining the matching and can be any valid `` not resulting in cartesian join. + +If `` is not specified, source and target must share row type and matching implies rows equal by value. + +If `` does not resolve for any row sub-type between the target and source it potentially creates `NOT MATCHED` conditions `BY TARGET` and `BY SOURCE` on rows that otherwise are equal by value. + **`[ WHEN MATCHED [ AND ] THEN ] [ ...n ]`** -Specifies that all rows of *target-table, which join the rows returned by `` ON `` or the implied join when `ON` predicate not present, and satisfy ``, result in some action, possibly resulting in state change, according to the `` clause. -* If two or more `WHEN` clauses are specified only the last clause may be unaccompanied by `AND `. -* The first `` evaluating to true determines the `` action. -* `WHEN THEN ` clause without `AND ` implies unconditionally apply the `` action. +Specifies that all rows of ``, which join the rows returned by `` ON `` or the implied join when `ON` predicate not present, and satisfy `` (when present), result in some action according to the `` clause. + +`WHEN MATCHED` clause without `AND ` implies unconditionally apply the `` action. + +If two or more `WHEN MATCHED` clauses are specified only the last clause may be unaccompanied by `AND `. + +The first `` evaluating to true determines the `` action. + +If there is no unconditional `` action, it is the same as specifying `NOP` for unconditional action. + **`[ WHEN NOT MATCHED [ BY TARGET ] [ AND ] THEN ] [ ...n ]`** -Specifies that a row is inserted into target-table for every row returned by `` ON `` that doesn't match a row in target-table, but satisfies an additional search condition, if present. The values to insert are specified by the `` clause. The MERGE statement can have only one WHEN NOT MATCHED [ BY TARGET ] clause. + +Specifies the action on `` for every row returned by `` ON `` that doesn't match a row in target-table, but satisfies ``, if present. The action to take is specified by the `` clause. + +`WHEN NOT MATCHED BY TARGET` clause without `AND ` implies unconditionally apply the `` action. + +If two or more `WHEN NOT MATCHED BY TARGET` clauses are specified only the last clause may be unaccompanied by `AND `. + +The first `` evaluating to true determines the `` action. + +If there is no unconditional `` action, it is the same as specifying `NOP` for unconditional action. **`WHEN NOT MATCHED BY SOURCE [ AND ] THEN `** -Specifies that all rows of *target-table, which don't match the rows returned by `` ON ``, and that satisfy any additional search condition, are updated or deleted according to the `` clause. -The MERGE statement can have at most two WHEN NOT MATCHED BY SOURCE clauses. If two clauses are specified, then the first clause must be accompanied by an AND `` clause. For any given row, the second WHEN NOT MATCHED BY SOURCE clause is only applied if the first isn't. If there are two WHEN NOT MATCHED BY SOURCE clauses, then one must specify an UPDATE action and one must specify a DELETE action. Only columns from the target table can be referenced in ``. +Specifies that all rows of ``, which don't match the rows returned by `` ON ``, and that satisfy any additional search condition, are updated or deleted according to the `` clause. -When no rows are returned by ``, columns in the source table can't be accessed. If the update or delete action specified in the `` clause references columns in the source table, error 207 (Invalid column name) is returned. For example, the clause WHEN NOT MATCHED BY SOURCE THEN UPDATE SET TargetTable.Col1 = SourceTable.Col1 may cause the statement to fail because Col1 in the source table is inaccessible. +`WHEN NOT MATCHED BY SOURCE` clause without `AND ` implies unconditionally apply the `` action. +If two or more `WHEN NOT MATCHED BY SOURCE` clauses are specified only the last clause may be unaccompanied by `AND `. +The first `` evaluating to true determines the `` action. -AND -Any valid predicate on the matching source and target row or nonmatching source or target. +If there is no unconditional `` action, it is the same as specifying `NOP` for unconditional action. - -Specifies the update or delete action that's applied to all rows of target-table that don't match the rows returned by ON , and which satisfy any additional search condition. - -UPDATE SET -Specifies the list of column or variable names to update in the target table and the values with which to update them. - -For more information about the arguments of this clause, see UPDATE. Setting a variable to the same value as a column isn't supported. - -DELETE -Specifies that the rows matching rows in target-table are deleted. - -NOP -State unaltered. - - -Specifies the values to insert into the target table. - -(column-list) -A list of one or more columns of the target table in which to insert data. Columns must be specified as a single-part name or else the MERGE statement will fail. column-list must be enclosed in parentheses and delimited by commas. - -No of T shall be identified more than once in an . - -every column name must be accounted for once, referencing the most recently set column names - -VALUES (values-list) -A comma-separated list of constants, variables, or expressions that return values to insert into the target table. Expressions can't contain an EXECUTE statement. - -NOP -State unaltered. - -For more information about this clause, see INSERT (Transact-SQL). - - -Specifies the search conditions to specify or . +When no rows are returned by ``, columns in the source table can't be accessed, and therefore the `` action cannot reference columns in ``. ## Remarks -Cross ship merges not allowed. -The discussion of `INSERT` also applies when not matched by target. -In the case of multiple `WHEN MATCHED` or `WHEN NOT MATCHED` and overlapping predicates, the cases are processed in order, so the first successful takes precedence. + +When `` is updated in place or `` specified as a base `
`, the command potentially results in a state change of the Obelisk agent. + +Cross ship merges are not allowed. + +In the case of multiple `WHEN MATCHED` or `WHEN NOT MATCHED` and overlapping predicates, the cases are processed in order, so the first successful case takes precedence. + Tables in the namespace *sys* cannot be merged into. -At least one of the three MATCHED clauses must be specified, but they can be specified in any order. A variable can't be updated more than once in the same MATCHED clause. +At least one of the three `MATCHED` / `NOT MATCHED` clauses must be specified, but they can be specified in any order. -Any insert, update, or delete action specified on the target table by the MERGE statement are limited by any constraints defined on it, including unique indices and any cascading referential integrity constraints. If IGNORE-DUP-KEY is ON for any unique indexes on the target table, MERGE ignores this setting. +`INSERT`, `UPDATE`, or `DELETE` actions specified on `` are limited by any constraints defined on it (when it is a base `
`), including unique indices and any cascading referential integrity constraints. + +It `` is updated in place, or `` created, every `INSERT` clause must account for all columns in ``. Inserting fewer columns results in a new row sub-type, which is allowed when creating a virtual ``. + +Any `` referencing a column each from `` and `` satisfies the requirement that `ON ` not produce a cartesian join. However, it is to be noted a cartestian join cannot be entirely prevented depending on column contents. ## Produced Metadata @@ -201,12 +228,12 @@ Any insert, update, or delete action specified on the target table by the MERGE ## Exceptions `` does not exist `GRANT` permission on `` violated -`` does not exists +`` does not exist `GRANT` permission on `` violated `` already exists -referential integrity violation +referential integrity violation on the updated `` unique key violation -- for updateable `` unique key violation is a violation of the primary index or any other unique index defined on the table - -- for otherwise base-table `` producing pass-thru or new base-table output, `` primary index determines unique key violations - -- for pass-thru `` the `` columns validated in ``, or all target columns in the case of its absence, determine unique key violations - + -- for producing new base `
` output, `` primary index determines unique key violations + -- for producing `PASS-THRU` output, columns referenced in `` determine unique key violations for row sub-types that include all of the referenced columns + -- for producing `PASS-THRU` output when `` is not present, or the produced row sub-type does not include all of the referenced columns, the entire row by value determines unique key violations diff --git a/docs/ref-ch07-transform.md b/docs/ref-ch07-transform.md index 025f8bb..3af1de4 100755 --- a/docs/ref-ch07-transform.md +++ b/docs/ref-ch07-transform.md @@ -1,4 +1,7 @@ # Transform + + + ``` ::= [ WITH [ [ ,...n ] ] @@ -30,7 +33,6 @@ | INTERSECT | DIVIDED BY [ WITH REMAINDER ] | PASS-THRU - | NOP | TEE | MULTEE ``` @@ -68,9 +70,11 @@ API: ## Remarks +The `` command potentially results in a state change of the Obelisk agent depending on the `` in the last step. + `` within a CTE may not have its own `WITH` clause. -The `` `WITH` clause, in which CTEs are grouped, makes each CTE available to subsequent CTEs defined in the parent ``. +The `` `WITH` clause, in which CTEs are grouped, makes each CTE available to subsequent CTEs. When used as a `` (CTE) `` output must be a pass-thru virtual-table. @@ -79,4 +83,6 @@ When used as a `` (CTE) `` output must be a ## Exceptions `
` does not exist `GRANT` permission on `
` violated +unique key violation on `
` `AS OF` prior to `
` component creation +any exception for ``