Database

Insert Results

The insert method on Table<T> returns a Query<string[]> that resolves to an array of the generated or provided primary keys for the inserted documents.

Return Value

// Insert returns string[] (the IDs of inserted documents)
const ids: string[] = await users.insert({
  name: "Alice",
  email: "[email protected]",
});

Examples

Single Document Insert

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

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

const ids = await users.insert({
  name: "John Doe",
  email: "[email protected]",
});

console.log("Inserted document ID:", ids[0]);

Multiple Document Insert

const ids = await users.insert([
  { name: "Alice", email: "[email protected]" },
  { name: "Bob", email: "[email protected]" },
  { name: "Carol", email: "[email protected]" },
]);

console.log(`Inserted ${ids.length} documents`);
console.log("IDs:", ids);

Insert with Conflict Handling

Use the conflict option to control behavior when a document with the same primary key already exists:

// Update matching fields on conflict
const ids = await users.insert(
  { _id: "user-123", name: "Updated Name", lastSeen: new Date() },
  { conflict: "update" },
);

// Replace the entire document on conflict
const ids2 = await users.insert(
  { _id: "user-123", name: "Replaced", email: "[email protected]" },
  { conflict: "replace" },
);

Update and Delete Results

The update, replace, and delete methods return a Query<number> that resolves to the count of affected documents:

// Update returns the number of modified documents
const updated = await users.get("user-123").update({ status: "active" });
console.log(`Modified: ${updated}`);

// Replace returns the number of replaced documents
const replaced = await users.get("user-123").replace({
  _id: "user-123",
  name: "New",
  email: "[email protected]",
});
console.log(`Replaced: ${replaced}`);

// Delete returns the number of deleted documents
const deleted = await users
  .filter((u) => u.key("status").eq("inactive"))
  .delete();
console.log(`Deleted: ${deleted}`);

Results

AQL operations return structured result values that communicate what happened during execution. This section covers the result types produced by write operations and change feeds.

Index Definitions

In AQL, indexes are defined as part of the schema definition rather than created at runtime. The schema declaration specifies which fields to index and what type of index to use.