Vector Search

Docs

Traditional searches match exact words. Search for 'comfortable chair' and you won't find 'ergonomic seating'. Vector search finds results by meaning instead. Your text gets converted to numbers (embeddings) that capture concepts, so similar ideas cluster together, even when the words are completely different. Use vector search when you need to find content by meaning rather than exact keywords. For exact key lookups, use KV storage instead.

Document:
products.json
Reference Code
import { VectorClient } from "@agentuity/vector";

const vector = new VectorClient();
const namespace = "product-search-" + crypto.randomUUID();
const sku = "chair-" + crypto.randomUUID();
const deskSku = "desk-" + crypto.randomUUID();
let namespaceCreated = false;

let summary: {
  chairFound: boolean;
  loaded: number;
  topMatch: string | undefined;
  exists: boolean;
  count: number;
  namespaceVisible: boolean;
};

try {
  await vector.upsert(
    namespace,
    {
      key: sku,
      document: "ErgoMax Pro Chair: ergonomic office chair with lumbar support",
      metadata: { sku, name: "ErgoMax Pro Chair", price: 549 },
    },
    {
      key: deskSku,
      document: "LiftDesk Air: adjustable standing desk for focused work",
      metadata: { sku: deskSku, name: "LiftDesk Air", price: 799 },
    }
  );
  namespaceCreated = true;

  // Read back stored documents by key.
  const chair = await vector.get<{ sku: string; name: string; price: number }>(
    namespace,
    sku
  );
  const documents = await vector.getMany(namespace, sku, deskSku);

  // Search by meaning, not keywords: "comfortable chair" matches the ErgoMax.
  const results = await vector.search<{
    sku: string;
    name: string;
    price: number;
  }>(namespace, {
    query: "comfortable chair",
    limit: 3,
    similarity: 0.3,
  });
  // Inspect namespace state.
  const exists = await vector.exists(namespace);
  const stats = await vector.getStats(namespace);
  const namespaces = await vector.getNamespaces();

  summary = {
    chairFound: chair.exists,
    loaded: documents.size,
    topMatch: results[0]?.metadata?.name,
    exists,
    count: stats.count,
    namespaceVisible: namespaces.includes(namespace),
  };

  await vector.delete(namespace, sku, deskSku);
} finally {
  if (namespaceCreated) {
    await vector.deleteNamespace(namespace);
  }
}

export { summary };
Ready
Output will appear here...