EdgeQL: Graph-Relational Query Language

• EdgeQL is a SQL-style query language for graph-relational data models, offering nested object-shaped query results and robust static type inference.
• It formalizes the object-relational mismatch by unifying scalar, optional, and multi-valued relationships through a precise cardinality algebra and static semantics.
• EdgeQL compiles queries into a single efficient PostgreSQL command, effectively addressing the common ORM n+1 query pattern.

Searching arXiv for the specified paper to ground the article in the current record. EdgeQL is a SQL-style query language for a graph-relational data model, developed as the query language of the Gel system and realized by compiling schemas and queries to PostgreSQL (Sullivan et al., 21 Jul 2025). It is designed to address the object-relational mismatch that arises when applications require nested, object-shaped data while relational systems store and return flat tabular structures. In the formulation given in "Querying Graph-Relational Data" (Sullivan et al., 21 Jul 2025), EdgeQL occupies a middle position between pure relational querying, document databases, graph databases, and ORM-driven object hydration. Its defining characteristics are a logical model of typed objects and links, first-class link properties, nested object-shaped results, and a static type system that infers both value type and cardinality.

1. Definition and motivating problem

EdgeQL is presented as a general-purpose query language whose semantics are aligned with object-shaped access patterns rather than flat row production (Sullivan et al., 21 Jul 2025). The motivating problem is the mismatch between application-level expectations and relational storage conventions. Applications commonly require results such as a movie object containing nested director and actor objects, while the relational representation typically consists of a Movie table, a Person table, and link tables such as Movie.actor(source, target, character).

The paper identifies three common responses to this mismatch. One is the ORM n+1 pattern, in which many small queries are issued. A second is to issue a few larger relational queries and reconstruct nested objects in application code. A third is to write specialized PostgreSQL using record and array aggregation. EdgeQL is intended to make the third approach natural and compositional while preserving database-side execution (Sullivan et al., 21 Jul 2025).

A representative schema is:

$e$9

A representative query is:

$\tau$0

This query returns movies directly in a nested object-like shape rather than as a flat join result. The paper’s central claim is that such object-shaped retrieval can remain strongly typed, compositional, and efficiently compiled to a single PostgreSQL query (Sullivan et al., 21 Jul 2025).

2. Graph-relational data model

The graph-relational model is the logical foundation on which EdgeQL is defined. In this model, data is understood as a graph in which objects or entities are nodes, links or relationships are directed edges, and link properties are metadata attached to edges (Sullivan et al., 21 Jul 2025). This differs from a purely relational presentation in which relationships are represented only indirectly by foreign-key equality and joins.

A key distinction emphasized in the paper is that the graph-relational model associates relationships more closely with their source object. A movie record may contain scalar properties such as title and year, links such as directors and actors, and link properties such as character attached to the actors relationship. By contrast, the relational representation treats source and target symmetrically through foreign keys (Sullivan et al., 21 Jul 2025).

At storage level, each object is modeled as a record mapping labels to sequences of stored values. Stored values are either scalar values or reference values. A reference value contains the referenced object’s unique identifier together with any link properties associated with that relationship. The database store is modeled as a set of triples of the form

$(id,\; \text{TypeName},\; \text{Record})$

with global uniqueness of identifiers across the store, implemented in practice with UUIDs (Sullivan et al., 21 Jul 2025).

This logical organization has several consequences. Links are typed and navigable through paths. Result values may be nested object-shaped computed values rather than homogeneous tables. Link properties are part of the model rather than an implementation detail. Cardinality is tracked explicitly in the type system. This suggests that EdgeQL should be understood not as a replacement for relational storage, but as a higher-level data model that reinterprets relationally stored data in terms better matched to application structure.

3. Type system, cardinality, and result model

A central design decision is that all expressions evaluate to sequences of values. The paper notes that Gel documentation often calls these “sets,” but the formal semantics uses sequences, usually modulo permutation (Sullivan et al., 21 Jul 2025). This unifies scalar fields, optional values, and many-valued relationships under a single result model.

The core typing judgment is

$\Gamma \vdash_\Sigma e : \tau \hash m$

meaning that under schema $\Sigma$ and context $\Gamma$, expression $e$ has type $\tau$ and cardinality mode $m$ (Sullivan et al., 21 Jul 2025). The notable feature is that type and cardinality are inferred together.

The paper defines five cardinality modes:

1. required single: $[1,1]$
2. optional single: $[0,1]$
3. required multi: $[1,\infty]$
4. optional multi: $\Gamma \vdash_\Sigma e : \tau \hash m$0
5. empty: $\Gamma \vdash_\Sigma e : \tau \hash m$1

This formulation replaces SQL’s special treatment of NULL and the usual separation between singleton fields and multi-valued relationships with a uniform account in terms of constraints on sequence-valued fields (Sullivan et al., 21 Jul 2025).

The cardinality algebra is given explicitly. Ordering is

$\Gamma \vdash_\Sigma e : \tau \hash m$2

multiplication is

$\Gamma \vdash_\Sigma e : \tau \hash m$3

with unit $\Gamma \vdash_\Sigma e : \tau \hash m$4, and addition is

$\Gamma \vdash_\Sigma e : \tau \hash m$5

with rounding to the nearest member of $\Gamma \vdash_\Sigma e : \tau \hash m$6 (Sullivan et al., 21 Jul 2025). The paper uses this algebra in typing rules for union, iteration, and related constructs.

Schemas map type names to object types. Object types assign labels to scalar properties, links to other object types, and optional link properties. The paper distinguishes stored value types $\Gamma \vdash_\Sigma e : \tau \hash m$7, used for persisted data, from computed types $\Gamma \vdash_\Sigma e : \tau \hash m$8, which generalize them recursively for query results. Computed values may therefore contain arbitrarily nested shaped data rather than only stored references (Sullivan et al., 21 Jul 2025). This distinction is essential to EdgeQL’s ability to return structured results while retaining static guarantees.

4. Paths, backlinks, and shaping

Path navigation is one of the defining features of EdgeQL. The formalism includes forward projection $\Gamma \vdash_\Sigma e : \tau \hash m$9 and backward projection $\Sigma$0 (Sullivan et al., 21 Jul 2025). The paper gives examples such as:

$\Sigma$1

$\Sigma$2

$\Sigma$3

The important semantic point is that projection may use fields already loaded into an object value or, if absent, read from the stored database record. This makes projection compositional: a value can be partially shaped and then extended by further path evaluation within the same query semantics (Sullivan et al., 21 Jul 2025).

Backlinks provide reverse navigation despite the source-oriented treatment of links. For example, if $\Sigma$4 denotes a person object for “Chris Nolens,” then:

$\Sigma$5

The paper states that backlink typing is intentionally imprecise in cardinality:

$\Sigma$6

unless stronger uniqueness constraints are available, which are left to future work (Sullivan et al., 21 Jul 2025). Reverse traversal is therefore semantically available even though the logical model stores links with source objects.

The shaping operator is the primary mechanism for constructing nested object-shaped results. Abstractly it is written

$\Sigma$7

where a shape $\Sigma$8 is a record

$\Sigma$9

and each field expression is evaluated with $\Gamma$0 bound to one object from the result of $\Gamma$1 (Sullivan et al., 21 Jul 2025). The paper gives the abstract form of a nested movie query:

$\Gamma$2

Shaping serves two roles. It loads stored fields into computed values, and it defines computed output structure. For example,

$\Gamma$3

adds a computed property rating to each movie result without changing stored data (Sullivan et al., 21 Jul 2025). The paper also includes visible and invisible assignment marks, which primarily affect serialization rather than evaluation. It notes, however, that visibility is tracked dynamically in the formalization and that this is a limitation relative to client-side typing concerns.

5. Formal semantics and metatheory

The paper provides both static semantics and big-step dynamic semantics, which is unusual for a system that is also positioned as a practical database implementation (Sullivan et al., 21 Jul 2025). The static semantics is syntax-directed and deterministic. Two metatheoretic properties are stated explicitly.

First, type synthesis is decidable: given a well-formed schema $\Gamma$4, context $\Gamma$5, and expression $\Gamma$6, it is decidable whether there exist $\Gamma$7 and $\Gamma$8 such that

$\Gamma$9

Second, type synthesis is unique: if

$e$0

then

$e$1

(Sullivan et al., 21 Jul 2025). This gives the typing system an inferential and principal character.

The dynamic semantics is state-transforming and uses a dual-store formulation. Conceptually, evaluation includes the schema, an initial database $e$2, an environment $e$3, a current mutable store, a result sequence, and an updated store (Sullivan et al., 21 Jul 2025). The crucial design choice is that expressions always read from the initial store $e$4, while mutations thread through a changing store. The paper explains this as implementation-driven, reflecting PostgreSQL single-query semantics in which reads see the pre-query state.

Representative evaluation rules include variables, primitive values, the empty set, and union, with union defined modulo permutation. Projection is handled through helper functions. Forward projection first checks whether a field is already present in the object value and otherwise reads it from the database. Backlinks use a seek helper that searches the initial store for objects of type $e$5 whose link $e$6 targets a given identifier, returning references augmented with relevant link properties (Sullivan et al., 21 Jul 2025).

The paper also defines type judgments for computed values and for sequences of values, distinguishing typing of stored values from typing of computed values. This supports two headline soundness properties. Preservation states that evaluation of a well-typed expression in well-formed stores and environments yields a result of the expected type and cardinality and preserves store well-formedness. Totality states that well-typed closed expressions always evaluate in the formal model (Sullivan et al., 21 Jul 2025). The paper notes that runtime assertions such as assert_single exist in the implementation but are outside the core formalism.

6. Mutation, compilation, and execution on PostgreSQL

EdgeQL treats mutation as compositional expression syntax rather than only statement-level syntax. The formal core includes insert and update as nested expressions (Sullivan et al., 21 Jul 2025). A representative insertion is:

$\tau$1

This makes object-shaped mutation stylistically parallel to object-shaped querying. The typing rule for insertion checks each field against the target schema, and the dynamic semantics evaluates field expressions, strips computed data down to storable form, allocates a fresh identifier, and inserts a new tuple (Sullivan et al., 21 Jul 2025). For updates, the paper notes an implementation-driven device: edit marks. Once an object has been updated in a query, later attempts to update it in the same query are ignored, mirroring PostgreSQL behavior.

Gel compiles EdgeQL schemas into PostgreSQL schemas in an idiomatic relational form. Each object type becomes a table. Singleton properties or links with cardinality $e$7 or $e$8 become columns. Multi properties or links become separate tables. Link properties become columns on the link table (Sullivan et al., 21 Jul 2025).

EdgeQL notion	PostgreSQL realization
Object type	Table
Singleton property or link	Column
Multi property or link	Separate table
Link property	Column on link table

For the movie example, the paper lists tables such as Movie(id, title, year), Person(id, name, age, born), Movie.directors(source, target), and Movie.actors(source, target, character) (Sullivan et al., 21 Jul 2025). This demonstrates that the graph-relational model is a logical abstraction rather than a rejection of relational storage.

The key implementation technique for nested results is to use PostgreSQL arrays, array_agg, and aggregation of tuples into nested arrays of records. The paper gives SQL that aggregates actor information and a full nested movie shape using correlated subqueries (Sullivan et al., 21 Jul 2025). It also highlights two concrete details: nested data is represented with arrays of tuples, and COALESCE is required because PostgreSQL’s array_agg returns NULL rather than an empty array when aggregating zero rows.

The paper states that compiling all EdgeQL queries into a single PostgreSQL query is an “absolute requirement” of Gel (Sullivan et al., 21 Jul 2025). The stated reasons are transactional coherence, avoidance of n+1 round trips, use of database-side optimization, and alignment with PostgreSQL’s execution model. On IMDB-like object-shaped benchmarks with simulated network delay, Gel is reported to clearly outperform mainstream ORMs and to come within about 20% of hand-written optimized PostgreSQL queries via asyncpg (Sullivan et al., 21 Jul 2025). The significance of this claim lies in the fact that object-shaped retrieval is precisely the workload on which ORM-based strategies commonly incur multiple queries or client-side correlation overhead.

7. Comparisons, limitations, and significance

EdgeQL is explicitly described as SQL-style rather than anti-SQL (Sullivan et al., 21 Jul 2025). It shares declarative querying, filtering and ordering, set-oriented execution, mutation, and database-side computation with SQL. It differs in exposing path navigation instead of explicit join syntax as the primary idiom, treating links and link properties as schema-level notions, incorporating cardinality into static typing, and returning object-shaped results rather than flat tables.

The paper distinguishes graph-relational programming from graph database querying in the Neo4j, GQL, or PGQ sense. Graph query languages are characterized as focusing on graph pattern matching, connectivity, path properties, and graph analytics, whereas EdgeQL focuses on typed object retrieval and mutation, application-facing nested shapes, and efficient graph-like navigation over relational storage (Sullivan et al., 21 Jul 2025). The “graph” in graph-relational thus refers to the logical organization of objects and links rather than to graph pattern analytics.

The work also notes affinities with semistructured and nested-relational approaches such as Lorel and UnQL, along with systems using dot notation and set-valued attributes. Two distinctions are emphasized: a uniform sequence semantics with cardinality constraints rather than a split between singleton and set kinds, and a hard implementation constraint of PostgreSQL single-query compilation (Sullivan et al., 21 Jul 2025).

The comparison to GraphQL is more specific. The resemblance is strongest in shaping syntax and nested field selection, but the paper argues that the underlying philosophy is different. GraphQL is presented as primarily an API query language whose mutations do not have a defined semantics and whose types are not tied to a formal storage model, whereas EdgeQL is a database query language with schema-driven storage semantics, formal query and mutation semantics, static typing, and direct SQL compilation (Sullivan et al., 21 Jul 2025).

The comparison to ORMs is presented as the most practically significant one. ORMs attempt to present relational data as objects but often rely on implicit lazy loading, eager-loading options, ad hoc SQL generation, and application-side reconstruction. EdgeQL instead makes object-shaped querying native, compiles it into one SQL query, provides static typing and cardinality guarantees, and is not tied to any one programming language’s object model (Sullivan et al., 21 Jul 2025). A plausible implication is that EdgeQL should be understood as formalizing the access pattern that ORMs try to emulate informally.

The paper is also explicit about limitations. The formalization does not cover exceptions or runtime assertions, deletion, free objects and arrays, tuples, JSON, inheritance, uniqueness- or exclusivity-based cardinality refinement, access policies, triggers, or migrations (Sullivan et al., 21 Jul 2025). Visibility is modeled dynamically but not statically, which the authors note creates tension with client-side type generation. There is also a discrepancy between the formal semantics and implementation behavior concerning deduplication of object-valued projection results: Gel may deduplicate results such as Movie.directors, while the formal semantics does not. The authors identify this as an open design and formalization tension (Sullivan et al., 21 Jul 2025). Finally, some expressions that are well typed in the formal language are rejected in Gel for ergonomic or client-typing reasons, such as reshaping a property to change its type or cardinality.

Taken together, these features define EdgeQL as a typed, compositional query language for graph-relational data whose central aim is to make nested, object-shaped data access a first-class database capability while preserving the advantages of relational storage and PostgreSQL execution (Sullivan et al., 21 Jul 2025). Its main technical contributions, as stated in the paper, are a formal graph-relational data model, a compositional query language with static and dynamic semantics, a first-class algebra of cardinality, metatheoretic results including decidable and unique type synthesis, preservation and totality, and a practical compilation strategy to PostgreSQL that supports efficient object-shaped workloads.