Define PartiQL-System and Name Resolution

.gitignore

@@ -13,6 +13,9 @@ auto-save-list
 tramp
 .\#*
 
+# VSCode
+.vscode
+
 # Org-mode
 .org-id-locations
 *_archive

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 _<period>_ and a leading _<period>_ 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]
+----
+<name> ::= <relative name> | <absolute name>
+
+<relative name> ::= <identifier> [ <period> <identifier> ]... 
+
+<absolute name> ::= <period> <identifier> [ <period> <identifier> ]... 
+
+<identifier>
+    ::= <double quote> <symbol> <double quote>
+      | <symbol>
+----
+// <period> ::= '.'
+// <at> ::= '@'
+// <symbol> ::= # [A-Za-z_][A-Za-z_0-9]*
+
+// <value expression>
+//     ::= <variable expression>
+//       | <table expression>
+//       | ....
+
+// <variable expression>
+//     ::= [ <at> ] <relative name>
+//       | <absolute name>
+
+// <table expression>
+//     ::= <table reference>
+//       | <value expression>
+
+// <table reference> ::= <name>
+
+=== 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

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 <name>` statement. For SQL compatibility, a _PartiQL-system_ must support `USE CATALOG <name>` and `USE SCHEMA <name>`.
+
+A session's PATH is accessible in statements by using the *PATH* variable. A client may update the PATH with the `SET PATH TO <PATH>` statement. The PATH is an array of names. The PATH is never empty and always contains the current namespace. 
+
+.Session Statements
+[source]
+----
+USE NAMESPACE <name>;
+USE CATALOG <name>;
+USE SCHEMA <name>;
+
+SET NAMESPACE TO <name>;
+SET PATH TO <PATH>;
+----
+
+[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