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

docs

Browse Source
This commit is contained in:
jackfoxy 2024-01-06 10:15:32 -08:00
parent a1d3639d81
commit 59c043bfa6
6 changed files with 56 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
docs/01-preliminaries.md
View File

@ -1,6 +1,6 @@
# Introduction
## Manifesto
## Introduction
A _first principles_ approach should guide the design and implementation of an Urbit RDBMS. The _urQL_ language, influenced by _The Third Manifesto_ (Date and Darwen), emphasizes composability and type safety. The areas where SQL design was hurried or neglected in terms of theoretical considerations (like nullable columns) have been excluded or corrected, making urQL closer to the _Query Language_ that Codd and Date would have endorsed.
@ -10,9 +10,9 @@ An Urbit-native RDBMS implementation presents new opportunities for composabilit
The Urbit RDBMS, Obelisk, consists of:
1. A scripting language and parser (as documented here).
2. A plan builder.
3. A front-end agent app using the parser and APIs.
1. A scripting language, urQL, and parser.
2. A a database engine, Obelisk.
3. A front-end agent app using the parser and Obelisk APIs. (currently does not exist)
The scripting language, _urQL_, is a derivation of SQL with significant variations.
@ -68,7 +68,7 @@ The following are some common language structures used throughout the reference.
<db-qualifier> ::= { <database>.<namespace>. | <database>.. | <namespace>. }
```
Provides the fully qualified path to a `<table>` or `<view>` object on the host ship.
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 similar to SQL view.)
`<database>` defaults to the current-databse property of the Obelisk agent.
@ -81,12 +81,12 @@ Provides the fully qualified path to a `<table>` or `<view>` object on the host
| <db-qualifier> }
```
Adds ship qualification.
Adds ship qualification to the database/namespace qualifier.
```
<common-table-expression> ::= <transform> [ AS ] <alias>
```
`<transform> ::=` from transform diagram.
`<transform> ::=` from transform diagram. (More on `<transform>` under `<table-set>`.)
`<alias> ::= @t` case-agnostic, see alias naming discussion above.
@ -96,23 +96,26 @@ Each CTE is always referenced by alias, never inlined.
<table-set> ::=
[ <ship-qualifier> ]{ <table> | <view> }
| <common-table-expression>
| ( column-1 [,...column-n] )
| *
```
When `<view>, <table>` have the same name within a namespace, `<view>` is said to "shadow" `<table>` wherever syntax accepts `<table>` or `<view>`.
A base-table, `<table>`, is the only manifestation of `<table-set>` that is not a computation.
A base-tables, `<table>`, are the sole source of content in an Obelisk database and the only manifestation of `<table-set>` that is not a computation.
Every `<table-set>` is a virtual-table and the row type may be a union type.
The `<transform>` command returns a `<table-set>`, hence every `<table-set>` is typed by one or more equivalent urQL `<transform>` commands. This is true because every `<transform>` command is idempotent. (More on this in the section on __Time__.)
If not cached, `<view>` must be evaluated to resolve.
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.
`( column-1 [,...column-n] )` assigns column names to the widest row type of an incoming pass-thru table.
```
<as-of-time> ::=
AS OF { NOW
| <timestamp>
| n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO
| <inline-scalar>
}
```
`*` accepts an incoming pass-thru virtual-table assuming column names established by the previous set-command (`DELETE`, `INSERT`, `MERGE`, `QUERY`, or `UPDATE`) that created the pass-thru.
Similarly `*` as the output of `DELETE`, `INSERT`, `MERGE` creates a pass-thru virtual-table for consumption by the next step or ultimate product of a `<transform>`.
## Literals

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

@ -5,13 +5,7 @@ Creates a new user-space database accessible to any agent running on the ship. T
_To Do NOTE_: Additional features like owner-desk property and GRANT desk permissions are under development.
```
<create-database> ::=
CREATE DATABASE <database>
[ AS OF { NOW
| <timestamp>
| n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO
| <inline-scalar>
}
]
CREATE DATABASE <database> [ <as-of-time> ]
```
## Example
@ -29,7 +23,7 @@ _To Do NOTE_: Additional features like owner-desk property and GRANT desk permis
**`<database>`**
The user-defined name for the new database. It must comply with the Hoon term naming standard.
**`AS OF`**
**`<as-of-time>`**
Timestamp of database creation. Defaults to NOW (current time). Subsequent DDL and data actions must have timestamps greater than this timestamp.
## Remarks

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

@ -3,13 +3,7 @@ Namespaces group various database components, including tables and views. When n
```
<create-namespace> ::=
CREATE NAMESPACE [<database>.]<namespace>
[ AS OF { NOW
| <timestamp>
| n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO
| <inline-scalar>
}
]
CREATE NAMESPACE [<database>.]<namespace> [ <as-of-time> ]
```
## Example
@ -31,7 +25,7 @@ This is a user-defined name for the new namespace. It must adhere to the hoon te
Note: The "sys" namespace is reserved for system use.
**`AS OF`**
**`<as-of-time>`**
Timestamp of namespace creation. Defaults to NOW (current time). When specified timestamp must be greater than latest system timestamp for the database.
## Remarks
@ -44,7 +38,7 @@ system timestamp
## Exceptions
"duplicate key: {<key>}" namespace already exists
AS OF less than latests system timestamp
`<as-of-time>` less than latests system timestamp
# ALTER NAMESPACE
Transfer an existing user `<table>` or `<view>` to another `<namespace>`.
@ -53,12 +47,7 @@ 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 { NOW
| <timestamp>
| n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO
| <inline-scalar>
}
]
[ <as-of-time> ]
```
## API
@ -85,7 +74,7 @@ Indicates the type of the target object.
**`<table> | <view>`**
Name of the object to be transferred to the target namespace.
**`AS OF`**
**`<as-of-time>`**
Timestamp of namespace update. Defaults to NOW (current time). When specified timestamp must be greater than latest system timestamp for the database.
## Remarks
@ -100,7 +89,7 @@ update `<database>.sys.views`
## Exceptions
namespace does not exist
`<table>` or `<view>` does not exist
AS OF less than latests system timestamp
`<as-of-time>` less than latests system timestamp
# DROP NAMESPACE
Deletes a `<namespace>` and all its associated objects.
@ -108,12 +97,7 @@ Deletes a `<namespace>` and all its associated objects.
```
<drop-namespace> ::=
DROP NAMESPACE [ FORCE ] [ <database>. ]<namespace>
[ AS OF { NOW
| <timestamp>
| n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO
| <inline-scalar>
}
]
[ <as-of-time> ]
```
## API
@ -136,7 +120,7 @@ Optionally, force deletion of `<namespace>`.
**`<namespace>`**
The name of `<namespace>` to delete.
**`AS OF`**
**`<as-of-time>`**
Timestamp of namespace deletion. Defaults to NOW (current time). When specified timestamp must be greater than latest system timestamp for the database.
## Remarks
@ -152,4 +136,4 @@ DELETE row from `<database>.sys.namespaces`.
## Exceptions
`<namespace>` does not exist.
`<namespace>` has populated tables and FORCE was not specified.
`AS OF` specified and not less than latest system timestamp for database.
`<as-of-time>` specified and not less than latest system timestamp for database.

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

@ -16,12 +16,7 @@ _NOTE_: Further investigation is needed to understand if there's a reason to spe
[ ON DELETE { NO ACTION | CASCADE | SET DEFAULT } ]
[ ON UPDATE { NO ACTION | CASCADE | SET DEFAULT } ] }
[ ,... n ] ]
[ AS OF { NOW
| <timestamp>
| n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO
| <inline-scalar>
}
]
[ <as-of-time> ]
```
## API
@ -93,7 +88,7 @@ All the values that make up the foreign key in the referencing row(s) are set to
The Obelisk agent raises an error if the parent foreign table has no entry with bunt values.
**`AS OF`**
**`<as-of-time>`**
Timestamp of table creation. Defaults to NOW (current time). When specified timestamp must be greater than system timestamp for the database.
## Remarks
@ -113,7 +108,7 @@ name within namespace already exists for table
table referenced by FOREIGN KEY does not exist
table column referenced by FOREIGN KEY does not exist
aura mis-match in FOREIGN KEY
AS OF timestamp prior to database creation
`<as-of-time>` timestamp prior to database creation
## Example
```
@ -126,6 +121,7 @@ REFERENCES special-offer (product-id, special-offer-id)
# ALTER TABLE
Modify the columns and/or `<foreign-key>`s of an existing `<table>`.
(Available in the urQL parser. Not currently implemented in the Obelisk DB engine.)
```
<alter-> ::=
@ -139,12 +135,7 @@ Modify the columns and/or `<foreign-key>`s of an existing `<table>`.
[ ON UPDATE { NO ACTION | CASCADE } ]
[ ,... n ]
| DROP FOREIGN KEY ( <foreign-key> [ ,... n ] } )
[ AS OF { NOW
| <timestamp>
| n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO
| <inline-scalar>
}
]
[ <as-of-time> ]
```
Example:
@ -228,7 +219,7 @@ All the values that make up the foreign key in the referencing row(s) are set to
The Obelisk agent raises an error if the parent foreign table has no entry with bunt values.
**`AS OF`**
**`<as-of-time>`**
Timestamp of table aleration. Defaults to NOW (current time). When specified timestamp must be greater than latest database system timestamp and greater than the latest data timestamp for the table.
## Remarks
@ -248,7 +239,7 @@ drop a column that does not exist
table referenced by FOREIGN KEY does not exist
table column referenced by FOREIGN KEY does not exist
aura mis-match in FOREIGN KEY
AS OF timestamp prior to latest system timestamp for table
`<as-of-time>` timestamp prior to latest system timestamp for table
# DROP TABLE
@ -257,12 +248,7 @@ Deletes a `<table>` and all associated objects
```
<drop-table> ::=
DROP TABLE [ FORCE ] [ <db-qualifer> ]{ <table> }
[ AS OF { NOW
| <timestamp>
| n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO
| <inline-scalar>
}
]
[ <as-of-time> ]
```
## API
@ -284,7 +270,7 @@ Optionally, force deletion of a table.
**`<table>`**
Name of `<table>` to delete.
**`AS OF`**
**`<as-of-time>`**
Timestamp of table deletion. Defaults to NOW (current time). When specified timestamp must be greater than latest database system timestamp and greater than the latest data timestamp for the table.
## Remarks
@ -304,5 +290,4 @@ DELETE from `<database>.sys.indices`.
`<table>` is populated and FORCE was not specified.
`<table>` used in `<view>` and FORCE was not specified.
`<table>` used in `<foreign-key>` and FORCE was not specified.
AS OF `<timestamp>` prior to latest system timestamp `<timestamp>`.
`<as-of-time>` `<timestamp>` prior to latest system timestamp `<timestamp>`.

16
docs/in-progress/in-prog-prelim Normal file
View File

@ -0,0 +1,16 @@
```
<table-set> ::=
...
| ( column-1 [,...column-n] )
...
```
...
`( column-1 [,...column-n] )` assigns column names to the widest row type of an incoming pass-thru table.
`*` accepts an incoming pass-thru virtual-table assuming column names established by the previous set-command (`DELETE`, `INSERT`, `MERGE`, `QUERY`, or `UPDATE`) that created the pass-thru.
Similarly `*` as the output of `DELETE`, `INSERT`, `MERGE` creates a pass-thru virtual-table for consumption by the next step or ultimate product of a `<transform>`.

1
docs/in-progress/ref-ch10-alter.md
View File

@ -1,3 +1,4 @@
# ALTER INDEX
Modifies the structure of an existing `<index>` on a user `<table>` or `<view>`.