jackfoxy/urQL
1
1
Fork 0
mirror of https://github.com/jackfoxy/urQL.git synced 2024-08-16 23:30:51 +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.
```
<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.)
@ -72,30 +75,30 @@ Provides the fully qualified path to a `<table>` or `<view>` object on the host
`<namespace>` defaults to 'dbo' (database owner).
```
``
<ship-qualifier> ::=
{ @p.<database>.<namespace>.
| @p.<database>..
| <db-qualifier> }
```
``
Adds ship qualification to the database/namespace qualifier.
```
``
<common-table-expression> ::= <transform> [ AS ] <alias>
```
``
`<transform> ::=` from transform diagram. (More on `<transform>` under `<table-set>`.)
`<alias> ::= @t` case-agnostic, see alias naming discussion above.
Each CTE is always referenced by alias, never inlined.
```
``
<table-set> ::=
[ <ship-qualifier> ]{ <table> | <view> }
| <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>`.
@ -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.
```
``
<as-of-time> ::=
AS OF { NOW
| <timestamp>
| n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO
| <time-offset>
}
```
``
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 |
Columns are typed by an aura and indexed by name.
```
``
<column-type> ::=
<aura/name>
```
``
### 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.
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>
```
``
Each base table is typed by its `<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.
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.
In general, `<table-set>`s have the type:
```
``
<table-set-type> ::=
(list <row-type>)
| (set (<all-column-row-type> | <row-sub-type-1> | ... | <row-sub-type-n> ))
```
``
### Additional Types
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.
```
``
<create-database> ::=
CREATE DATABASE <database> [ <as-of-time> ]
```
``
### API
```
``
+$ create-database
$:
%create-database
name=@tas
as-of=(unit <as-of>)
==
```
``
### Arguments
@ -44,28 +44,28 @@ database name cannot be 'sys'
duplicate key: `<database>`
### Example
```
``
CREATE DATABASE my-database
```
``
## DROP DATABASE
*supported in urQL parser, not yet supported in Obelisk*
Deletes an existing `<database>` and all associated objects.
```
``
<drop-database> ::= DROP DATABASE [ FORCE ] <database>
```
``
### API
```
``
+$ drop-database
$:
%drop-database
name=@tas
force=?
==
```
``
### 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`.
```
``
<create-namespace> ::=
CREATE NAMESPACE [<database>.] <namespace> [ <as-of-time> ]
```
``
### API
```
``
+$ create-namespace
database-name=@tas
name=@tas
as-of=(unit as-of)
==
```
``
### Arguments
@ -61,15 +61,15 @@ create namespace state change after query in script
Transfer an existing user `<table>` or `<view>` to another `<namespace>`.
```
``
<alter-namespace> ::=
ALTER NAMESPACE [ <database>. ] <namespace>
TRANSFER { TABLE | VIEW } [ <db-qualifer> ]{ <table> | <view> }
[ <as-of-time> ]
```
``
### API
```
``
+$ alter-namespace
$: %alter-namespace
database-name=@tas
@ -79,7 +79,7 @@ Transfer an existing user `<table>` or `<view>` to another `<namespace>`.
target-name=@tas
as-of=(unit as-of)
==
```
``
### Arguments
@ -119,14 +119,14 @@ alter namespace state change after query in script
Deletes a `<namespace>` and all its associated objects when `FORCE` specified.
```
``
<drop-namespace> ::=
DROP NAMESPACE [ FORCE ] [ <database>. ] <namespace>
[ <as-of-time> ]
```
``
### API
```
``
+$ drop-namespace
$:
%drop-namespace
@ -135,7 +135,7 @@ Deletes a `<namespace>` and all its associated objects when `FORCE` specified.
force=?
as-of=(unit as-of)
==
```
``
### 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.
```
``
<create-table> ::=
CREATE 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 } ] }
[ ,... n ] ]
[ <as-of-time> ]
```
``
### API
```
``
+$ create-table
$:
%create-table
@ -33,7 +33,7 @@ Creates a new table within the specified or default database.
foreign-keys=(list foreign-key)
as-of=(unit as-of)
==
```
``
### Arguments
@ -126,13 +126,13 @@ aura mis-match in `FOREIGN KEY`
create table state change after query in script
### Example
```
``
CREATE TABLE order-detail
(invoice-nbr @ud, line-item @ud, product-id @ud, special-offer-id @ud, message @t)
PRIMARY KEY CLUSTERED (invoice-nbr, line-item)
FOREIGN KEY fk-special-offer-order-detail (product-id, specialoffer-id)
REFERENCES special-offer (product-id, special-offer-id)
```
``
## 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>`.
```
``
<alter-> ::=
ALTER TABLE [ <db-qualifer> ]{ <table> }
{ ADD COLUMN ( <column> <aura> [ ,... n ] )
@ -153,16 +153,16 @@ Modify the columns and/or `<foreign-key>`s of an existing `<table>`.
[ ,... n ]
| DROP FOREIGN KEY ( <foreign-key> [ ,... n ] } )
[ <as-of-time> ]
```
``
Example:
```
``
ALTER TABLE my-table
DROP FOREIGN KEY fk-1, fk-2
```
``
### API
```
``
+$ alter-table
$:
%alter-table
@ -174,7 +174,7 @@ DROP FOREIGN KEY fk-1, fk-2
drop-foreign-keys=(list @tas)
as-of=(unit as-of)
==
```
``
### Arguments
@ -263,14 +263,14 @@ alter table state change after query in script
Deletes a `<table>` and all associated objects.
```
``
<drop-table> ::=
DROP TABLE [ FORCE ] [ <db-qualifer> ]{ <table> }
[ <as-of-time> ]
```
``
### API
```
``
+$ drop-table
$:
%drop-table
@ -278,7 +278,7 @@ Deletes a `<table>` and all associated objects.
force=?
as-of=(unit as-of)
==
```
``
### 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.
### AST
```
``
<create-index> ::=
CREATE [ UNIQUE ] [ CLUSTERED | LOOK-UP ] INDEX <index>
ON [ <db-qualifer> ] <table>
( <column> [ ASC | DESC ] [ ,...n ] )
[ <as-of-time> ]
```
``
### Examples
```
``
CREATE INDEX ix-vendor-id ON product-vendor (vendor-id);
CREATE UNIQUE INDEX ix-vendor-id2 ON dbo.product-vendor
(vendor-id DESC, name ASC, address DESC);
CREATE INDEX ix-vendor-id3 ON purchasing..product-vendor (vendor-id);
```
``
### API
```
``
+$ create-index
$:
%create-index
@ -34,7 +34,7 @@ CREATE INDEX ix-vendor-id3 ON purchasing..product-vendor (vendor-id);
is-clustered=?
columns=(list ordered-column)
==
```
``
### 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>`.
```
``
<alter-index> ::=
ALTER [ UNIQUE ] [ CLUSTERED | LOOK-UP ] INDEX <index>
ON [ <db-qualifer> ] <table>
[ ( <column> [ ASC | DESC ] [ ,...n ] ) ]
{ DISABLE | RESUME}
[ <as-of-time> ]
```
``
### API
```
``
+$ 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)
action=index-action
==
```
``
### Arguments
@ -165,22 +165,22 @@ alter index state change after query in script
Deletes an existing `<index>`.
```
``
<drop-index> ::=
DROP INDEX <index>
ON [ <db-qualifer> ] <table>
[ <as-of-time> ]
```
``
### API
```
``
+$ drop-index
$:
%drop-index
name=@tas
object=qualified-object
==
```
``
### Arguments

8
docs/07-update.md
View File

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

8
docs/08-delete.md
View File

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

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

@ -2,21 +2,21 @@
Removes all rows in a base table.
```
``
<truncate-table> ::=
TRUNCATE TABLE [ <ship-qualifier> ] <table>
[ <as-of-time> ]
```
``
### API
```
``
+$ truncate-table
$:
%truncate-table
table=qualified-object
as-of=(unit as-of)
==
```
``
### 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.
```
``
<query> ::=
[ 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 }
} [ ,...n ]
]
```
``
`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.
@ -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.
```
``
<predicate> ::=
{ [ NOT ] <predicate> | [ ( ] <simple-predicate> [ ) ] }
[ { { AND | OR } [ NOT ] { <predicate> | [ ( ] <simple-predicate> [ ) ] }
[ ...n ]
]
```
``
```
``
<simple-predicate> ::=
{ expression <binary-operator> 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 ) }
| expression [ NOT ] BETWEEN expression [ AND ] expression
| [ 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.
`[ 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.
```
``
<binary-operator> ::=
{ = | <> | != | > | >= | !> | < | <= | !< | 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.
`<inequality-operator>` is any `<binary-operator>` other than equality and `EQUIV`.
```
``
<expression> ::=
{ <qualified-column>
| <constant>
@ -86,24 +86,24 @@ Whitespace is not required between operands and binary-operators, except when th
| <scalar-query>
| <aggregate-function>( { <column> | <scalar> } )
}
```
``
*<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.
```
``
<column> ::=
{ <qualified-column>
| <column-alias>
| <constant> }
```
``
```
``
<qualified-column> ::=
[ [ <ship-qualifier> ]<table-view> | <alias> ].<column-name>
```
``
### API
```
``
+$ query
$:
%query
@ -115,7 +115,7 @@ Whitespace is not required between operands and binary-operators, except when th
selection=select
order-by=(list ordering-column)
==
```
``
### 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>`.
```
``
<merge> ::=
MERGE [ { INTO | FROM } ] <target-table> [ [ AS ] <alias> ]
[ 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> ]
THEN <merge-matched> ] [ ...n ]
[ <as-of-time> ]
```
``
```
``
<target-table> ::= <table-set>
<new-table> ::= <table-set>
<source-table> ::= <table-set>
<matched-predicate> ::= <predicate>
<unmatched-target-predicate> ::= <predicate>
<unmatched-source-predicate> ::= <predicate>
```
``
```
``
<merge-matched> ::=
{ UPDATE [ SET ] { <column> = <scalar-expression> } [ ,...n ]
| DELETE
| 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.
@ -80,12 +80,12 @@ Delete the matched target row.
No operation performed.
```
``
<merge-not-matched> ::=
INSERT [ ( <column> [ ,...n ] ) ]
VALUES ( <scalar-expression> [ ,...n ] )
| NOP
```
``
**`<column>`**
@ -102,7 +102,7 @@ The count out `INSERT` columns and `VALUES` must match.
No operation performed.
### API
```
``
+$ merge
$:
%merge
@ -115,7 +115,7 @@ No operation performed.
unmatched-by-source=(list matching)
as-of=(unit as-of)
==
```
``
### 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)
### AST
```
``
<grant> ::=
GRANT { ADMINREAD | READONLY | READWRITE }
TO { PARENT | SIBLINGS | MOONS | <@p> [ ,...n ] }
@ -27,21 +27,21 @@ To Do:
| NAMESPACE [<database>.] <namespace>
| [<db-qualifier>] <table-object>
}
```
``
### Example
`GRANT READONLY TO ~sampel-palnet ON NAMESPACE my-namespace`
### API
```
``
$:
%grant
permission=grant-permission
to=grantee
grant-target=grant-object
==
```
``
### 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.
```
``
<revoke> ::=
REVOKE { ADMINREAD | READONLY | READWRITE | ALL }
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>
| [<db-qualifier>] <table-object>
}
```
``
### API
```
``
+$ revoke
$:
%revoke
@ -124,7 +124,7 @@ Revokes permission to read from and/or write to selected database objects on the
from=revoke-from
revoke-target=revoke-object
==
```
``
### Arguments