Overview
The delete() method removes documents from a collection. You can delete documents either by specifying their IDs directly or by using a filter expression to match documents based on their field values.
Document deletion is permanent and cannot be undone. Make sure you have backups or can recreate deleted data if needed.
Method Signature
delete(
expr: Array<string> | LogicalExpression
): Promise<string>
def delete(
expr: Union[Sequence[str], LogicalExpr]
) -> str:
"""Delete documents by their IDs or using a filter expression."""
Parameters
expr
Array<string> | LogicalExpression
required
Either:
- An array of document IDs to delete
- A logical expression that matches documents to delete
Returns
The Log Sequence Number (LSN) at which the deletion was applied.
Examples
Delete by IDs
Delete specific documents by their IDs.
import { Client } from "topk-js";
const client = new Client({
apiKey: "your-api-key",
region: "us-east-1"
});
// Delete multiple documents by ID
const lsn = await client.collection("books").delete([
"book_1",
"book_2",
"book_3"
]);
console.log(`Deleted at LSN: ${lsn}`);
Delete by Filter Expression
Delete documents matching specific criteria.
import { Client } from "topk-js";
import { field } from "topk-js/query";
const client = new Client({
apiKey: "your-api-key",
region: "us-east-1"
});
// Delete all books published before 1950
const lsn = await client.collection("books").delete(
field("published_year").lt(1950)
);
console.log(`Deleted old books at LSN: ${lsn}`);
Delete with Complex Filters
Use complex logical expressions to target specific documents.
import { Client } from "topk-js";
import { field } from "topk-js/query";
const client = new Client({
apiKey: "your-api-key",
region: "us-east-1"
});
// Delete products that are out of stock AND have price > 100
const lsn = await client.collection("products").delete(
field("in_stock").eq(false)
.and(field("price").gt(100))
);
console.log(`Deleted expensive out-of-stock products at LSN: ${lsn}`);
Delete by Field Value
Delete documents based on a single field value.
import { Client } from "topk-js";
import { field } from "topk-js/query";
const client = new Client({
apiKey: "your-api-key",
region: "us-east-1"
});
// Delete all books by a specific author
const lsn = await client.collection("books").delete(
field("author").eq("Ernest Hemingway")
);
console.log(`Deleted books by Ernest Hemingway at LSN: ${lsn}`);
Delete by Range
Delete documents within a specific range of values.
import { Client } from "topk-js";
import { field } from "topk-js/query";
const client = new Client({
apiKey: "your-api-key",
region: "us-east-1"
});
// Delete books published between 1990 and 2000
const lsn = await client.collection("books").delete(
field("published_year").gte(1990)
.and(field("published_year").lte(2000))
);
console.log(`Deleted books from 1990s at LSN: ${lsn}`);
Delete by List Membership
Delete documents where a field contains specific values.
import { Client } from "topk-js";
import { field } from "topk-js/query";
const client = new Client({
apiKey: "your-api-key",
region: "us-east-1"
});
// Delete all books in specific categories
const lsn = await client.collection("books").delete(
field("category").in(["outdated", "removed", "discontinued"])
);
console.log(`Deleted books in removed categories at LSN: ${lsn}`);
Delete with String Matching
Delete documents based on string patterns.
import { Client } from "topk-js";
import { field } from "topk-js/query";
const client = new Client({
apiKey: "your-api-key",
region: "us-east-1"
});
// Delete all temporary or draft entries
const lsn = await client.collection("articles").delete(
field("title").startsWith("DRAFT:")
.or(field("title").startsWith("TEMP:"))
);
console.log(`Deleted draft articles at LSN: ${lsn}`);
Delete with Null Checks
Delete documents where fields are null or missing.
import { Client } from "topk-js";
import { field } from "topk-js/query";
const client = new Client({
apiKey: "your-api-key",
region: "us-east-1"
});
// Delete all products without a price
const lsn = await client.collection("products").delete(
field("price").isNull()
);
console.log(`Deleted products without prices at LSN: ${lsn}`);
Conditional Delete with Query Preview
Query first to see what will be deleted, then delete.
import { Client } from "topk-js";
import { filter, field } from "topk-js/query";
const client = new Client({
apiKey: "your-api-key",
region: "us-east-1"
});
// First, preview what will be deleted
const condition = field("published_year").lt(1900);
const toDelete = await client.collection("books").query(
filter(condition).limit(100)
);
console.log(`Found ${toDelete.length} books to delete`);
// Confirm before deleting
if (toDelete.length > 0) {
const lsn = await client.collection("books").delete(condition);
console.log(`Deleted ${toDelete.length} books at LSN: ${lsn}`);
}
Delete Single Document
Delete a single document by its ID.
import { Client } from "topk-js";
const client = new Client({
apiKey: "your-api-key",
region: "us-east-1"
});
const lsn = await client.collection("books").delete(["book_1"]);
console.log(`Deleted book_1 at LSN: ${lsn}`);
Best Practices
-
Query Before Delete: When using filter expressions, query first to preview what will be deleted, especially for broad filters.
-
Use Specific Filters: Make your filter expressions as specific as possible to avoid accidentally deleting the wrong documents.
-
Backup Important Data: Before performing large delete operations, ensure you have backups or can recreate the data.
-
Batch by IDs: When deleting specific documents, use ID-based deletion with an array of IDs for better performance and precision.
-
Monitor LSN: Store the returned LSN if you need to track when deletions occurred or ensure consistency in subsequent operations.
-
Test Filters: Test your filter expressions on a development collection before running them on production data.
- ID-based deletion is faster than filter-based deletion for small numbers of specific documents.
- Filter-based deletion is more efficient when removing many documents matching a pattern.
- Large delete operations may take time to complete. Consider breaking them into smaller batches if needed.
upsert() - Insert or update documentsupdate() - Update existing documentsget() - Retrieve documents by IDsquery() - Search and filter documents
