urQL/docs/ref-ch04-data-manipulation.md

# BULK INSERT

TBD


# DELETE

Deletes rows from a `<table-set>`.

```
<delete> ::=
  DELETE [ FROM ] <table-set>
  [ WHERE <predicate> ]
```
## API
```
+$  delete
  $:
    %delete
    table=qualified-object
    predicate=(unit predicate)
  ==
```

## Arguments

**`<table-set>`**
The target of the `DELETE` operation.

**`<predicate>`**
Any valid `<predicate>`, including predicates on CTEs.

## Remarks

When `<table-set>` is a `<table>`, the command potentially mutates `<table>` resulting in a state change of the Obelisk agent.

A stand-alone `DELETE` statement can only operate on a `<table>` and produces a `<transform>` of one command step.

Data in the *sys* namespace cannot be deleted.

When `<table-set>` is a virtual table, the command produces an output `<table-set>` which may be consumed as a pass-thru by a subsequent `<transform>` step.

## Produced Metadata

@@ROWCOUNT returns the total number of rows deleted

## Exceptions
`<table>` does not exist
`GRANT` permission on `<table>` violated


# INSERT

Inserts rows into a `<table-set>`.

```
<insert> ::=
  INSERT INTO <table-set>
    [ ( <column> [ ,...n ] ) ]
    { VALUES (<scalar-expression> [ ,...n ] ) [ ...n ]
      | <transform> }
```

```
<scalar-expression> ::=
  { <constant>
    | <scalar-function>
    | <scalar-query>
    | [ unary-operator ] expression
    | expression <binary-operator> expression }
```

Details of `<scalar-function>` are TBD. Refer to the Functions chapter currently under development.

## API
```
+$  insert
  $:
    %insert
    table=qualified-object
    columns=(unit (list @t))
    values=insert-values
  ==
```

## Arguments

**`<table-set>`**
The target of the `INSERT` operation.

**`<column>` [ ,...n ]**
When present, the column list must account for all column identifiers (names or aliases) in the target once. It determines the order in which update values are applied and the output `<table-set>`'s column order.   

**(`<scalar-expression>` [ ,...n ] ) [ ,...n ]**
Row(s) of literal values to insert into target. Source auras must match target columnwise.

**`<transform>`**
Transform creating source `<table-set>` to insert into target. Source auras must match target columnwise.

## Remarks

When `<table-set>` is a `<table>` the command potentially mutates `<table>`, resulting in a state change of the Obelisk agent.

When `INSERT` operates on a `<table>`, it must be in the terminal (last) step of a `<transform>` or a stand-alone `INSERT`.

Data in the *sys* namespace cannot be inserted into.

When `<table-set>` is a virtual table, the command produces an output `<table-set>` which may be consumed as a pass-thru by a subsequent `<transform>` step.

The `VALUES` or `<query>` must provide data for all columns in the expected order.

Cord values are represented in single quotes `'this is a cord'`. Single quotes within cord values must be escaped with double backslash as `'this is a cor\\'d'`.

If `( <column> [ ,...n ] )` is not specified, the inserted columns must be arranged in the same order as the target `<table-set>`.

When the target `<table-set>` is a `<table>`, the input `<row-type>` must match the `<table>` `<row-type>`.

When target `<table-set>` is not a `<table>` and the input is from a `<transform>` then the target `<table-set>` and `<transform>` `<table-set>` must have the same all-column `<row-type>`. New `<row-type>` sub-types may be introduced.

Note that multiple parentheses enclosed rows of column values are NOT comma separated.

## Produced Metadata

`@@ROWCOUNT` returns the total number of rows inserted

## Exceptions
`<table>` does not exist
`GRANT` permission on `<table>` violated
unique key violation
colum misalignment


# TRUNCATE TABLE

Removes all rows in a base table.

```
<truncate-table> ::=
  TRUNCATE TABLE [ <ship-qualifier> ] <table>
```

## API
```
+$  truncate-table
  $:
    %truncate-table
    table=qualified-object
  ==
```

## Arguments

**`<table>`**
The target table.

## Remarks

The command potentially mutates `<table>`, resulting in a state change of the Obelisk agent.

Tables in the *sys* namespace cannot be truncated.

## Produced Metadata

none

## Exceptions
`<table>` does not exist
`GRANT` permission on `<table>` violated


# UPDATE

Changes content of selected columns in existing rows of a `<table-set>`. 

```
<update> ::=
  UPDATE [ <ship-qualifier> ] <table-set>
    SET { <column> = <scalar-expression> } [ ,...n ]
    [ WHERE <predicate> ]
```

## API
```
+$  update
  $:
    %update
    table=qualified-object
    columns=(list @t)
    values=(list value-or-default)
    predicate=(unit predicate)
  ==
```

## Arguments

**`<table-set>`**
The target of the `UPDATE` operation.

**`<column>` = `<scalar-expression>`**
`<column>` is a column name or alias of a target column. `<scalar-expression>` is a valid expression within the statement context.

**`<predicate>`**
Any valid `<predicate>`, including predicates on CTEs.

## Remarks

When `<table-set>` is a `<table>`, the command potentially mutates the data within `<table>`, resulting in a state change of the Obelisk agent.

A stand-alone `UPDATE` statement can only operate on a `<table>`, producing a `<transform>` of one command step with no CTEs.

Data in the *sys* namespace cannot be updated.

When `<table-set>` is a virtual table, the command produces an output `<table-set>` which may be consumed as a pass-thru by a subsequent `<transform>` step.

The `VALUES` or `<query>` must provide data for all columns in the expected order.

Cord values are represented in single quotes 'this is a cord'. Single quotes within cord values must be escaped with double backslash as `'this is a cor\\'d'`.

## Produced Metadata

`@@ROWCOUNT` returns the total number of rows updated

## Exceptions
`<table>` does not exist
`GRANT` permission on `<table>` violated
unique key violation
aura mismatch on `SET`