AST Structure

The JSON Intermediate Representation (IR) for ObjectQL Queries. The language spoken by the Database Compiler.

The ObjectQL Abstract Syntax Tree (AST) is the runtime specification for data access. When you use the OQL SDK or GraphQL API, your request is parsed into this normalized JSON structure before it touches the database driver.

The Query Object

Every standard retrieval operation resolves to this structure:

interface QueryAST {
    fields?: string[];      // Projection (SELECT)
    filters?: FilterNode;   // Predicates (WHERE)
    sort?: string;          // Ordering (ORDER BY)
    top?: number;           // Limit (LIMIT)
    skip?: number;          // Offset (OFFSET)
    expand?: string[];      // Joins (JOIN / $lookup)
}

1. Filters (The WHERE Clause)

The filtering logic uses LISP-like nested arrays (or simplified JSON syntax) to represent logical trees.

Syntax

[ field, operator, value ] or [ clause, logic, clause ]

Example

// WHERE (category = 'electronics') AND (price > 1000 OR featured = true)
[
  ["category", "=", "electronics"],
  "and",
  [
    ["price", ">", 1000],
    "or",
    ["featured", "=", true]
  ]
]

Supported Operators

2. Projection (The SELECT Clause)

Defines which fields to return.

• Default: Returns all fields if omitted.
• Specific: ["name", "email", "company"]

3. Expansion (The JOIN Clause)

ObjectQL handles relationships via expand. It supports deep compilation strategies (performing standard SQL JOIN or multiple fetches based on performance optimization).

// Get Project and its related Manager info
{
    "expand": ["manager", "customer.name"]
}

4. Sorting

Standard SQL-like sort string.

• "created_at desc"
• "priority desc, due_date asc"

The Mutation AST

For modifications, the AST structure changes slightly:

interface MutationAST {
    id?: string | number;   // Primary Key for Update/Delete
    doc?: Record<string, any>; // The payload for Insert/Update
}