Database

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.

Define a Schema

Create a schema by providing an ID and a definition of tables with their fields and indexes:

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

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

`SchemaDefinition`

A schema definition is a record mapping table names to their TableDefinition:

interface TableDefinition {
  fields: Record<string, FieldType>;
  indexes: Record<string, IndexDefinition>;
}

interface IndexDefinition {
  fields?: string[];  // For compound indexes
  multi?: boolean;    // Multi-valued index
}

Create an Instance

After defining a schema, create an instance to start working with data. The optional id parameter distinguishes multiple instances of the same schema.

// Create the default instance
await schema.createInstance();

// Create a named instance
await schema.createInstance("tenant-abc");

Access an Instance

Retrieve a SchemaInstance to access tables:

// Default instance
const db = schema.instance();

// Named instance
const tenantDb = schema.instance("tenant-abc");

To operate across every instance of the schema, pass the CROSS_INSTANCE sentinel:

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

const everything = schema.instance(CROSS_INSTANCE).table("users");

Destroy an Instance

Remove an instance and its data:

await schema.destroyInstance("tenant-abc");

List Instances

List the IDs of named instances of a schema:

const ids = await schema.listInstances();
// ["tenant-abc", "tenant-xyz"]

The default (unnamed) instance is not included.

Retrieve a Schema

Use the static Schema.get() method to look up a previously defined schema by its ID:

const schema = Schema.get("myapp");

if (schema) {
  const users = schema.instance().table("users");
}

Work with Tables

Once you have a SchemaInstance, access tables by name. The generic type parameter provides type safety for your documents:

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

interface Post {
  _id: string;
  title: string;
  content: string;
  authorId: string;
}

const db = schema.instance();
const users = db.table<User>("users");
const posts = db.table<Post>("posts");

Multi-Tenant Pattern

Schemas with multiple instances support multi-tenant architectures. Each tenant gets an isolated instance of the same schema:

const schema = new Schema("saas", {
  projects: {
    fields: { name: "string" },
    indexes: {},
  },
});

// Create one instance per tenant
await schema.createInstance("tenant-1");
await schema.createInstance("tenant-2");

// Access tenant-specific data
const tenant1Projects = schema.instance("tenant-1").table("projects");
const tenant2Projects = schema.instance("tenant-2").table("projects");

Operations

This section covers practical operations you can perform with the AQL interface. These guides walk through schema management, table access, document CRUD, index usage, filtering, and foreign key lookups.

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.