AutoGineer
Generated banner for Upstash Search JS
Generated logo for Upstash Search JS

Upstash Search JS

UpstashOfficialCreated by Upstash

  • Skill
  • Tool integration
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

Work with the @upstash/search TypeScript/JavaScript SDK, a serverless full-text and semantic search database with built-in reranking. Use when adding search to an app or site, creating a search index, upserting documents with searchable content and filterable metadata, running keyword, semantic, or hybrid search queries, reranking results, filtering with SQL-like or structured filter syntax, paginating with range, fetching or deleting documents, resetting an index, or checking index info. Also use when the user asks for site search, product, document, or knowledge-base search, or a managed search service that needs no cluster to run.
— the description by Upstash

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The upstash-search-js skill provides comprehensive guidance for utilizing the @upstash/search TypeScript/JavaScript SDK. It enables developers to implement serverless full-text, semantic, and hybrid search functionality within their applications. The skill covers the entire lifecycle of search operations, including index management, document upsertion with metadata, advanced filtering, and result reranking, all without the need for managing clusters.

What it does

  • Facilitates the creation and management of serverless search indexes.
  • Supports upserting documents with both searchable content and filterable metadata.
  • Enables execution of keyword, semantic, and hybrid search queries.
  • Provides tools for result reranking and structured filtering.
  • Includes methods for document retrieval, deletion, and index maintenance.
  • Offers guidance on pagination and range-based queries.

When to use it

  • When adding full-text or semantic search to a web application or site.
  • When building a product, document, or knowledge-base search feature.
  • When you require a managed, serverless search service that avoids cluster management.
  • When implementing complex filtering or reranking requirements for search results.

Advantages

  • Serverless architecture eliminates the need for manual cluster management.
  • Supports both keyword and semantic search in a single interface.
  • Built-in reranking capabilities improve search result relevance.
  • Flexible metadata filtering allows for precise query control.
  • Native TypeScript support ensures type safety during development.

Usage examples

“How do I initialize the Upstash Search client and add a document?”
The agent provides the code to import the Search class, initialize it with environment variables, and use the index.upsert method to add a document.
“Show me how to perform a search query with filtering.”
The agent demonstrates the index.search method, showing how to pass a query string alongside structured filter parameters.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/upstash/upstash-search-js/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip upstash-search-js.zip -d .agents/skills

Documentation by Upstash

Upstash Search Documentation

Bundled docs and source

Before writing or debugging SDK code, check node_modules/@upstash/search/docs/ for bundled docs and node_modules/@upstash/search/src/ for readable TypeScript source. Read and search the relevant files when present; otherwise use the references in this skill.

Quick Start

Install the TS SDK:

npm install @upstash/search

Create a client and perform a simple upsert + search:

import { Search } from "@upstash/search";

const client = new Search({ url: process.env.UPSTASH_SEARCH_REST_URL, token: process.env.UPSTASH_SEARCH_REST_TOKEN });
const index = client.index("my-index");

await index.upsert({ id: "1", content: { text: "hello world" } });
const results = await index.search({ query: "hello" });

Basic steps:

  • Create an index

  • Insert or update documents

  • Run searches or filtered queries

Other Skill Files

sdk-overview

Provides detailed documentation for all TypeScript SDK commands. Includes:

  • delete: Deleting documents

  • fetch: Retrieving a document

  • info: Index info

  • range: Range queries

  • reset: Clearing an index

  • search: Search queries

  • upsert: Adding/updating documents

  • getting-started: Setup steps for the SDK

quick-start

Provides a fast, end-to-end workflow for creating a Search database, adding documents, and querying them. Covers essential concepts including:

  • Creating a database and storing credentials

  • Adding documents with content and metadata

  • Understanding content vs metadata (searchability and filterability)

  • Performing searches with optional reranking

  • Filtering syntax with SQL-like or structured filters

  • Common pitfalls and best practices

Files

sdk-overview.md

SDK Overview

This skill provides a concise but complete reference for using the Upstash Search TypeScript SDK. It focuses on practical usage patterns, common pitfalls, and efficient examples that combine multiple commands. Use this skill whenever interacting with the Upstash Search SDK, generating agents that must query, mutate, or paginate search indexes.

Client Initialization

You must configure a Search client using either environment variables or a config object.

import { Search } from "@upstash/search";

// Option 1: with explicit config
const client = new Search({ 
  url: process.env.UPSTASH_SEARCH_REST_URL!,
  token: process.env.UPSTASH_SEARCH_REST_TOKEN! 
});
const index = client.index("movies");

// Option 2: using fromEnv (Node.js platform only)
// The constructor will automatically read from process.env if url/token not provided
const client2 = new Search({}); // reads UPSTASH_SEARCH_REST_URL and UPSTASH_SEARCH_REST_TOKEN
const index2 = client2.index("movies");

Type-safe usage:

type Content = { title: string, genre: string };
type Metadata = { year: number };
const indexTyped = client.index<Content, Metadata>("movies");

Upsert (add or update documents)

Pitfalls:

  • Document structure must match the index schema.

  • Content/metadata types are enforced when using generics.

// Single
await index.upsert({
  id: "star-wars",
  content: { title: "Star Wars", genre: "sci-fi" },
  metadata: { year: 1977 }
});

// Multiple
await index.upsert([
  { id: "inception", content: { title: "Inception", genre: "action" }, metadata: { year: 2010 } },
  { id: "matrix", content: { title: "The Matrix", genre: "sci-fi" }, metadata: { year: 1999 } },
]);

// Update
await index.upsert({ id: "star-wars", content: { title: "A New Hope" } });

Fetch (retrieve documents)

Pitfalls:

  • Returns null for IDs not found.

  • Supports prefix matching.

// By IDs
const docs = await index.fetch({ ids: ["star-wars", "inception"] });

// By prefix
const sciFi = await index.fetch({ prefix: "star-" });

Delete (IDs, prefix, or filter)

Pitfalls:

  • Filter deletion is O(N) and slow on large indexes.

  • Prefix deletion removes all matching documents.

// ID list
await index.delete(["star-wars", "inception"]);

// Single ID
await index.delete("star-wars");

// Prefix
await index.delete({ prefix: "star-" });

// Filter — expensive
await index.delete({ filter: "age > 30" });

Search (AI‑powered)

Pitfalls:

  • Default limit = 5.

  • Scores are 0–1.

  • Use filters to restrict by document fields.

// Basic
const results = await index.search({ query: "space opera", limit: 3 });

// With reranking
await index.search({ query: "space opera", limit: 3, reranking: true });

// With filter
await index.search({ query: "space", filter: "category = 'classic'" });

// Adjust semantic vs keyword weighting
await index.search({ query: "robots", semanticWeight: 0.2 });

Range (cursor pagination)

Pitfalls:

  • Stateless: you must pass all parameters every call.

  • cursor = "0" for the first request.

let cursor = "0";
while (cursor !== "") {
  const res = await index.range({ cursor, limit: 2, prefix: "test-" });
  cursor = res.nextCursor;
  console.log(res.documents);
}

Reset (delete all documents)

await index.reset(); // "Success"

Info (index or database level)

// Index-level
const indexInfo = await index.info();
// { documentCount, pendingDocumentCount }

// Database-level
const dbInfo = await client.info();
// { documentCount, pendingDocumentCount, diskSize, indexes: {...} }

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Upstash
Publisher
Upstash (Official)
Source
upstash/skills · skills/upstash-search-js · commit 9f9e3e5
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Upstash.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download upstash-search-js.zip