Index Definitions

`IndexDefinition`

interface IndexDefinition {
  fields?: string[]; // Fields for compound indexes
  multi?: boolean; // Multi-valued index
  crossInstance?: boolean; // Also serve CROSS_INSTANCE queries efficiently
}

Define Indexes

Indexes are declared in the indexes property of each table definition:

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

const schema = new Schema("myapp", {
  users: {
    fields: { name: "string", email: "string", role: "string" },
    indexes: {
      email: {}, // Simple index (field name = index name)
      role: {}, // Simple index
      name_role: { fields: ["name", "role"] }, // Compound index
    },
  },
});

Simple Indexes

When fields is omitted, the index name is used as the field name:

indexes: {
  email: {},  // Creates an index on the "email" field
}

Compound Indexes

Provide the fields array for indexes spanning multiple fields:

indexes: {
  full_name: { fields: ["firstName", "lastName"] },
}

Multi Indexes

Set multi: true for array fields where each element should be individually indexed:

indexes: {
  tags: { multi: true },
}

Set crossInstance: true when queries run with CROSS_INSTANCE use the index. The driver then also maintains an index usable across all instances. Without it, the index is optimized for queries scoped to one instance and cross-instance queries using it may be slow. Results are never affected:

indexes: {
  status: { crossInstance: true },
}

Use Indexes in Queries

Once defined, indexes are available for getAll() and between() operations:

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

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

// Range query on an indexed field
const recent = await users.between(
  "createdAt",
  new Date("2024-01-01"),
  new Date(),
);

For more details, see Index Management.