Database

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.

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

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

Create Documents

Insert a Single Document

const ids = await users.insert({
  name: "Alice Johnson",
  email: "[email protected]",
  status: "active",
  createdAt: new Date(),
});

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

Insert Multiple Documents

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

console.log("Inserted IDs:", ids);

Upsert (Insert or Update)

Use the conflict option to handle documents that already exist:

// Update existing fields, keep unmentioned fields
await users.insert(
  { _id: "user-123", name: "Updated Name", lastSeen: new Date() },
  { conflict: "update" },
);

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

Read Documents

Get by Primary Key

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

if (user) {
  console.log("Found:", user.name);
} else {
  console.log("User not found");
}

Get by Secondary Index

const admins = await users.getAll("admin", "role");
console.log(`Found ${admins.length} admins`);

Get by Range

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

Filter Documents

// Filter with a predicate function
const active = await users.filter((user) =>
  user.key("status").eq("active")
    .and(user.key("age").ge(18)),
);

Select Specific Fields

// Keep only listed fields
const profiles = await users.pluck("_id", "name", "avatar");

// Remove sensitive fields
const safe = await users.without("password", "ssn");

Order and Paginate

const page1 = await users.orderBy("createdAt", "desc").slice(0, 10);
const page2 = await users.orderBy("createdAt", "desc").slice(10, 10);

Stream Results

For large result sets, use async iteration to process documents one at a time:

for await (const user of users) {
  console.log("Processing:", user.name);
}

Update Documents

Update a Single Document

The update method modifies specified fields while preserving all other fields.

const count = await users.get("user-123").update({
  status: "active",
  lastLogin: new Date(),
});

if (count === 1) {
  console.log("User updated");
}

Update with Computed Values

Pass a function to compute new values based on current ones:

await users.get("user-123").update((user) => ({
  loginCount: user.key("loginCount").add(1),
  lastLogin: new Date(),
}));

Update Multiple Documents

const count = await users
  .getAll("inactive", "status")
  .update({ status: "active" });

console.log(`Activated ${count} users`);

Replace Documents

The replace method substitutes the entire document. Fields not included in the replacement are removed.

const count = await users.get("user-123").replace({
  _id: "user-123",
  name: "Alice Updated",
  email: "[email protected]",
  status: "active",
  updatedAt: new Date(),
});

Delete Documents

Delete a Single Document

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

if (count === 1) {
  console.log("User deleted");
}

Delete Multiple Documents

const count = await users
  .filter((user) => user.key("status").eq("inactive"))
  .delete();

console.log(`Deleted ${count} inactive users`);

Batch Operations

For large-scale inserts, batch documents to manage memory and throughput:

const documents = Array.from({ length: 10000 }, (_, i) => ({
  index: i,
  value: `Item ${i}`,
  createdAt: new Date(),
}));

const batchSize = 1000;
for (let i = 0; i < documents.length; i += batchSize) {
  const batch = documents.slice(i, i + batchSize);
  await schema.instance().table("items").insert(batch);
  console.log(`Inserted batch ${Math.floor(i / batchSize) + 1}`);
}

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.

Index Management

Indexes improve query performance by enabling the database to locate documents quickly based on indexed fields. In AQL, indexes are defined as part of the schema definition.