Pure.RelationalSchema.Storage.PureQL.Projection 0.1.0-preview.4.0.0

Pure.RelationalSchema.Storage.PureQL.Projection

Executes PureQL queries against in-memory relational schema datasets: a PureQLQuery from PureQL.CSharp.Model becomes an enumerable IStoredTableDataSet.

Overview

Pure.RelationalSchema.Storage.PureQL.Projection is an interpreter for the PureQL specification 0.1.0-preview.2.0.1 over the Pure relational storage model. Given a collection of IStoredSchemaDataSet objects and a PureQLQuery, it produces an IStoredTableDataSet whose rows are the query's result under the specification's semantics.

Everything runs in memory: no SQL, no external engine.

Public API

PureQLProjection

The only public type. Implements IStoredTableDataSet, IAsyncEnumerable<IRow> and IQueryable<IRow>.

What is supported

Every clause and operator of the specification: from and joins (inner, left, right, full, aliases and self-joins), where, groupBy over any row expression with keys referenced by alias, having, select, aggregate (total queries), orderBy over any expression, distinctBy, pagination, and subqueries read through from, join and in. All operators in the row, projection, group and total contexts are supported, including aggregates with predicate and over, and comparisons, min and max over every type.

A plain query returns one row per row left by where, a total query exactly one row (even over no rows) and a grouped query one row per group. distinctBy runs after orderBy and keeps, of the rows equal on the listed columns, the first in order.

The semantics are the specification's: null equals null and sorts first, ordering comparisons against null are false, lifted operators are null on a null operand, integer is a checked 64-bit integer, decimal is exact (System.Decimal), strings compare by code point, a datetime is an instant written in UTC, and seconds and time / datetime averages round half away from zero to the microsecond. Overflow, division by zero and dates outside the calendar fail the query with the corresponding .NET exception.

The checks the specification leaves to the interpreter run when the projection is built, and a failing query raises ArgumentException: entities, subqueries, sources and fields exist; each field declares its column's type and, after outer joins, its nullability; group key references name a key and repeat its type; source names, group key aliases, column aliases and subquery names are unique; distinctBy lists only column aliases; a subquery reads only subqueries declared before it.

Storage mapping

Empty cell text is NULL. A stored datetime without an offset is read as UTC. Result columns are typed long for integer and double for decimal; result cells hold invariant text (True/False, yyyy-MM-dd, HH:mm:ss[.fffffff], yyyy-MM-ddTHH:mm:ss[.fffffff] in UTC, lower case uuids).

Not supported

• Parameters. There is no API to bind parameter values, so evaluating a parameter (in an expression, a list or pagination) raises NotSupportedException.
• Stored times and datetimes are read to the .NET tick (100 ns); the specification's values have microsecond precision, so finer stored digits are kept as read.

Dependencies

• Pure.Primitives — core primitive value types (String, Date, DateTime, Time, Guid, Number)
• Pure.RelationalSchema — relational schema abstractions (ISchema, ITable, IColumn, column type hierarchy)
• Pure.RelationalSchema.HashCodes — structural hash codes for relational schema types
• Pure.RelationalSchema.Storage — in-memory relational data model (IStoredSchemaDataSet, IStoredTableDataSet, IRow, ICell)
• PureQL.CSharp.Model — PureQL query model (PureQLQuery, Query, expressions per context) — tracks PureQL specification 0.1.0-preview.2.0.0
• Pure.Collections.Generic — generic collection utilities used in row projection

Target Frameworks

• .NET 8
• .NET 9
• .NET 10

Installation

dotnet add package Pure.RelationalSchema.Storage.PureQL.Projection

Usage

// datasets: IEnumerable<IStoredSchemaDataSet> populated by your storage layer
// query:    a PureQLQuery, built directly or deserialized with
//           PureQL.CSharp.Model.Serialization

IStoredTableDataSet result = new PureQLProjection(datasets, query);

foreach (IRow row in result)
{
    // ...
}

await foreach (IRow row in result)
{
    // ...
}

A query selecting one field:

PureQLQuery query = new PureQLQuery(
    new MainPlainQuery(
        new From(new FromEntity("mySchema.myTable")),
        [
            new SelectItemProjection(
                new SelectItemProjectionNonNullable(
                    new SelectItemProjectionString(
                        "name",
                        new StringProjection(new FieldString("mySchema.myTable", "name"))
                    )
                )
            ),
        ]
    )
);

PureQL.CSharp.Model.Samples holds a query for every feature of the specification; this package's tests run all of them.