# Transform The `` statements provides a means of chaining commands on ``s produced by any command, either by passing the resulting `` to the next command -- similar to how CTEs work -- or by applying a set operation on two resulting ``s. It also provides the framework for declaring ``s, which can be consumed by following commands. ``` ::= [ WITH [ [ ,...n ] ] ] [ INTO | [ ( ] [ ) ] |

[ ( ] [ ) ] ] [ ...n ] [ AS OF { NOW | | n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO | } ] ``` ``` ::= [ AS ] ``` A `` in a CTE cannot include a `WITH` clause. ``` ::= | | | | ``` A `` is considered terminal when it operates on a `

` and potentially mutates its state, whether it mutates `

` state or not. A terminal `` must be the last step in a ``, it cannot be grouped by parentheses, and it is not the only `` it must have been preceded by a ``. The `` command by itself is never terminal. It is terminal when it is followed by `INTO

`. ``` ::= | ``` ``` ::= UNION | EXCEPT | INTERSECT | DIVIDED BY [ WITH REMAINDER ] ``` Set operations between two result ``. The left `` represents the running result of the `` and the right `` can be the result of nested ``s. **UNION** `UNION` concatenates the left and right ``s into one `` of distinct rows. **EXCEPT** `EXCEPT` returns distinct rows from the left `` that are not in the right ``. Rows that are not of the same `` are considered not matching. **INTERSECT** `INTERSECT` returns distinct rows that are in both the left and right ``s. Rows that are not of the same `` are considered not matching. **DIVIDED BY [ WITH REMAINDER ]** This operator performs a relational division on the left `` as the dividend and the right `` as divisor. NOTE: rule for dividing union ``s TBD. ``` ::= PASS-THRU | TEE | MULTEE ``` ``` ::= TEE | MULTEE ``` ``s make the left resulting `` available for consumption by the next `` in the ``. The right side of the statement cannot be nested. The left `` can be consumed by `*`, in which case column identifiers and `` column alignments from the left `` apply, or a list of column aliases, in which case all columns produced by the left `` must be included in the order produced. (See the definition of `` in the Introduction.) In other words the `` of the left `` applies when consumed by the right ``. **PASS-THRU** The result `` of the left sequence of ``s in the `` is available to the next (right) ``. **TEE** The result `` of the left sequence of ``s in the `` is available to the next (right) `` and the left `` is placed in order in the list of ``s resulting from the parent ``. **MULTEE** The result `` of the left sequence of ``s in the `` is available to the next (right) `` and the results of each `` in the left `` union type is placed in order in the list of ``s resulting from the parent ``. The order of the resulting ``s from the union type is arbitrary. NOTE: deterministic ordering of union type results TBD. ``` ::= | ``` API: ``` +$ transform $: %transform ctes=(list ) (tree ) == ``` ## Arguments **`WITH [ [ ,...n ] ]`** ``s within a CTE may not have their own `WITH` clause. The `WITH` clause makes the result `` of a `` statement available to the subsequent `` statements in the `WITH` clause and ``s in the main `` by ``. ``s in the `WITH` clause cannot have their own internal `WITH`, rather any preceding CTEs are available. When used as a ``, `` output must be a pass-thru virtual-table. When used as a ``, `` cannot include `TEE` and `MULTEE` operators. **`INTO

`** This clause inserts the resulting `` into `

`. The associated `` is terminal. This is the only case in which `` is terminal. **` [ ( ] [ ) ]`** If `` is a `` the result `` from the left side is applied to the next (right) result or result from next nested ``s. If `` is a `` the result `` from the left side is available to the next ``. Nesting left paren `(` can only exist singly, but right paren `)` may be stacked to any depth `...)))`, so long as left and right are matching. In other words nesting can only be applied on the right side. **`AS OF`** The `AS OF` provides a means to "travel through time" through the state changes of the ``(s). The default is the current state at execution, `NOW`. If the last `` is terminal (i.e. potentially state mutating, see discussion above), the affected `

` definition (columns, indices, and foreign keys) must be the same currently and in the `AS OF` time period. Foreign key constraints will operate against the current parent `

`s. All other `` state will be in the `AS OF` time period. Due to possible `` state changes there is no guarantee of the success of an `AS OF` ``. **``** Any valid date/time before the time of execution. **`n`** Integer seconds, minutes, hours, days, weeks, months, or years before execution time. If months is specified and the time "lands" on a day that is beyond the last day of that month, the date defaults to the last day of the landing month. **``** TBD ## Remarks The `` command potentially results in a state change of the Obelisk agent depending on the `` in the last step. If a `` is terminal it must be the last `` in the ``, cannot be nested by parentheses, and cannot be the right side of a ``. ## Produced Metadata list of output ``s in order produced (if the last `` is terminal it produces no output) metadata from last ``, if it was not the right side of a `` `@@ROWCOUNT` returns the total number of rows returned, if the last `` is in the right side of a `` ## Exceptions `

` does not exist mismatch of result `` and `

` `GRANT` permission on `

` violated unique key violation on `

` `AS OF` prior to creation of any `

` directly or indirectly (through a ``) referenced in the `` any exception for `` anywhere in the ``