jackfoxy/urQL
1
1
Fork 0
mirror of https://github.com/jackfoxy/urQL.git synced 2024-09-11 11:55:33 +03:00
Code Issues Packages Projects Releases Wiki Activity

standard MD code blocks

Browse Source
This commit is contained in:
jackfoxy 2024-04-10 09:36:26 -07:00
parent fc1aa73075
commit ba15948a1e
11 changed files with 120 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
docs/01-preliminaries.md
View File

@ -62,9 +62,12 @@ All objects in the database *sys* and namespace *sys* are system-owned and read-
The following are some common language structures used throughout the reference. The following are some common language structures used throughout the reference.
``` ``
<db-qualifier> ::= { <database>.<namespace>. | <database>.. | <namespace>. } <db-qualifier> ::=
``` { <database>.<namespace>.
| <database>..
| <namespace>. }
``
Provides the fully qualified path to a `<table>` or `<view>` object on the host ship. (NOTE: `<view>` is not yet implemented and is intended to be similar to SQL view.) Provides the fully qualified path to a `<table>` or `<view>` object on the host ship. (NOTE: `<view>` is not yet implemented and is intended to be similar to SQL view.)
@ -72,30 +75,30 @@ Provides the fully qualified path to a `<table>` or `<view>` object on the host
`<namespace>` defaults to 'dbo' (database owner). `<namespace>` defaults to 'dbo' (database owner).
``` ``
<ship-qualifier> ::= <ship-qualifier> ::=
{ @p.<database>.<namespace>. { @p.<database>.<namespace>.
| @p.<database>.. | @p.<database>..
| <db-qualifier> } | <db-qualifier> }
``` ``
Adds ship qualification to the database/namespace qualifier. Adds ship qualification to the database/namespace qualifier.
``` ``
<common-table-expression> ::= <transform> [ AS ] <alias> <common-table-expression> ::= <transform> [ AS ] <alias>
``` ``
`<transform> ::=` from transform diagram. (More on `<transform>` under `<table-set>`.) `<transform> ::=` from transform diagram. (More on `<transform>` under `<table-set>`.)
`<alias> ::= @t` case-agnostic, see alias naming discussion above. `<alias> ::= @t` case-agnostic, see alias naming discussion above.
Each CTE is always referenced by alias, never inlined. Each CTE is always referenced by alias, never inlined.
``` ``
<table-set> ::= <table-set> ::=
[ <ship-qualifier> ]{ <table> | <view> } [ <ship-qualifier> ]{ <table> | <view> }
| <common-table-expression> | <common-table-expression>
| * | *
``` ``
When `<view>, <table>` have the same name within a namespace, `<view>` is said to "shadow" `<table>` wherever syntax accepts `<table>` or `<view>`. When `<view>, <table>` have the same name within a namespace, `<view>` is said to "shadow" `<table>` wherever syntax accepts `<table>` or `<view>`.
@ -105,14 +108,14 @@ The `<transform>` command returns a `<table-set>`, hence every `<table-set>` is
The row type is defined by the component columns and may be a union type. Hence rows of `<table-set>`s that are not also `<table>`s may be of varying length (jagged). The order of rows may be determined in the `<transform>` command, and so `<table-set>`s are not strictly *sets* in the mathematical sense. The row type is defined by the component columns and may be a union type. Hence rows of `<table-set>`s that are not also `<table>`s may be of varying length (jagged). The order of rows may be determined in the `<transform>` command, and so `<table-set>`s are not strictly *sets* in the mathematical sense.
``` ``
<as-of-time> ::= <as-of-time> ::=
AS OF { NOW AS OF { NOW
| <timestamp> | <timestamp>
| n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO | n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO
| <time-offset> | <time-offset>
} }
``` ``
Specifying `<as-of-time>` overrides setting the schema and/or content timestamp in state changes. Specifying `<as-of-time>` overrides setting the schema and/or content timestamp in state changes.
@ -217,10 +220,10 @@ Obelisk supports the following auras (see the __Literals__ section for represent
| @ux | unsigned hexadecimal | | @ux | unsigned hexadecimal |
Columns are typed by an aura and indexed by name. Columns are typed by an aura and indexed by name.
``` ``
<column-type> ::= <column-type> ::=
<aura/name> <aura/name>
``` ``
### Table Row and Table Types ### Table Row and Table Types
@ -230,13 +233,13 @@ Datasets are also commonly regarded as tables, which is accurate when the index
All tables originate from, or are derived from, base tables created by the `CREATE TABLE` command. All tables originate from, or are derived from, base tables created by the `CREATE TABLE` command.
A base-table (`<table>`) row has a default type, which is the table's atomic aura-typed columns in a fixed order. A base-table (`<table>`) row has a default type, which is the table's atomic aura-typed columns in a fixed order.
``` ``
<row-type> ::= list <aura> <row-type> ::= list <aura>
``` ``
Each base table is typed by its `<row-type>`. Each base table is typed by its `<row-type>`.
``` ``
<table-type> ::= (list <row-type>) <table-type> ::= (list <row-type>)
``` ``
A base table's definition includes a unique primary row order, giving it `list` type rather than `set` type. This is not true for all `<table-set>` instances. A base table's definition includes a unique primary row order, giving it `list` type rather than `set` type. This is not true for all `<table-set>` instances.
Rows from `<view>`s, `<common-table-expression>`s, and the command output from `<transform>`, or any other table that is not a base-table, can only have an immutable row order if it is explicitly specified (i.e., the `SELECT` statement includes an `ORDER BY` clause). In general, these other tables have types that are unions of `<row-type>`s. Rows from `<view>`s, `<common-table-expression>`s, and the command output from `<transform>`, or any other table that is not a base-table, can only have an immutable row order if it is explicitly specified (i.e., the `SELECT` statement includes an `ORDER BY` clause). In general, these other tables have types that are unions of `<row-type>`s.
@ -246,11 +249,11 @@ When the `<table-set-type>` is a union of `<row-type>`s. There is a `<row-type>`
Sub-types align their columns with the all-column `<row-type>`, regardless of the SELECT statement's construction. Sub-types align their columns with the all-column `<row-type>`, regardless of the SELECT statement's construction.
In general, `<table-set>`s have the type: In general, `<table-set>`s have the type:
``` ``
<table-set-type> ::= <table-set-type> ::=
(list <row-type>) (list <row-type>)
| (set (<all-column-row-type> | <row-sub-type-1> | ... | <row-sub-type-n> )) | (set (<all-column-row-type> | <row-sub-type-1> | ... | <row-sub-type-n> ))
``` ``
### Additional Types ### Additional Types
All static types in Obelisk API are defined in `sur/ast/hoon`. All static types in Obelisk API are defined in `sur/ast/hoon`.

20
docs/02-ddl-database.md
View File

@ -4,20 +4,20 @@
Creates a new user-space database on the ship. Creates a new user-space database on the ship.
``` ``
<create-database> ::= <create-database> ::=
CREATE DATABASE <database> [ <as-of-time> ] CREATE DATABASE <database> [ <as-of-time> ]
``` ``
### API ### API
``` ``
+$ create-database +$ create-database
$: $:
%create-database %create-database
name=@tas name=@tas
as-of=(unit <as-of>) as-of=(unit <as-of>)
== ==
``` ``
### Arguments ### Arguments
@ -44,28 +44,28 @@ database name cannot be 'sys'
duplicate key: `<database>` duplicate key: `<database>`
### Example ### Example
``` ``
CREATE DATABASE my-database CREATE DATABASE my-database
``` ``
## DROP DATABASE ## DROP DATABASE
*supported in urQL parser, not yet supported in Obelisk* *supported in urQL parser, not yet supported in Obelisk*
Deletes an existing `<database>` and all associated objects. Deletes an existing `<database>` and all associated objects.
``` ``
<drop-database> ::= DROP DATABASE [ FORCE ] <database> <drop-database> ::= DROP DATABASE [ FORCE ] <database>
``` ``
### API ### API
``` ``
+$ drop-database +$ drop-database
$: $:
%drop-database %drop-database
name=@tas name=@tas
force=? force=?
== ==
``` ``
### Arguments ### Arguments

24
docs/03-ddl-namespace.md
View File

@ -6,19 +6,19 @@ Creates a new namespace within the specified or default database.
Namespaces group various database components, including tables and views. When not explicitly specified, namespace designations default to `dbo`. Namespaces group various database components, including tables and views. When not explicitly specified, namespace designations default to `dbo`.
``` ``
<create-namespace> ::= <create-namespace> ::=
CREATE NAMESPACE [<database>.] <namespace> [ <as-of-time> ] CREATE NAMESPACE [<database>.] <namespace> [ <as-of-time> ]
``` ``
### API ### API
``` ``
+$ create-namespace +$ create-namespace
database-name=@tas database-name=@tas
name=@tas name=@tas
as-of=(unit as-of) as-of=(unit as-of)
== ==
``` ``
### Arguments ### Arguments
@ -61,15 +61,15 @@ create namespace state change after query in script
Transfer an existing user `<table>` or `<view>` to another `<namespace>`. Transfer an existing user `<table>` or `<view>` to another `<namespace>`.
``` ``
<alter-namespace> ::= <alter-namespace> ::=
ALTER NAMESPACE [ <database>. ] <namespace> ALTER NAMESPACE [ <database>. ] <namespace>
TRANSFER { TABLE | VIEW } [ <db-qualifer> ]{ <table> | <view> } TRANSFER { TABLE | VIEW } [ <db-qualifer> ]{ <table> | <view> }
[ <as-of-time> ] [ <as-of-time> ]
``` ``
### API ### API
``` ``
+$ alter-namespace +$ alter-namespace
$: %alter-namespace $: %alter-namespace
database-name=@tas database-name=@tas
@ -79,7 +79,7 @@ Transfer an existing user `<table>` or `<view>` to another `<namespace>`.
target-name=@tas target-name=@tas
as-of=(unit as-of) as-of=(unit as-of)
== ==
``` ``
### Arguments ### Arguments
@ -119,14 +119,14 @@ alter namespace state change after query in script
Deletes a `<namespace>` and all its associated objects when `FORCE` specified. Deletes a `<namespace>` and all its associated objects when `FORCE` specified.
``` ``
<drop-namespace> ::= <drop-namespace> ::=
DROP NAMESPACE [ FORCE ] [ <database>. ] <namespace> DROP NAMESPACE [ FORCE ] [ <database>. ] <namespace>
[ <as-of-time> ] [ <as-of-time> ]
``` ``
### API ### API
``` ``
+$ drop-namespace +$ drop-namespace
$: $:
%drop-namespace %drop-namespace
@ -135,7 +135,7 @@ Deletes a `<namespace>` and all its associated objects when `FORCE` specified.
force=? force=?
as-of=(unit as-of) as-of=(unit as-of)
== ==
``` ``
### Arguments ### Arguments

32
docs/04-ddl-table.md
View File

@ -6,7 +6,7 @@ Creates a new table within the specified or default database.
`<table>`s are the source of indexed persistent `<table-sets>`s in Obelisk. `<table>`s are the source of indexed persistent `<table-sets>`s in Obelisk.
``` ``
<create-table> ::= <create-table> ::=
CREATE TABLE CREATE TABLE
[ <db-qualifer> ]<table> [ <db-qualifer> ]<table>
@ -19,10 +19,10 @@ Creates a new table within the specified or default database.
[ ON UPDATE { NO ACTION | CASCADE | SET DEFAULT } ] } [ ON UPDATE { NO ACTION | CASCADE | SET DEFAULT } ] }
[ ,... n ] ] [ ,... n ] ]
[ <as-of-time> ] [ <as-of-time> ]
``` ``
### API ### API
``` ``
+$ create-table +$ create-table
$: $:
%create-table %create-table
@ -33,7 +33,7 @@ Creates a new table within the specified or default database.
foreign-keys=(list foreign-key) foreign-keys=(list foreign-key)
as-of=(unit as-of) as-of=(unit as-of)
== ==
``` ``
### Arguments ### Arguments
@ -126,13 +126,13 @@ aura mis-match in `FOREIGN KEY`
create table state change after query in script create table state change after query in script
### Example ### Example
``` ``
CREATE TABLE order-detail CREATE TABLE order-detail
(invoice-nbr @ud, line-item @ud, product-id @ud, special-offer-id @ud, message @t) (invoice-nbr @ud, line-item @ud, product-id @ud, special-offer-id @ud, message @t)
PRIMARY KEY CLUSTERED (invoice-nbr, line-item) PRIMARY KEY CLUSTERED (invoice-nbr, line-item)
FOREIGN KEY fk-special-offer-order-detail (product-id, specialoffer-id) FOREIGN KEY fk-special-offer-order-detail (product-id, specialoffer-id)
REFERENCES special-offer (product-id, special-offer-id) REFERENCES special-offer (product-id, special-offer-id)
``` ``
## ALTER TABLE ## ALTER TABLE
@ -140,7 +140,7 @@ REFERENCES special-offer (product-id, special-offer-id)
Modify the columns and/or `<foreign-key>`s of an existing `<table>`. Modify the columns and/or `<foreign-key>`s of an existing `<table>`.
``` ``
<alter-> ::= <alter-> ::=
ALTER TABLE [ <db-qualifer> ]{ <table> } ALTER TABLE [ <db-qualifer> ]{ <table> }
{ ADD COLUMN ( <column> <aura> [ ,... n ] ) { ADD COLUMN ( <column> <aura> [ ,... n ] )
@ -153,16 +153,16 @@ Modify the columns and/or `<foreign-key>`s of an existing `<table>`.
[ ,... n ] [ ,... n ]
| DROP FOREIGN KEY ( <foreign-key> [ ,... n ] } ) | DROP FOREIGN KEY ( <foreign-key> [ ,... n ] } )
[ <as-of-time> ] [ <as-of-time> ]
``` ``
Example: Example:
``` ``
ALTER TABLE my-table ALTER TABLE my-table
DROP FOREIGN KEY fk-1, fk-2 DROP FOREIGN KEY fk-1, fk-2
``` ``
### API ### API
``` ``
+$ alter-table +$ alter-table
$: $:
%alter-table %alter-table
@ -174,7 +174,7 @@ DROP FOREIGN KEY fk-1, fk-2
drop-foreign-keys=(list @tas) drop-foreign-keys=(list @tas)
as-of=(unit as-of) as-of=(unit as-of)
== ==
``` ``
### Arguments ### Arguments
@ -263,14 +263,14 @@ alter table state change after query in script
Deletes a `<table>` and all associated objects. Deletes a `<table>` and all associated objects.
``` ``
<drop-table> ::= <drop-table> ::=
DROP TABLE [ FORCE ] [ <db-qualifer> ]{ <table> } DROP TABLE [ FORCE ] [ <db-qualifer> ]{ <table> }
[ <as-of-time> ] [ <as-of-time> ]
``` ``
### API ### API
``` ``
+$ drop-table +$ drop-table
$: $:
%drop-table %drop-table
@ -278,7 +278,7 @@ Deletes a `<table>` and all associated objects.
force=? force=?
as-of=(unit as-of) as-of=(unit as-of)
== ==
``` ``
### Arguments ### Arguments

28
docs/05-ddl-index → docs/05-ddl-index.md
View File

@ -6,25 +6,25 @@
This command creates an index over selected columns of an existing table. This command creates an index over selected columns of an existing table.
### AST ### AST
``` ``
<create-index> ::= <create-index> ::=
CREATE [ UNIQUE ] [ CLUSTERED | LOOK-UP ] INDEX <index> CREATE [ UNIQUE ] [ CLUSTERED | LOOK-UP ] INDEX <index>
ON [ <db-qualifer> ] <table> ON [ <db-qualifer> ] <table>
( <column> [ ASC | DESC ] [ ,...n ] ) ( <column> [ ASC | DESC ] [ ,...n ] )
[ <as-of-time> ] [ <as-of-time> ]
``` ``
### Examples ### Examples
``` ``
CREATE INDEX ix-vendor-id ON product-vendor (vendor-id); CREATE INDEX ix-vendor-id ON product-vendor (vendor-id);
CREATE UNIQUE INDEX ix-vendor-id2 ON dbo.product-vendor CREATE UNIQUE INDEX ix-vendor-id2 ON dbo.product-vendor
(vendor-id DESC, name ASC, address DESC); (vendor-id DESC, name ASC, address DESC);
CREATE INDEX ix-vendor-id3 ON purchasing..product-vendor (vendor-id); CREATE INDEX ix-vendor-id3 ON purchasing..product-vendor (vendor-id);
``` ``
### API ### API
``` ``
+$ create-index +$ create-index
$: $:
%create-index %create-index
@ -34,7 +34,7 @@ CREATE INDEX ix-vendor-id3 ON purchasing..product-vendor (vendor-id);
is-clustered=? is-clustered=?
columns=(list ordered-column) columns=(list ordered-column)
== ==
``` ``
### Arguments ### Arguments
@ -87,17 +87,17 @@ create index state change after query in script
Modifies the structure of an existing `<index>` on a user `<table>` or `<view>`. Modifies the structure of an existing `<index>` on a user `<table>` or `<view>`.
``` ``
<alter-index> ::= <alter-index> ::=
ALTER [ UNIQUE ] [ CLUSTERED | LOOK-UP ] INDEX <index> ALTER [ UNIQUE ] [ CLUSTERED | LOOK-UP ] INDEX <index>
ON [ <db-qualifer> ] <table> ON [ <db-qualifer> ] <table>
[ ( <column> [ ASC | DESC ] [ ,...n ] ) ] [ ( <column> [ ASC | DESC ] [ ,...n ] ) ]
{ DISABLE | RESUME} { DISABLE | RESUME}
[ <as-of-time> ] [ <as-of-time> ]
``` ``
### API ### API
``` ``
+$ alter-index +$ alter-index
$: $:
%alter-index %alter-index
@ -106,7 +106,7 @@ Modifies the structure of an existing `<index>` on a user `<table>` or `<view>`.
columns=(list ordered-column) columns=(list ordered-column)
action=index-action action=index-action
== ==
``` ``
### Arguments ### Arguments
@ -165,22 +165,22 @@ alter index state change after query in script
Deletes an existing `<index>`. Deletes an existing `<index>`.
``` ``
<drop-index> ::= <drop-index> ::=
DROP INDEX <index> DROP INDEX <index>
ON [ <db-qualifer> ] <table> ON [ <db-qualifer> ] <table>
[ <as-of-time> ] [ <as-of-time> ]
``` ``
### API ### API
``` ``
+$ drop-index +$ drop-index
$: $:
%drop-index %drop-index
name=@tas name=@tas
object=qualified-object object=qualified-object
== ==
``` ``
### Arguments ### Arguments

8
docs/07-update.md
View File

@ -3,16 +3,16 @@
Changes content of selected columns in existing rows of a `<table-set>`. Changes content of selected columns in existing rows of a `<table-set>`.
``` ``
<update> ::= <update> ::=
UPDATE [ <ship-qualifier> ] <table> UPDATE [ <ship-qualifier> ] <table>
SET { <column> = <scalar-expression> } [ ,...n ] SET { <column> = <scalar-expression> } [ ,...n ]
[ WHERE <predicate> ] [ WHERE <predicate> ]
[ <as-of-time> ] [ <as-of-time> ]
``` ``
### API ### API
``` ``
+$ update +$ update
$: $:
%update %update
@ -22,7 +22,7 @@ Changes content of selected columns in existing rows of a `<table-set>`.
predicate=(unit predicate) predicate=(unit predicate)
as-of=(unit as-of) as-of=(unit as-of)
== ==
``` ``
### Arguments ### Arguments

8
docs/08-delete.md
View File

@ -3,14 +3,14 @@
Deletes rows from a `<table-set>`. Deletes rows from a `<table-set>`.
``` ``
<delete> ::= <delete> ::=
DELETE [ FROM ] <table> DELETE [ FROM ] <table>
[ WHERE <predicate> ] [ WHERE <predicate> ]
[ <as-of-time> ] [ <as-of-time> ]
``` ``
### API ### API
``` ``
+$ delete +$ delete
$: $:
%delete %delete
@ -18,7 +18,7 @@ Deletes rows from a `<table-set>`.
predicate=(unit predicate) predicate=(unit predicate)
as-of=(unit as-of) as-of=(unit as-of)
== ==
``` ``
### Arguments ### Arguments

8
docs/09-truncate-table.md
View File

@ -2,21 +2,21 @@
Removes all rows in a base table. Removes all rows in a base table.
``` ``
<truncate-table> ::= <truncate-table> ::=
TRUNCATE TABLE [ <ship-qualifier> ] <table> TRUNCATE TABLE [ <ship-qualifier> ] <table>
[ <as-of-time> ] [ <as-of-time> ]
``` ``
### API ### API
``` ``
+$ truncate-table +$ truncate-table
$: $:
%truncate-table %truncate-table
table=qualified-object table=qualified-object
as-of=(unit as-of) as-of=(unit as-of)
== ==
``` ``
### Arguments ### Arguments

32
docs/10-query.md
View File

@ -3,7 +3,7 @@
The `<query>` statement provides a means to create `<table-set>`s derived from persisted and/or cached `<table-set>`s and/or constants. Data rows can be joined based on predicates, specific columns can be selected, and the resulting rows can be filtered by predicate. The `<query>` statement provides a means to create `<table-set>`s derived from persisted and/or cached `<table-set>`s and/or constants. Data rows can be joined based on predicates, specific columns can be selected, and the resulting rows can be filtered by predicate.
``` ``
<query> ::= <query> ::=
[ FROM <table-set> [ [AS] <alias> ] [ FROM <table-set> [ [AS] <alias> ]
{ {
@ -28,7 +28,7 @@ The `<query>` statement provides a means to create `<table-set>`s derived from p
{ <qualified-column> | <column-alias> | <column-ordinal> } { ASC | DESC } { <qualified-column> | <column-alias> | <column-ordinal> } { ASC | DESC }
} [ ,...n ] } [ ,...n ]
] ]
``` ``
`JOIN` is an inner join returning all matching pairs of rows. `JOIN` is an inner join returning all matching pairs of rows.
`LEFT JOIN` is a left outer join returning all rows from the left table not meeting the join condition, along with all matching pairs of rows. `LEFT JOIN` is a left outer join returning all rows from the left table not meeting the join condition, along with all matching pairs of rows.
@ -45,15 +45,15 @@ Cross database joins are permitted, but not cross ship joins.
Avoid using `ORDER BY` in CTEs or in any query prior to the last step in a `<transform>`, unless required by `TOP` or `BOTTOM` specified in the `SELECT` statement. Avoid using `ORDER BY` in CTEs or in any query prior to the last step in a `<transform>`, unless required by `TOP` or `BOTTOM` specified in the `SELECT` statement.
``` ``
<predicate> ::= <predicate> ::=
{ [ NOT ] <predicate> | [ ( ] <simple-predicate> [ ) ] } { [ NOT ] <predicate> | [ ( ] <simple-predicate> [ ) ] }
[ { { AND | OR } [ NOT ] { <predicate> | [ ( ] <simple-predicate> [ ) ] } [ { { AND | OR } [ NOT ] { <predicate> | [ ( ] <simple-predicate> [ ) ] }
[ ...n ] [ ...n ]
] ]
``` ``
``` ``
<simple-predicate> ::= <simple-predicate> ::=
{ expression <binary-operator> expression { expression <binary-operator> expression
| expression [ NOT ] EQUIV expression | expression [ NOT ] EQUIV expression
@ -63,22 +63,22 @@ Avoid using `ORDER BY` in CTEs or in any query prior to the last step in a `<tra
{ ALL | ANY} { ( <scalar-query> ) | ( <value> ,...n ) } { ALL | ANY} { ( <scalar-query> ) | ( <value> ,...n ) }
| expression [ NOT ] BETWEEN expression [ AND ] expression | expression [ NOT ] BETWEEN expression [ AND ] expression
| [ NOT ] EXISTS { <column value> | <scalar-query> } } | [ NOT ] EXISTS { <column value> | <scalar-query> } }
``` ``
When applied to a column `EXISTS` tests whether the returned `<row-type>` includes the required column. In the case of `<scalar-query>`, it tests whether a CTE returns any rows. When applied to a column `EXISTS` tests whether the returned `<row-type>` includes the required column. In the case of `<scalar-query>`, it tests whether a CTE returns any rows.
`[ NOT ] EQUIV` is a binary operator, similar to (not) equals `<>`, `=`. However, comparing two `NOT EXISTS` yields true. `[ NOT ] EQUIV` is a binary operator, similar to (not) equals `<>`, `=`. However, comparing two `NOT EXISTS` yields true.
`<scalar-query>` is a CTE that selects for one column. Depending on whether the operator expects a set or a value, it operates on the entire result set or on the first row returned, respectively. `<scalar-query>` is a CTE that selects for one column. Depending on whether the operator expects a set or a value, it operates on the entire result set or on the first row returned, respectively.
``` ``
<binary-operator> ::= <binary-operator> ::=
{ = | <> | != | > | >= | !> | < | <= | !< | EQUIV | NOT EQUIV} { = | <> | != | > | >= | !> | < | <= | !< | EQUIV | NOT EQUIV}
``` ``
Whitespace is not required between operands and binary-operators, except when the left operand is a numeric literal, in which case whitespace is required. Whitespace is not required between operands and binary-operators, except when the left operand is a numeric literal, in which case whitespace is required.
`<inequality-operator>` is any `<binary-operator>` other than equality and `EQUIV`. `<inequality-operator>` is any `<binary-operator>` other than equality and `EQUIV`.
``` ``
<expression> ::= <expression> ::=
{ <qualified-column> { <qualified-column>
| <constant> | <constant>
@ -86,24 +86,24 @@ Whitespace is not required between operands and binary-operators, except when th
| <scalar-query> | <scalar-query>
| <aggregate-function>( { <column> | <scalar> } ) | <aggregate-function>( { <column> | <scalar> } )
} }
``` ``
*<aggregate-function> is not yet implemente in the urQL parser* *<aggregate-function> is not yet implemente in the urQL parser*
`<scalar-query>` is a CTE that returns only one column. The first returned value is accepted and subsequent values ignored. Ordering the CTE may be required for predictable results. `<scalar-query>` is a CTE that returns only one column. The first returned value is accepted and subsequent values ignored. Ordering the CTE may be required for predictable results.
``` ``
<column> ::= <column> ::=
{ <qualified-column> { <qualified-column>
| <column-alias> | <column-alias>
| <constant> } | <constant> }
``` ``
``` ``
<qualified-column> ::= <qualified-column> ::=
[ [ <ship-qualifier> ]<table-view> | <alias> ].<column-name> [ [ <ship-qualifier> ]<table-view> | <alias> ].<column-name>
``` ``
### API ### API
``` ``
+$ query +$ query
$: $:
%query %query
@ -115,7 +115,7 @@ Whitespace is not required between operands and binary-operators, except when th
selection=select selection=select
order-by=(list ordering-column) order-by=(list ordering-column)
== ==
``` ``
### Arguments ### Arguments

20
docs/11-merge.md
View File

@ -28,7 +28,7 @@ The output `<table-set>`'s row type will correspond to the row type of `<target-
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 `<target-table>` or creation of `<new-table>` as base `<table>`. 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 `<target-table>` or creation of `<new-table>` as base `<table>`.
``` ``
<merge> ::= <merge> ::=
MERGE [ { INTO | FROM } ] <target-table> [ [ AS ] <alias> ] MERGE [ { INTO | FROM } ] <target-table> [ [ AS ] <alias> ]
[ PRODUCING NEW <new-table> ] [ PRODUCING NEW <new-table> ]
@ -42,24 +42,24 @@ If the resulting virtual-table row type is a union type, then the output must be
[ WHEN NOT MATCHED BY SOURCE [ AND <unmatched-source-predicate> ] [ WHEN NOT MATCHED BY SOURCE [ AND <unmatched-source-predicate> ]
THEN <merge-matched> ] [ ...n ] THEN <merge-matched> ] [ ...n ]
[ <as-of-time> ] [ <as-of-time> ]
``` ``
``` ``
<target-table> ::= <table-set> <target-table> ::= <table-set>
<new-table> ::= <table-set> <new-table> ::= <table-set>
<source-table> ::= <table-set> <source-table> ::= <table-set>
<matched-predicate> ::= <predicate> <matched-predicate> ::= <predicate>
<unmatched-target-predicate> ::= <predicate> <unmatched-target-predicate> ::= <predicate>
<unmatched-source-predicate> ::= <predicate> <unmatched-source-predicate> ::= <predicate>
``` ``
``` ``
<merge-matched> ::= <merge-matched> ::=
{ UPDATE [ SET ] { <column> = <scalar-expression> } [ ,...n ] { UPDATE [ SET ] { <column> = <scalar-expression> } [ ,...n ]
| DELETE | DELETE
| NOP | NOP
} }
``` ``
Specifies the update or delete action that is applied to all rows of `<target-table>` that don't match the rows returned by `<table-source>` ON `<merge-predicate>`, and which satisfy any additional predicate. Specifies the update or delete action that is applied to all rows of `<target-table>` that don't match the rows returned by `<table-source>` ON `<merge-predicate>`, and which satisfy any additional predicate.
@ -80,12 +80,12 @@ Delete the matched target row.
No operation performed. No operation performed.
``` ``
<merge-not-matched> ::= <merge-not-matched> ::=
INSERT [ ( <column> [ ,...n ] ) ] INSERT [ ( <column> [ ,...n ] ) ]
VALUES ( <scalar-expression> [ ,...n ] ) VALUES ( <scalar-expression> [ ,...n ] )
| NOP | NOP
``` ``
**`<column>`** **`<column>`**
@ -102,7 +102,7 @@ The count out `INSERT` columns and `VALUES` must match.
No operation performed. No operation performed.
### API ### API
``` ``
+$ merge +$ merge
$: $:
%merge %merge
@ -115,7 +115,7 @@ No operation performed.
unmatched-by-source=(list matching) unmatched-by-source=(list matching)
as-of=(unit as-of) as-of=(unit as-of)
== ==
``` ``
### Arguments ### Arguments

16
docs/12-permissions.md
View File

@ -19,7 +19,7 @@ To Do:
2. Allow revoking of rights by on-ship agent. (for real security this has to be opt-in...do this in create database) 2. Allow revoking of rights by on-ship agent. (for real security this has to be opt-in...do this in create database)
### AST ### AST
``` ``
<grant> ::= <grant> ::=
GRANT { ADMINREAD | READONLY | READWRITE } GRANT { ADMINREAD | READONLY | READWRITE }
TO { PARENT | SIBLINGS | MOONS | <@p> [ ,...n ] } TO { PARENT | SIBLINGS | MOONS | <@p> [ ,...n ] }
@ -27,21 +27,21 @@ To Do:
| NAMESPACE [<database>.] <namespace> | NAMESPACE [<database>.] <namespace>
| [<db-qualifier>] <table-object> | [<db-qualifier>] <table-object>
} }
``` ``
### Example ### Example
`GRANT READONLY TO ~sampel-palnet ON NAMESPACE my-namespace` `GRANT READONLY TO ~sampel-palnet ON NAMESPACE my-namespace`
### API ### API
``` ``
$: $:
%grant %grant
permission=grant-permission permission=grant-permission
to=grantee to=grantee
grant-target=grant-object grant-target=grant-object
== ==
``` ``
### Arguments ### Arguments
@ -104,7 +104,7 @@ INSERT grantee, grant, target, `<timestamp>` INTO `<database>.sys.grants`
Revokes permission to read from and/or write to selected database objects on the host ship to selected foreign ships. Revokes permission to read from and/or write to selected database objects on the host ship to selected foreign ships.
``` ``
<revoke> ::= <revoke> ::=
REVOKE { ADMINREAD | READONLY | READWRITE | ALL } REVOKE { ADMINREAD | READONLY | READWRITE | ALL }
FROM { PARENT | SIBLINGS | MOONS | ALL | <@p> [ ,...n ] } FROM { PARENT | SIBLINGS | MOONS | ALL | <@p> [ ,...n ] }
@ -112,11 +112,11 @@ Revokes permission to read from and/or write to selected database objects on the
| NAMESPACE [<database>.] <namespace> | NAMESPACE [<database>.] <namespace>
| [<db-qualifier>] <table-object> | [<db-qualifier>] <table-object>
} }
``` ``
### API ### API
``` ``
+$ revoke +$ revoke
$: $:
%revoke %revoke
@ -124,7 +124,7 @@ Revokes permission to read from and/or write to selected database objects on the
from=revoke-from from=revoke-from
revoke-target=revoke-object revoke-target=revoke-object
== ==
``` ``
### Arguments ### Arguments