Skip to content

upstash/vector-js / skills

upstash-vector-js

Verified

Provides 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.

FileKindSize
SKILL.mdskill md1.4 KB
features/filtering-and-metadata.mdmarkdown2.1 KB
features/index-structure.mdmarkdown4.4 KB
features/namespaces.mdmarkdown929 B
sdk-methods.mdmarkdown3.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
```
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall