README
¶
DTQL — YAML serialization of dal.StructuredQuery
DTQL is a 1:1, lossless, human-readable YAML serialization of dalgo's
dal.StructuredQuery for the core relational read-only subset. It is plain YAML
over the existing dal query model — there is no bespoke grammar and no
hand-written parser; the standard gopkg.in/yaml.v3 library produces and
consumes it.
data, err := dtql.Serialize(q) // dal.StructuredQuery -> DTQL-YAML
q2, err := dtql.Deserialize(data) // DTQL-YAML -> dal.StructuredQuery
dtql.Equal(q, q2) // structural equality over the covered surface
This package imports dal but adds no YAML dependency to dal.
Covered subset
DTQL represents a single From (with no Joins()) over a root CollectionRef
(Parent() == nil), the selected Columns, the Where condition (Comparison
and And/Or GroupCondition trees), OrderBy, and Limit/Offset. The
in-scope expression nodes are field references, constants and constant arrays;
literal values are carried inline. Anything outside this subset — joins,
CollectionGroupRef / parented CollectionRef, GroupBy, functions/aggregates,
a cursor (StartFrom), or an operator outside the in-scope set — is rejected
by Serialize with a descriptive error rather than silently dropped.
Node → YAML mapping
dal node |
YAML representation |
|---|---|
From over root CollectionRef |
from: { name: <string>, alias?: <string> } |
Column |
a sequence item under columns:, an expression plus optional as: <alias> |
Comparison |
{ op: <operator>, left: <expr>, right: <expr> } |
GroupCondition (And) |
{ and: [ <condition>, ... ] } |
GroupCondition (Or) |
{ or: [ <condition>, ... ] } |
OrderExpression |
a sequence item under orderBy:, an expression plus optional desc: true |
FieldRef |
{ field: <name> } |
Constant |
{ value: <scalar> } (inline string, bool, int or float) |
Array |
{ values: [ <scalar>, ... ] } (inline, for In membership) |
Operator |
the dal.Operator string itself: ==, In, >, >=, <, <= |
Limit / Offset |
limit: <int> / offset: <int> (omitted when zero) |
An expression node sets exactly one of field, value or values, which
discriminates a FieldRef, a Constant or an Array.
Document shape
A DTQL-YAML document has this canonical key order (top-level keys are omitted
when empty/zero, except from which is required):
from:
name: users
columns:
- field: name
- field: age
as: years
where:
and:
- op: '>='
left:
field: age
right:
value: 18
- or:
- op: In
left:
field: status
right:
values:
- active
- pending
- op: ==
left:
field: country
right:
value: US
orderBy:
- field: name
- field: age
desc: true
limit: 10
offset: 20
Round-trip guarantees
- Structural —
Deserialize(Serialize(q))reconstructs aStructuredQuerystructurally equal toqacrossFrom,Columns,Where(including inlineConstant/Arrayvalues),OrderBy,LimitandOffset(seedtql.Equal). - Canonical —
Serializeemits a canonical document (stable key order and 2-space indentation), soSerialize(Deserialize(d))is byte-identical to a valid in-scope documentdand saved queries diff cleanly across edits.
Errors
Deserialize returns a descriptive error and no partially-populated query on
malformed or schema-invalid input: unknown keys, wrong value types, a missing
required from.name, an unknown operator, a comparison missing left/right,
an expression that is not exactly one of field/value/values, or a
condition that mixes the comparison and group forms.
Published artifacts
The package also publishes DTQL as a tool-validatable artifact: a JSON Schema
(draft 2020-12) generated from the Go types — schema/schema.json (canonical
$id https://dal-go.github.io/dtql/schema.json) and schema/schema.yaml — a
set of example documents under examples/, and a styled index page, served at
https://dal-go.github.io/dtql/.
Documentation
¶
Overview ¶
Package dtql provides a 1:1, lossless, human-readable YAML serialization of dalgo's dal.StructuredQuery for the core relational read-only subset.
DTQL ("DataTug Query Language") is plain YAML over the existing dal query model — there is no bespoke grammar and no hand-written parser; a standard YAML library produces and consumes it. The package serializes an in-scope dal.StructuredQuery to a DTQL-YAML document and deserializes it back, proving a lossless round-trip in both directions.
The covered subset and its node→YAML mapping are documented in dtql/README.md.
This package imports dal but adds no YAML dependency to dal.
Index ¶
Constants ¶
const SchemaID = "https://dal-go.github.io/dtql/schema.json"
SchemaID is the canonical $id of the published DTQL JSON Schema.
Variables ¶
This section is empty.
Functions ¶
func Deserialize ¶
func Deserialize(data []byte) (dal.StructuredQuery, error)
Deserialize reconstructs a dal.StructuredQuery from a DTQL-YAML document. Malformed or schema-invalid input — unknown keys, wrong value types, missing required fields, or an unknown operator — yields a descriptive error and no (partially-populated) query.
func Equal ¶
func Equal(a, b dal.StructuredQuery) bool
Equal reports whether two in-scope dal.StructuredQuery values are structurally equal across the DTQL-covered surface: From, Columns, the Where condition tree (including inline Constant/Array values), OrderBy, Limit and Offset. It compares via the dal accessor interface, so it is agnostic to the concrete query type (e.g. a builder query vs. a deserialized one). It is the equality mechanism behind the structural round-trip guarantee. The in-scope dal nodes are value types (Comparison, GroupCondition, FieldRef, Constant, Array), so the type switches handle the value forms.
func SchemaJSON ¶
func SchemaJSON() []byte
SchemaJSON renders the DTQL JSON Schema as canonical, indented JSON. The schema document holds only strings, bools, ints, slices and maps, so marshaling cannot fail.
func SchemaYAML ¶
func SchemaYAML() []byte
SchemaYAML renders the DTQL JSON Schema as canonical YAML (identical content).
Types ¶
This section is empty.
Source Files