upstash/vector-js / skills
upstash-vector-js
VerifiedProvides quick-start guidance and a unified entry point for Vector features, SDK usage, and integrations. Use when users ask how to work with Vector, its TS SDK, features, or supported frameworks.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 1.4 KB |
| features/filtering-and-metadata.md | markdown | 2.1 KB |
| features/index-structure.md | markdown | 4.4 KB |
| features/namespaces.md | markdown | 929 B |
| sdk-methods.md | markdown | 3.5 KB |
sdk-methods.md
View on GitHub# 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)**
```ts
// 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**
```ts
// 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**
```ts
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**
```ts
// 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**
```ts
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**
```ts
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**
```ts
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**
```ts
await index.reset(); // default namespace
await index.reset({ namespace: "my-namespace" });
await index.reset({ all: true });
```
---
## Advanced
### Request Timeout
```ts
const index = new Index({
url,
token,
signal: () => AbortSignal.timeout(1000),
});
```
### Telemetry
Disable with env variable:
```sh
UPSTASH_DISABLE_TELEMETRY=1
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |