Chapter 17Catalog, Names and Session State

This chapter axiomatizes the abstract catalog that underlies GQL programs, explaining how named objects, schemas, and graphs are organized and resolved during query and update execution. We explicitly define the normative core catalog objects, specify qualified names and the rules for resolving them relative to a working schema and working graph, and describe the notion of a session, including its execution sites and policy settings. These ingredients provide the ambient context in which the semantic rules of earlier and later chapters are interpreted.

17.1 Named Objects and Namespaces

Catalog. A GQL-catalog is a persistent, hierarchically organized collection whose root is either a GQL-directory or a GQL-schema. Directories contain directories and schemas; schemas contain the normative primary catalog objects: graphs, graph types, binding tables, and named procedures. Node and edge types are secondary objects contained in graph types.

Identifiers and qualification. Let ${ℝ}_{\mathrm{cat}}$ denote the syntactically well-formed catalog object references of the GQL grammar, and let $\mathbb{Q}$ denote their globally resolved references to catalog objects. A syntactic reference consists of an optional catalog object parent reference and a local object name. Schema paths use “/” and may be absolute or relative (including CURRENT_SCHEMA, HOME_SCHEMA, “.”, and “..”); periods separate any nested secondary-object names. Thus ${ℝ}_{\mathrm{cat}}$ is not modeled as dot-concatenated identifiers detached from the catalog hierarchy.

Catalog descriptors and derived projections. Abstractly, a catalog instance is a rooted tree

where every directory descriptor maps local identifiers to directory or schema descriptors and every schema descriptor maps local identifiers to primary catalog object descriptors. A schema descriptor also records its owner, which is an authorization identifier; a schema created by CREATE SCHEMA has the session authorization identifier as its owner. Let $\mathrm{PDesc}$ denote the domain of named procedure descriptors; its tuple structure is defined in Chapter 18. For concise semantic rules, the following are derived projections after standard reference resolution, not independent top-level dictionaries:

Here a member of $\mathrm{BT}$ is the binding-table object, including its record collection and associated descriptor: binding-table type, ordered/unordered indication, and preferred column-name sequence. The schema’s single named-subobject dictionary ensures that two primary objects with the same local name cannot silently occupy separate sort-specific namespaces.

Active context and working schema/graph. An active context is

where $\mathrm{WSR}$ (working schema reference) and $\mathrm{WG}$ (working graph site) determine relative resolution and execution scope as in the GQL standard object-reference and USE rules.

Working graph and unnamed patterns. The working schema component $\mathrm{WSR}$ is a working schema reference. The graph reference value occupying the working graph site $\mathrm{WG}$ identifies the graph against which unqualified pattern clauses and data-modification operations are evaluated. A USE GE graph-selection step evaluates GE and establishes the current working graph. Subsequent pattern clauses and data-modification operations use that current working graph; they do not carry a separate graph expression of their own.

Example: library catalog projections. Let

represent the abstract graph type descriptor of libraryGraphType defined in Sections 15.4 and 15.5. Let $q_G,q_{\mathrm{GT}}\in \mathbb{Q}$ be the globally resolved references denoted in the current working schema by libraryGraph and libraryGraphType. A catalog containing those objects satisfies

The two maps are derived projections of ${\mathcal{C}}_{\mathrm{lib}}$, not additional components of its one-component tuple.

Example: active library context. In the active-context abstraction used here, let $q_S$ be the current working schema reference and let the graph reference value denoted by $q_G$ occupy ${\mathrm{WG}}_{\mathrm{lib}}$. Then

and an unqualified MATCH is evaluated against the graph referenced by ${\mathrm{WG}}_{\mathrm{lib}}$.

Name resolution. Given a syntactic reference $r\in {ℝ}_{\mathrm{cat}}$ of sort

${\mathrm{resolve}}_S(\mathcal{X},r)$ first resolves its explicit schema/object parent. If the parent is omitted, the grammar supplies the implicit parent “./”, i.e. the current working schema. The local name must identify an object of sort $S$ in that parent; on success, resolution determines its globally resolved reference in $\mathbb{Q}$. Absolute, relative, home, and current-schema references follow their distinct grammar rules, so resolution is not an ordered search between two textual names.

17.2 Qualified References and USE

Syntactic form of the USE graph clause. The standard use-graph clause declares a working graph and its syntactically defined scope:

use-graph-clause ::= "USE" graph-expr

graph-expr ::= ...  /* graph reference or expression */

Here graph-expr denotes an expression whose value is a graph reference. The clause has neither an intervening GRAPH keyword nor an AS alias. Uses in modifying and read-only statements appear in Sections 4.3 and 4.4. This clause requires optional Feature GQ01, USE graph clause.

Using a graph for a statement. Let $\mathit{GE}$ be the graph expression in USE $\mathit{GE}$. It is evaluated in a new child execution context with a material unit incoming working table. The working graph site identified by the clause is set to the resulting graph reference value. Its scope is the enclosing focused linear query or focused linear data-modifying statement part determined by the grammar; there is no concrete USE $\mathit{GE}$ IN $S$ form.

17.3 Session State and Sites

A session context is represented here by the compact tuple

Here $a$ is the session authorization identifier, $\pi$ is the principal it identifies, $z$ is the time-zone displacement, $S^{?}$ and $G^{?}$ are the session schema and session graph (each possibly not set), $\mathrm{Params}$ is the session-parameter dictionary, $\mathrm{ListBeh}$ records offset/ordinal indexing, negative-index, and out-of-range behavior, $T^{?}$ and $R^{?}$ are the current transaction and request context (each possibly not set), and $f$ is the termination flag. The list-behavior policies affect list element references and indexing, not list unwinding. Session SET and RESET commands modify or restore the corresponding characteristics, while session close sets the termination flag.

GQL also operates with execution contexts and sites; assignments to sites (read/write locations) respect declared types, including dynamic unions. Nullability and inference of site nullability are part of the type and assignment semantics. In general, a store assignment is modeled as a partial function from memory state to memory state, equipped with dynamic type checking and the possibility of raising exceptions.