/upstash-vector-js

Vector TS SDK

Upsert

Add or update vectors. Also accepts raw text (data) to embed automatically.

Pitfalls

• Vector dimension must match index dimension.
• Passing both vector and data is invalid.
• Metadata is optional but recommended for filtering.

Example (single + batch, mix of vector/data)

// Single vector
await index.upsert({ id: "1", vector: [0.1, 0.2], metadata: { type: "doc" } });

// Multiple vectors
await index.upsert(
  [
    { id: "2", vector: [0.2, 0.3] },
    { id: "3", vector: [0.3, 0.4], metadata: { tag: "a" } },
  ],
  { namespace: "ns" }
);

// Using data (auto‑embedding. Only works if the vector index has an embedding model)
await index.upsert({ id: "4", data: "A fantasy movie" });

Fetch

Retrieve vectors by exact ID or prefix.

Example

// Exact
const out = await index.fetch(["1", "2"], { includeMetadata: true });
// → [{ id: "1", metadata: {...} }, null]

// Prefix
await index.fetch({ prefix: "user-" });

Delete

Remove vectors by IDs, prefix, or metadata filter.

Pitfalls

• Only one of ids, prefix, or filter can be used.
• Using filter triggers an O(N) scan.

Example

await index.delete(["1", "2"]);
await index.delete({ prefix: "user-" });
await index.delete({ filter: "status = 'expired'" });

Query

Find the top‑K most similar vectors. Supports dense, sparse, hybrid, and embedded-on-demand queries.

Pitfalls

• Query vector dimension must match index.
• Scores are normalized 0–1 no matter the similarity metric.

Example

// Dense vector
const results = await index.query({
  vector: [0.1, 0.2],
  topK: 3,
  includeMetadata: true,
  filter: "genre = 'fantasy'",
});

// Data (auto‑embedding)
await index.query({ data: "epic fantasy adventure", topK: 2 });

Resumable Query

Long-running, chunked queries with server-side state.

Pitfalls

• Remember to call stop() to free resources.
• fetchNext(k) retrieves N more results.

Example

const { result, fetchNext, stop } = await index.resumableQuery({
  vector: [0.1, 0.2],
  topK: 50,
  maxIdle: 3600,
});

const next = await fetchNext(10);
await stop();

Range

Paginated, stateless scanning of vectors; recommended for large prefix fetches.

Pitfalls

• Always pass cursor; set to 0 initially.

Example

let cursor = 0;
while (cursor !== null) {
  const page = await index.range({ cursor, limit: 100, includeMetadata: true });
  console.log(page.vectors);
  cursor = page.nextCursor;
}

Info

Retrieve index statistics.

Example

const info = await index.info();
/* Returns:
{
  vectorCount: number;
  pendingVectorCount: number;
  indexSize: number;
  dimension: number;
  similarityFunction: "COSINE" | "EUCLIDEAN" | "DOT_PRODUCT";
  denseIndex?: {
    dimension: number;
    similarityFunction: "COSINE" | "EUCLIDEAN" | "DOT_PRODUCT";
    embeddingModel?: string;
  };
  sparseIndex?: {
    embeddingModel?: string;
  };
  namespaces: Record<string, {
    vectorCount: number;
    pendingVectorCount: number;
  }>;
}
*/

Reset

Clear a namespace or the entire index.

Pitfalls

• { all: true } must be explicit.

Example

await index.reset(); // default namespace
await index.reset({ namespace: "my-namespace" });
await index.reset({ all: true });

Advanced

Request Timeout

const index = new Index({
  url,
  token,
  signal: () => AbortSignal.timeout(1000),
});

Telemetry

Disable with env variable:

UPSTASH_DISABLE_TELEMETRY=1