2.table.md

title	Table
description	The Table query type and its methods for inserting documents, reading them by primary key, secondary index, or range, and applying atomic mutations.
mode	reference

The Table<T> class represents a database table. It inserts documents and retrieves them by primary key, secondary index, or range. It extends Selection<T>, so it also has every multi-document operation and stream method.

Class definition

class Table<T> extends Selection<T> {
  atomicMutation(
    key: string,
    request: AtomicMutation<T>,
  ): Query<AtomicMutationOutcome>;
  insert(
    obj: (DeepPartial<T> & object) | (DeepPartial<T> & object)[],
    options?: InsertOptions,
  ): Query<string[]>;
  get(key: ValueProxyOrValue<string>): SingleSelection<T>;
  getAll(keys: IndexKeys, index?: string): Selection<T>;
  between<TK extends keyof T & string>(
    index: TK,
    low: T[TK] & IndexBound,
    high: T[TK] & IndexBound,
  ): Selection<T>;
}

Access a table

You reach a table 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.

Each field of a document holds a WriteValue: text, a number, a boolean, null, a Date, a list of values or a nested document. A bigint or a symbol does not compile, because no provider stores it as it was given.

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

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

// 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)

Retrieves a single document by its primary key, given as a string or a ValueProxy of a string. Returns a SingleSelection<T>.

Awaiting this selection is declared as T, not T | null. The declaration does not prove that a row exists. A provider can return null or undefined for a missing key, so check the result before you read its fields.

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

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

getAll(keys, index?)

Retrieves multiple documents by key values. keys is an IndexKeys: one key, a list of keys, or a list of compound keys that each hold a compound index's values in its field order. A key is a string, a number, or a boolean. When you pass index, the lookup uses that 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)

Retrieves the documents whose value for the index falls within a range. The lower bound is inclusive, and the upper bound is exclusive. A bound is an IndexBound: a string, number, boolean, Date or null, or a list of them for a compound index.

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

Inherited methods

For conditional single-record writes, see Atomic mutations. atomicMutation() is a table method, not a selection method. It returns an explicit outcome, "applied", "not-applied", or "unknown", rather than a modified count.

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

• The selection methods update(), replace(), and delete(). See Selection.
• The stream methods map(), filter(), orderBy(), count(), join(), and the others listed on Stream.