Overview
The get() method retrieves documents from a collection by their unique _id values. This is the most efficient way to fetch documents when you know their identifiers.
Method Signature
get(
ids: Array<string>,
fields?: Array<string> | null,
options?: QueryOptions | null
): Promise<Record<string, Record<string, any>>>
def get(
ids: Sequence[str],
fields: Optional[Sequence[str]] = None,
lsn: Optional[str] = None,
consistency: Optional[ConsistencyLevel] = None
) -> dict[str, dict[str, Any]]:
"""Get documents by their IDs."""
Parameters
An array of document IDs to retrieve.
Optional array of field names to return. If not specified, all fields are returned.
Optional query options:
lsn: Wait for writes up to this Log Sequence Number before retrieving documentsconsistency: Consistency level ('indexed' or 'strong')
Returns
documents
Record<string, Record<string, any>>
A dictionary mapping document IDs to their document objects. Only documents that exist in the collection are included in the result.
If a requested ID doesn’t exist in the collection, it will simply be omitted from the returned dictionary. No error is raised for missing documents.
Examples
Basic Get
Retrieve specific documents by their IDs.
import { Client } from "topk-js";
const client = new Client({
apiKey: "your-api-key",
region: "us-east-1"
});
const documents = await client.collection("books").get([
"book_1",
"book_2",
"book_3"
]);
// Access documents by ID
if (documents["book_1"]) {
console.log(`Title: ${documents["book_1"].title}`);
console.log(`Author: ${documents["book_1"].author}`);
}
// Iterate over all returned documents
for (const [id, doc] of Object.entries(documents)) {
console.log(`${id}: ${doc.title}`);
}
Get with Field Selection
Retrieve only specific fields to reduce data transfer.
import { Client } from "topk-js";
const client = new Client({
apiKey: "your-api-key",
region: "us-east-1"
});
// Only fetch title and author fields
const documents = await client.collection("books").get(
["book_1", "book_2", "book_3"],
["title", "author"]
);
console.log(documents["book_1"]);
// Output: { title: "...", author: "..." }
// Note: Other fields like _id, year, etc. are not included
Get with Consistency Guarantees
Ensure you read the latest version of documents.
import { Client } from "topk-js";
const client = new Client({
apiKey: "your-api-key",
region: "us-east-1"
});
// Perform an update and get the LSN
const lsn = await client.collection("books").upsert([{
_id: "book_1",
title: "Updated Title",
author: "Original Author"
}]);
// Retrieve with consistency guarantee
const documents = await client.collection("books").get(
["book_1"],
null,
{ lsn: lsn, consistency: 'strong' }
);
console.log(documents["book_1"].title); // "Updated Title"
Handling Missing Documents
Gracefully handle cases where some requested documents don’t exist.
import { Client } from "topk-js";
const client = new Client({
apiKey: "your-api-key",
region: "us-east-1"
});
const requestedIds = ["book_1", "book_2", "book_999"];
const documents = await client.collection("books").get(requestedIds);
// Check which documents were found
const foundIds = Object.keys(documents);
const missingIds = requestedIds.filter(id => !documents[id]);
console.log(`Found ${foundIds.length} documents`);
console.log(`Missing ${missingIds.length} documents: ${missingIds.join(", ")}`);
// Process only found documents
for (const [id, doc] of Object.entries(documents)) {
console.log(`${id}: ${doc.title}`);
}
Batch Retrieval
Fetch a large number of documents efficiently.
import { Client } from "topk-js";
const client = new Client({
apiKey: "your-api-key",
region: "us-east-1"
});
// Generate IDs for 100 products
const productIds = Array.from(
{ length: 100 },
(_, i) => `product_${i}`
);
// Fetch all products in one call
const products = await client.collection("products").get(
productIds,
["name", "price", "in_stock"]
);
console.log(`Retrieved ${Object.keys(products).length} products`);
// Calculate statistics
const inStock = Object.values(products)
.filter(p => p.in_stock)
.length;
console.log(`${inStock} products in stock`);
Get Single Document
Retrieve a single document by ID.
import { Client } from "topk-js";
const client = new Client({
apiKey: "your-api-key",
region: "us-east-1"
});
const documents = await client.collection("books").get(["book_1"]);
if (documents["book_1"]) {
const book = documents["book_1"];
console.log(`Found: ${book.title} by ${book.author}`);
} else {
console.log("Book not found");
}
Retrieving Vector Embeddings
Fetch documents including their vector embeddings.
import { Client } from "topk-js";
const client = new Client({
apiKey: "your-api-key",
region: "us-east-1"
});
const documents = await client.collection("books").get(
["book_1", "book_2"],
["title", "embedding"]
);
for (const [id, doc] of Object.entries(documents)) {
console.log(`${doc.title}: ${doc.embedding.length} dimensions`);
}
-
Field Selection: When you only need specific fields, use the
fields parameter to reduce data transfer time and bandwidth.
-
Batch Requests: Fetching multiple documents in a single
get() call is much more efficient than making multiple individual calls.
-
Consistency Trade-offs: The default
'indexed' consistency level offers better performance. Use 'strong' consistency only when you need guaranteed up-to-date reads.
-
Missing Documents: The
get() method handles missing documents gracefully by omitting them from results. Always check if a document ID exists in the returned dictionary before accessing it.
Best Practices
-
Use Get for Known IDs: When you know the exact document IDs,
get() is faster than using query() with filters.
-
Limit Fields: Always specify the
fields parameter when you don’t need all document data.
-
Handle Missing Documents: Always check if a document exists in the result before accessing it to avoid errors.
-
Batch Operations: Retrieve multiple documents in a single call rather than making separate calls for each document.
query() - Search for documents using complex queriesupsert() - Insert or update documentsupdate() - Update existing documentsdelete() - Remove documents from the collection
