Chapter 21Diagnostics

This chapter describes how the core semantics of GQL is augmented with diagnostics, in particular how successful completions, warnings, and failures are represented and propagated. We separate the pure result of statement evaluation from error outcomes, and we model the standardized space of GQLSTATUS codes together with their categories and precedence rules. This provides a bridge between the denotational semantics of earlier chapters and the observable behavior of a conforming implementation when exceptions or other conditions arise.

21.1 Errors and Exceptions

Let $\mathrm{Err}$ be the abstract carrier of exception conditions represented in the core semantics, and let $e_{\mathrm{err}}\in \mathrm{Err}$. Let $\mathrm{GQLStatus}$ be the opaque carrier of GQL-status objects, $\zeta \in \mathrm{GQLStatus}$ a primary status object, and $\stackrel{}{\zeta ¯}\in {\mathrm{GQLStatus}}^{\ast }$ a finite list of additional status objects. Any execution may yield a failure outcome $\mathrm{Fail}(e_{\mathrm{err}},\zeta ,\stackrel{}{\zeta ¯})$. Let the failure-outcome carrier be

A failed outcome records an exception condition and has no result.

In accordance with the execution-outcome model, a regular result is either a value or a binding table. Write $\coprod$ for a disjoint sum. Let

be the carriers of regular results and all results, respectively. A successful outcome records exactly one regular or omitted result. The carrier of successful outcomes is

Execution outcomes are then modeled by the disjoint sum

Compound statements are evaluated from left to right. If a component yields $\mathrm{Fail}(e_{\mathrm{err}},\zeta ,\stackrel{}{\zeta ¯})$, no subsequent component is evaluated, and the same failure outcome is propagated to the enclosing compound statement.

21.2 Status Codes

Status domain. Let $\mathit{ℂℍ}$ be the standard digits together with the simple Latin upper-case letters, the repertoire of characters that may occur in a GQLSTATUS code. Define the lexical domains

where, for $n\in \mathbb{N}$, ${\mathit{ℂℍ}}^n$ denotes the set of strings of exactly $n$ characters drawn from $\mathit{ℂℍ}$. Let $\mathit{𝕊𝕋𝔸𝕋𝕌𝕊}\subseteq {\mathit{ℂℍ}}^5$ be the set of status codes (GQLSTATUS codes). Each $\kappa \in \mathit{𝕊𝕋𝔸𝕋𝕌𝕊}$ identifies a single condition. Concretely, every $\kappa \in \mathit{𝕊𝕋𝔸𝕋𝕌𝕊}$ is assumed to admit a unique factorization $\kappa =c_{\kappa }\cdot s_{\kappa }$ with $c_{\kappa }\in \mathit{ℂ𝕃𝔸𝕊𝕊}$ and $s_{\kappa }\in \mathit{𝕊𝕌𝔹ℂ𝕃𝔸𝕊𝕊}$, where $\cdot$ denotes string concatenation. We then define

The exact lexical form and the assignment of class/subclass codes to conditions are defined by the standard and are not modeled here.

Categories. Each $\kappa \in \mathit{𝕊𝕋𝔸𝕋𝕌𝕊}$ has a category

where:

• $S$ (“successful completion”),
• $W$ (“warning”),
• $N$ (“no data”),
• $I$ (“informational”),
• $X$ (“exception”).

We write:

Completion, exception, and informational conditions. A completion condition is one whose code lies in ${\mathit{𝕊𝕋𝔸𝕋𝕌𝕊}}_{\mathrm{compl}}$; these include in particular:

Here ${\kappa }_{\mathrm{ok}}$, and permitted implementation-defined subclasses of successful completion other than the omitted-result subclass, denote successful completion with a regular result; ${\kappa }_{\mathrm{ok}\text{\_}\mathrm{omitted}}$ denotes successful completion with an omitted result, ${\kappa }_{\mathrm{warning}}$ denotes successful completion with a warning, and ${\kappa }_{\mathrm{no}\text{\_}\mathrm{data}}$ denotes successful completion with an empty result.

Except where otherwise specified, an exception condition is one whose code lies in ${\mathit{𝕊𝕋𝔸𝕋𝕌𝕊}}_{\mathrm{exc}}$; such a condition causes the execution of a GQL-request to have no effect on GQL-data or the GQL-catalog beyond recording the diagnostics.

An informational condition is one whose code lies in ${\mathit{𝕊𝕋𝔸𝕋𝕌𝕊}}_{\mathrm{info}}$; informational codes are used only in additional (nested) GQL-status objects and are not used as the primary status of an execution outcome. In particular, the standard informational condition has code $\text{03000}$.

Standard-defined vs. implementation-defined codes. The standard assigns GQLSTATUS codes to all conditions it defines and specifies that these assignments are stable. We write ${\mathit{𝕊𝕋𝔸𝕋𝕌𝕊}}_{\mathrm{std}}\subseteq \mathit{𝕊𝕋𝔸𝕋𝕌𝕊}$ for the set of codes assigned to conditions by this or another International Standard. Let ${\mathit{𝕊𝕋𝔸𝕋𝕌𝕊}}_{\mathrm{impl}}\subseteq \mathit{𝕊𝕋𝔸𝕋𝕌𝕊}$ be the separate set of codes used for implementation-defined conditions in the class/subclass ranges reserved for that purpose by the standard. It is not simply the complement of ${\mathit{𝕊𝕋𝔸𝕋𝕌𝕊}}_{\mathrm{std}}$: an unassigned character string in a reserved standard-defined range does not thereby become an implementation-defined code. Implementation-defined completion conditions use implementation-defined subclasses of classes 00, 01, or 02. An implementation-defined exception condition uses either a permitted implementation-defined subclass of a standard-defined exception class or an implementation-defined class (and subclass), as prescribed by the standard.

Status of execution outcomes. Every execution outcome (successful or failed) carries a primary GQL-status object whose GQLSTATUS field is $\kappa \in \mathit{𝕊𝕋𝔸𝕋𝕌𝕊}$, and may carry a finite list of additional GQL-status objects for secondary conditions. The ISO standard requires:

• If an outcome is successful (i.e., yields a regular or omitted result), then its primary $\kappa$ lies in ${\mathit{𝕊𝕋𝔸𝕋𝕌𝕊}}_{\mathrm{compl}}$.
• If an outcome is failed (i.e., corresponds to some $\mathrm{Fail}(e_{\mathrm{err}},\zeta ,\stackrel{}{\zeta ¯})$), then its primary $\kappa$ lies in ${\mathit{𝕊𝕋𝔸𝕋𝕌𝕊}}_{\mathrm{exc}}$.

The additional GQL-status objects are carried by the list $\stackrel{}{\zeta ¯}$; their internal fields other than GQLSTATUS are left opaque in the core semantics.

When more than one condition could have been raised for a single GQL-request, the GQLSTATUS field of the primary object must respect the precedence rules of the standard:

• Exception conditions for transaction rollback (class code 40) have precedence over all other exception conditions.
• Every exception condition has precedence over every completion condition.
• Among completion conditions, 02000 (no data) has precedence over 01000 (warning).
• 01000 (warning) has precedence over 00000 (successful completion) and its subclasses.

Our semantics is parametric in the implementation-dependent mechanism for choosing a primary exception condition among raised conditions of equal highest precedence.

Status codes for errors. Errors are reported via a GQL-status object whose GQLSTATUS field is a code $\kappa \in {\mathit{𝕊𝕋𝔸𝕋𝕌𝕊}}_{\mathrm{exc}}$ and whose diagnostic record (if present) is a diagnostic record in the sense of the standard: it contains at least the standard fields describing the operation, its operation code, and the current schema, and may be extended with implementation-defined fields (whose names begin with an underscore). In this formalization, the diagnostic record is treated as an opaque value; we do not model its internal structure, and any additional information it carries is implementation-defined. We assume a total mapping

that is consistent with the error classes introduced below. If an error denotes a condition defined by the standard, $\mathrm{code}$ returns that condition’s stable, standard-assigned GQLSTATUS. Only an implementation-defined condition is mapped to a code from ${\mathit{𝕊𝕋𝔸𝕋𝕌𝕊}}_{\mathrm{impl}}$, using the class and subclass ranges reserved by the standard.

21.3 Control Flow

Error classes. We partition the error domain as

Static errors are detected before execution (e.g., unbound variables in the write-part shape, schema mismatch); dynamic errors occur during dynamic evaluation (e.g., numeric overflow or access through an invalidated graph-element reference); concurrency errors arise from isolation and conflict handling; constraint errors correspond to integrity or graph-type violations; resource errors include both standard-defined conditions and conditions introduced by an implementation. The mapping $\mathrm{code}$ respects this classification in the sense that each error class is associated with the corresponding family of GQLSTATUS exception classes prescribed by the standard (for example, data exceptions, transaction rollback, integrity constraint violation, graph type violation).

Primary-condition selection. Errors are reported using a GQLSTATUS code $\kappa$ and a GQL-status object (with optional diagnostic record). When more than one condition could have been raised, the primary status is chosen in accordance with the precedence rules summarized above. Within those constraints, if several raised exception conditions have the same highest precedence, the mechanism that selects the primary condition is implementation-dependent and is not modeled here. The set of conditions that is actually detected may itself vary where evaluation can short-circuit or where concurrency, resource availability, or external failures differ. Consequently, GQL does not guarantee that re-executing the same source text against an apparently identical application state yields the same primary status.