Database

Table

The Table<T> class represents a database table and provides methods for inserting documents and retrieving them by primary key, secondary index, or range. It extends Selection<T>, inheriting all multi-document operations and stream capabilities.

Class Definition

class Table<T> extends Selection<T> {
  insert(obj: DeepPartial<T> | DeepPartial<T>[], options?: InsertOptions): Query<string[]>;
  get(key: string): SingleSelection<T>;
  getAll(keys: string | number | boolean | (string | number | boolean)[], index?: string): Selection<T>;
  between<TK extends keyof T>(index: TK, low: T[TK], high: T[TK]): Selection<T>;
}

Access a Table

Tables are accessed through a SchemaInstance. Define a schema, create an instance, then call table():

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

const schema = new Schema("myapp", {
  users: {
    fields: { name: "string", email: "string" },
    indexes: { email: {} },
  },
});

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

Insert Documents

The insert method adds one or more documents to the table and returns the generated IDs.

// Insert a single document
const ids = await users.insert({
  name: "Alice Johnson",
  email: "[email protected]",
});
console.log("Inserted ID:", ids[0]);

// Insert multiple documents
const batchIds = await users.insert([
  { name: "Bob", email: "[email protected]" },
  { name: "Carol", email: "[email protected]" },
]);

// Insert with conflict handling
const upsertIds = await users.insert(
  { _id: "user-123", name: "Updated Name" },
  { conflict: "update" },
);

`InsertOptions`

Option	Type	Description
`conflict`	`"update" \| "replace"`	Behavior when a document with the same ID exists.

Retrieve Documents

`get(key)`

Retrieve a single document by its primary key. Returns a SingleSelection<T>.

const user = await users.get("user-123");

if (user) {
  console.log("Found:", user.name);
}

`getAll(keys, index?)`

Retrieve multiple documents by key values. When index is provided, the lookup uses the specified secondary index instead of the primary key.

// By primary key
const selected = await users.getAll(["user-1", "user-2", "user-3"]);

// By secondary index
const admins = await users.getAll("admin", "role");

`between(index, low, high)`

Retrieve documents where the specified index value falls within a range. The lower bound is inclusive, and the upper bound is exclusive.

const recent = await users.between(
  "createdAt",
  new Date("2024-01-01"),
  new Date(),
);

Inherited Methods

Since Table extends Selection, which extends Stream, it inherits:

Selection methods: update(), replace(), delete() -- see Selection
Stream methods: map(), filter(), orderBy(), count(), join(), and more -- see Stream

Query Types

AQL provides several query classes that form a hierarchy of capabilities. Each class encapsulates a different aspect of database interactions, from full table access down to individual value manipulation.

Selection

The Selection<T> class represents a set of documents and provides methods for bulk mutation operations. It extends Stream<T>, inheriting all transformation, filtering, and aggregation capabilities.