From 59c043bfa6d6ccd3a6f36b03cc8f0c89b75a69ed Mon Sep 17 00:00:00 2001 From: jackfoxy Date: Sat, 6 Jan 2024 10:15:32 -0800 Subject: [PATCH] docs --- docs/01-preliminaries.md | 33 +++++++++++++++------------- docs/02-ddl-database.md | 10 ++------- docs/03-ddl-namespace.md | 34 ++++++++--------------------- docs/04-ddl-table.md | 35 +++++++++--------------------- docs/in-progress/in-prog-prelim | 16 ++++++++++++++ docs/in-progress/ref-ch10-alter.md | 1 + 6 files changed, 56 insertions(+), 73 deletions(-) create mode 100644 docs/in-progress/in-prog-prelim diff --git a/docs/01-preliminaries.md b/docs/01-preliminaries.md index 6e6961a..edce9d2 100644 --- a/docs/01-preliminaries.md +++ b/docs/01-preliminaries.md @@ -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. ::= { .. | .. | . } ``` -Provides the fully qualified path to a `` or `` object on the host ship. +Provides the fully qualified path to a `
` or `` object on the host ship. (NOTE: `` is not yet implemented and is intended to be similar similar to SQL view.) `` defaults to the current-databse property of the Obelisk agent. @@ -81,12 +81,12 @@ Provides the fully qualified path to a `
` or `` object on the host | } ``` -Adds ship qualification. +Adds ship qualification to the database/namespace qualifier. ``` ::= [ AS ] ``` -` ::=` from transform diagram. +` ::=` from transform diagram. (More on `` under ``.) ` ::= @t` case-agnostic, see alias naming discussion above. @@ -96,23 +96,26 @@ Each CTE is always referenced by alias, never inlined. ::= [ ]{
| } | - | ( column-1 [,...column-n] ) | * ``` When `,
` have the same name within a namespace, `` is said to "shadow" `
` wherever syntax accepts `
` or ``. -A base-table, `
`, is the only manifestation of `` that is not a computation. +A base-tables, `
`, are the sole source of content in an Obelisk database and the only manifestation of `` that is not a computation. -Every `` is a virtual-table and the row type may be a union type. +The `` command returns a ``, hence every `` is typed by one or more equivalent urQL `` commands. This is true because every `` command is idempotent. (More on this in the section on __Time__.) -If not cached, `` must be evaluated to resolve. +The row type is defined by the component columns and may be a union type. Hence rows of ``s that are not also `
`s may be of varying length (jagged). The order of rows may be determined in the `` command, and so ``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 { NOW + | + | n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO + | + } +``` -`*` 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 ``. ## Literals diff --git a/docs/02-ddl-database.md b/docs/02-ddl-database.md index adff0bd..449b474 100644 --- a/docs/02-ddl-database.md +++ b/docs/02-ddl-database.md @@ -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 - [ AS OF { NOW - | - | n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO - | - } - ] + CREATE DATABASE [ ] ``` ## Example @@ -29,7 +23,7 @@ _To Do NOTE_: Additional features like owner-desk property and GRANT desk permis **``** The user-defined name for the new database. It must comply with the Hoon term naming standard. -**`AS OF`** +**``** Timestamp of database creation. Defaults to NOW (current time). Subsequent DDL and data actions must have timestamps greater than this timestamp. ## Remarks diff --git a/docs/03-ddl-namespace.md b/docs/03-ddl-namespace.md index a86cd57..e9ff679 100644 --- a/docs/03-ddl-namespace.md +++ b/docs/03-ddl-namespace.md @@ -3,13 +3,7 @@ Namespaces group various database components, including tables and views. When n ``` ::= - CREATE NAMESPACE [.] - [ AS OF { NOW - | - | n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO - | - } - ] + CREATE NAMESPACE [.] [ ] ``` ## 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`** +**``** 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: {}" namespace already exists -AS OF less than latests system timestamp +`` less than latests system timestamp # ALTER NAMESPACE Transfer an existing user `
` or `` to another ``. @@ -53,12 +47,7 @@ Transfer an existing user `
` or `` to another ``. ::= ALTER NAMESPACE [ . ] TRANSFER { TABLE | VIEW } [ ]{
| } - [ AS OF { NOW - | - | n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO - | - } - ] + [ ] ``` ## API @@ -85,7 +74,7 @@ Indicates the type of the target object. **`
| `** Name of the object to be transferred to the target namespace. -**`AS OF`** +**``** 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 `.sys.views` ## Exceptions namespace does not exist `
` or `` does not exist -AS OF less than latests system timestamp +`` less than latests system timestamp # DROP NAMESPACE Deletes a `` and all its associated objects. @@ -108,12 +97,7 @@ Deletes a `` and all its associated objects. ``` ::= DROP NAMESPACE [ FORCE ] [ . ] - [ AS OF { NOW - | - | n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO - | - } - ] + [ ] ``` ## API @@ -136,7 +120,7 @@ Optionally, force deletion of ``. **``** The name of `` to delete. -**`AS OF`** +**``** 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 `.sys.namespaces`. ## Exceptions `` does not exist. `` has populated tables and FORCE was not specified. -`AS OF` specified and not less than latest system timestamp for database. +`` specified and not less than latest system timestamp for database. diff --git a/docs/04-ddl-table.md b/docs/04-ddl-table.md index 96b9d0e..46bb2c6 100644 --- a/docs/04-ddl-table.md +++ b/docs/04-ddl-table.md @@ -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 - | - | n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO - | - } - ] + [ ] ``` ## 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`** +**``** 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 +`` 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 ``s of an existing `
`. +(Available in the urQL parser. Not currently implemented in the Obelisk DB engine.) ``` ::= @@ -139,12 +135,7 @@ Modify the columns and/or ``s of an existing `
`. [ ON UPDATE { NO ACTION | CASCADE } ] [ ,... n ] | DROP FOREIGN KEY ( [ ,... n ] } ) - [ AS OF { NOW - | - | n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO - | - } - ] + [ ] ``` 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`** +**``** 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 +`` timestamp prior to latest system timestamp for table # DROP TABLE @@ -257,12 +248,7 @@ Deletes a `
` and all associated objects ``` ::= DROP TABLE [ FORCE ] [ ]{
} - [ AS OF { NOW - | - | n { SECONDS | MINUTES | HOURS | DAYS | WEEKS | MONTHS | YEARS } AGO - | - } - ] + [ ] ``` ## API @@ -284,7 +270,7 @@ Optionally, force deletion of a table. **`
`** Name of `
` to delete. -**`AS OF`** +**``** 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 `.sys.indices`. `
` is populated and FORCE was not specified. `
` used in `` and FORCE was not specified. `
` used in `` and FORCE was not specified. -AS OF `` prior to latest system timestamp ``. - +`` `` prior to latest system timestamp ``. diff --git a/docs/in-progress/in-prog-prelim b/docs/in-progress/in-prog-prelim new file mode 100644 index 0000000..753b4d2 --- /dev/null +++ b/docs/in-progress/in-prog-prelim @@ -0,0 +1,16 @@ +``` + ::= +... + | ( 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 ``. + + diff --git a/docs/in-progress/ref-ch10-alter.md b/docs/in-progress/ref-ch10-alter.md index ed2318b..570a703 100755 --- a/docs/in-progress/ref-ch10-alter.md +++ b/docs/in-progress/ref-ch10-alter.md @@ -1,3 +1,4 @@ + # ALTER INDEX Modifies the structure of an existing `` on a user `
` or ``.