Database

Table Operations

Tables are the primary containers for documents in AQL. They are accessed through a SchemaInstance and provide methods for inserting, retrieving, and querying documents.

Access a Table

Retrieve a table reference from a schema instance:

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

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

Type-Safe Tables

Provide a generic type parameter to get type-safe operations:

interface User {
  _id: string;
  name: string;
  email: string;
  status: string;
}

const users = db.table<User>("users");

// TypeScript now validates field names and types
const user = await users.get("user-123"); // user is User | null
const emails = await users.key("email");  // string[]

Basic Operations

Retrieve All Documents

A table reference doubles as a stream of all its documents:

const allUsers = await users;
console.log(`Total users: ${allUsers.length}`);

Retrieve by Primary Key

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

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

Retrieve by Secondary Index

const admins = await users.getAll("admin", "role");

Retrieve by Range

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

Chain Operations

Since Table extends Selection and Stream, you can chain any stream operation directly:

// Filter and sort
const activeByName = await users
  .filter((u) => u.key("status").eq("active"))
  .orderBy("name");

// Paginate
const page = await users.orderBy("createdAt").slice(0, 10);

// Aggregate
const count = await users.count();
const avgAge = await users.avg("age");

// Transform
const names = await users.map((u) => u.key("name"));

Insert Documents

// Single document
const ids = await users.insert({
  name: "Alice",
  email: "[email protected]",
  status: "active",
});

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

// Upsert (update on conflict)
await users.insert(
  { _id: "user-123", name: "Updated" },
  { conflict: "update" },
);

For complete CRUD documentation, see CRUD Operations.

Schema Management

AQL organizes data through schemas and instances. A Schema defines the structure of your database (tables, fields, and indexes). Each schema can have multiple instances, and the underlying module implementation determines how instances map to physical storage.

CRUD Operations

CRUD operations (Create, Read, Update, Delete) form the foundation of document management in AQL. All examples assume a schema is already defined and an instance is available.