diff --git a/.gitignore b/.gitignore index 2df4a48..fc455ec 100644 --- a/.gitignore +++ b/.gitignore @@ -13,6 +13,9 @@ auto-save-list tramp .\#* +# VSCode +.vscode + # Org-mode .org-id-locations *_archive diff --git a/drafts/name-resolution.adoc b/drafts/name-resolution.adoc new file mode 100644 index 0000000..1b9d786 --- /dev/null +++ b/drafts/name-resolution.adoc @@ -0,0 +1,99 @@ += Name Resolution + +== Scope + +This document defines the name resolution rules for tables, views, routines, and variables in the context of a xref:partiql-system.adoc[_PartiQL-System_] and a xref:partiql-system.adoc[_PartiQL-Session_]. + +== Definitions + +[loweralpha,title="Names",start=1] +. **Name**: A relative or absolute name is composed of one or more identifiers. +. **Identifier**: A quoted or unquoted symbol. +. **Lookup Strategy**: Local-first or global-first lookup. + +[loweralpha,title="From PartiQL-System",start=4] +. **Catalog**: A named collection of _objects_ at the root (top-level) of a _PartiQL-system_. +. **Namespace**: A named collection of _objects_; namespaces can contain other namespaces. +. **Object**: A named item of a catalog; e.g. namespace, table, view, or routine. + +== Concepts + +=== Names + +Names composed of one or more identifiers which reference either a database object or a local variable. Identifiers are joined by a __ and a leading __ denotes an absolute name. + +[cols="1e,1,2"] +|=== +| Type | Form | Example + +| Relative Name | `n~1~.---.n~n~` | `hello.world` +| Absolute Name | `.n~1~.---.n~n~` | `.goodnight.moon` + +|=== + +.Name Syntax +[source,ebnf] +---- + ::= | + + ::= [ ]... + + ::= [ ]... + + + ::= + | +---- +// ::= '.' +// ::= '@' +// ::= # [A-Za-z_][A-Za-z_0-9]* + +// +// ::= +// | +// | .... + +// +// ::= [ ] +// | + +//
+// ::=
+// | + +//
::= + +=== Lookup Strategies + +> INCOMPLETE + +== Rules + +Generally and absolute name is always resolved from the root, and a relative name is resolved by prepending the current namespace to the relative name to form an absolute name. + +=== Table Resolution + +Let _N_ be a name (relative or absolute) with symbols _n~1~ , ... , n~i~_ and _S_ be the session namespace with name _. s~1~_ . s~2~ ... _s~j~_ + +. Let _T_ be the absolute table name. +.. If _N_ is relative, then _T = S + N = . s~1~ . s~2~ ... s~j~ . n~1~ . n~2~ ... n~i~_ +.. If _N_ is absolute, then _T = N = . n~1~ . n~2~ ... n~i~_ +. Let _n_ be the number of symbols in _T = . t~1~ . t~2~ ... t~n~_ +. Find the largest _m ≤ n_ such that _t~1~ . t~2~ ... t~m~_ is a database name. +. Any remaining _t~m+1~ ...t~n~_ are path navigations. + +=== Routine Resolution + +// SQL 10.4 + +Let _N_ be a routine name with symbols _n~1~ , ... , n~i~_ and _S_ be the session namespace with name _. s~1~_ . s~2~ ... _s~j~_ + +. If n = 1 then the session path _PATH_ is searched left-to-right. +. Else let _R_ be the absolute routine name. +.. If _N_ is relative, then _R = S + N = . s~1~ . s~2~ ... s~j~ . n~1~ . n~2~. ... n~i~_ . +.. If _N_ is absolute, then _R = N = . n~1~ . n~2~ ... n~i~_ +. Return all routines matching absolute name _R_. + +== Guide + +> PLACEHOLDER \ No newline at end of file diff --git a/drafts/partiql-system.adoc b/drafts/partiql-system.adoc new file mode 100644 index 0000000..5554ca0 --- /dev/null +++ b/drafts/partiql-system.adoc @@ -0,0 +1,120 @@ += PartiQL-System + +// MOTIVATION +// ---------- +// The PartiQL Specification briefly mentions a _database environment_ which is akin to a single catalog and schema, but we have yet-to-define fundamental system concepts such as catalogs, schemas, information_schema, and the SQL PATH. These concepts govern all current PartiQL functionality (table and function resolution), developing functionality such as DDL/DML, as well as future functionality such as views. +// + +== Scope + +This document defines the _PartiQL-System_ and _PartiQL-Session_ which together form the foundation for defining statement semantics. + +== Definitions + +[loweralpha,title="PartiQL-System",start=1] +. **PartiQL-System**: One or more _catalogs_ and a _PartiQL-implementation_. +. **PartiQL-Statement**: A string of characters conforming to the PartiQL syntax and semantics. +. **PartiQL-Implementation**: A processor that executes _statements_ given a _session_. +. **PartiQL-Client**: Any entity which executes statements against a _PartiQL-system_. + +[loweralpha,title="Objects",start=5] +. **Catalog**: A named collection of _objects_ at the root (top-level) of a _PartiQL-system_. +. **Object**: A named item of a catalog; e.g. namespace, table, view, or routine. +. **Namespace**: A named collection of _objects_; namespaces can contain other namespaces. +. **Table**: A named value which is typically (but not necessarily) a collection of structs. +. **View**: A named query statement. +. **Routine**: A named function or procedure which is usable in a _statement_. +.. **Function**: A routine invoked in the context of a value expression. +.. **Procedure**: A routine invoked as a CALL statement. +. **Name**: An identifier associated with a _catalog_ or _object_. + +[loweralpha,title="PartiQL-Session",start=12] +. **PartiQL-session**: A session is state for a _PartiQL-client_ that is used during statement processing. +. **Session namespace**: A reference to a _namespace_ used for name resolution. +. **Session PATH**: An arrays of _namespaces_ which determine the search order for routine resolution. + +NOTE: A _catalog_ is just a _namespace_ at the root level. + +== Concepts + +=== PartiQL-System + +A PartiQL-System is a link:https://en.wikipedia.org/wiki/Database#Database_management_system[Database Management System] composed of one or more catalogs and a PartiQL-Implementation. Each catalog is a named collection of object descriptors such as namespaces, tables, and routines which form a hierarchical structure much like a file system. This abstraction enables PartiQL's statement semantics to be ammenable to various database models such as relational, document, and graph. + +NOTE: A namespace is just like a schema in traditional SQL-systems i.e. a named collection of object descriptors — however, a namespace may contain additional namespaces. + +This example contains two catalogs (1) _benchmarks_ and (2) _samples_. The _benchmarks_ catalog has two namespaces for the TPC tables at different scales, and the _samples_ catalog has two table descriptors. + +.Example +[source] +---- +. +├── benchmarks -- catalog +│   ├── tpc_10 -- namespace +│   │ ├── customer -- table descriptor +│   │ ├── ... +│   │ └── item -- table descriptor +│   └─── tpc_100 +│   ├── customer -- table descriptor +│   ├── ... +│   └── item -- table descriptor +└── samples +    ├── sample_0 -- table descriptor + └── sample_1 -- table descriptor +---- + +=== PartiQL-Statement + +_PartiQL-Statement_ statements can be categorized into four broad categories. + +[loweralpha] +. **Data Statements** +.. **DQL**: Data query language i.e. SELECT-FROM-WHERE. +.. **DML**: Data manipulation statements such as INSERT, UPDATE and DELETE. +.. **DDL**: Data definition statements such as CREATE TABLE. +. **Session Statements**: Statements which modify a PartiQL-Session e.g. SET and USE. +. **Control Statements**: Statements which may invoke stored procedures e.g. CALL and RETURN. +. **Transaction Management**: Statements which set parameters for, and start or terminate transactions (out-of-scope). + +=== PartiQL-Implementation + +A _PartiQL-Implemention_ is responsible for executing statements against the PartiQL-System given a PartiQL-Session. + +=== PartiQL-Client + +A _PartiQL-Client_ holds a PartiQL-Session and executes statments against a PartiQL-Implemention. + +=== PartiQL-Session + +A _PartiQL-Session_ holds information about the client's state such as the user, namespace, and PATH. The namespace and PATH determine how a PartiQL-Implementation resolves names when executing a statement. Please see xref:name-resolution.adoc[Name Resolution] for these rules. + +The current namespace is accessible in statements by using the _NAMESPACE_ variable. A client may update the current namespace with the `SET NAMESPACE TO ` statement. For SQL compatibility, a _PartiQL-system_ must support `USE CATALOG ` and `USE SCHEMA `. + +A session's PATH is accessible in statements by using the *PATH* variable. A client may update the PATH with the `SET PATH TO ` statement. The PATH is an array of names. The PATH is never empty and always contains the current namespace. + +.Session Statements +[source] +---- +USE NAMESPACE ; +USE CATALOG ; +USE SCHEMA ; + +SET NAMESPACE TO ; +SET PATH TO ; +---- + +[IMPORTANT] +==== +The session statements have two distinct behaviors. + +. The `USE` statement comes from SQL systems and **will modify both NAMESPACE and PATH**. +. The `SET` statement **will only modify the specified session attribute**. +==== + +== Rules + +> PLACEHOLDER + +== Guide + +> PLACEHOLDER