Database

Query

The Query<T> class is the base class for all query types in the AQL system. It implements PromiseLike<T>, so queries can be awaited directly, and provides cursor-based async iteration for streaming results.

Class Definition

class Query<T> extends StagedObject implements PromiseLike<T> {
  run(): Promise<T>;
  then<TResult1, TResult2>(
    onfulfilled?: (value: T) => TResult1 | PromiseLike<TResult1>,
    onrejected?: (reason: any) => TResult2 | PromiseLike<TResult2>,
  ): PromiseLike<TResult1 | TResult2>;
  cursor(): AsyncGenerator<T extends Array<infer T1> ? T1 : T, void, unknown>;
  [Symbol.asyncIterator](): AsyncGenerator<...>;
}

Execute a Query

`run()`

Execute the query pipeline and return the result as a promise.

import { Schema } from "@antelopejs/interface-database";

const schema = Schema.get("myapp")!;
const users = await schema.instance().table("users").run();

Direct `await`

Since Query implements PromiseLike, you can await it directly without calling run():

const users = await schema.instance().table("users");

Both approaches are equivalent. Use whichever reads better in context.

Async Iteration

`cursor()`

Return an AsyncGenerator that yields results one at a time. This is useful for processing large result sets without loading everything into memory.

const cursor = schema.instance().table("users").cursor();

let result = await cursor.next();
while (!result.done) {
  console.log("User:", result.value);
  result = await cursor.next();
}

`for await...of`

The [Symbol.asyncIterator]() method enables the for await...of syntax:

for await (const user of schema.instance().table("users")) {
  console.log("Processing:", user.name);
}

Query Composition

Queries use lazy evaluation. Operations are recorded as pipeline stages and only execute when run(), then(), or iteration begins. This means you can build queries incrementally:

const usersTable = schema.instance().table("users");

// Build different queries from the same base
const activeUsers = usersTable.filter((u) => u.key("status").eq("active"));
const inactiveUsers = usersTable.filter((u) => u.key("status").eq("inactive"));

// Execute them independently
const active = await activeUsers;
const inactive = await inactiveUsers;

Change Feeds

Change feeds provide real-time notifications when documents are inserted, updated, or deleted. Both Stream<T> and SingleSelection<T> expose a changes() method that returns change events.

Datum

The Datum<T> class represents a single value in the query system. It extends Query<T> and provides methods for accessing fields, applying transformations, and performing foreign key lookups on individual values.