querying

Querying & Counting

Overview

Query documents from a search index using type-safe filters with support for pagination, sorting, field selection, scoring, and highlighting. Count matching documents efficiently without returning results.

Good For

• Full-text search with fuzzy matching and phrase queries
• Filtering by numeric ranges, dates, booleans, keywords
• Paginated results with sorting
• Highlighting search terms in results
• Counting documents matching a filter

Examples

Basic Query

import { Redis, s } from "@upstash/redis";

const redis = Redis.fromEnv();

const index = await redis.search.createIndex({
  name: "products",
  prefix: "product:",
  dataType: "json",
  schema: s.object({
    name: s.string(),
    price: s.number("F64"),
    category: s.keyword(),
    inStock: s.boolean(),
  }),
});

// Insert data
await redis.json.set("product:1", "$", {
  name: "Gaming Laptop",
  price: 1299.99,
  category: "electronics",
  inStock: true,
});
await redis.json.set("product:2", "$", {
  name: "Wireless Mouse",
  price: 29.99,
  category: "electronics",
  inStock: true,
});
await redis.json.set("product:3", "$", {
  name: "Laptop Stand",
  price: 49.99,
  category: "accessories",
  inStock: false,
});
await index.waitIndexing();

// Query with filter and return data
const results = await index.query({
  filter: { category: { $eq: "electronics" } },
  select: { name: true, price: true },
});
// [
//   { key: "product:1", score: ..., data: { name: "Gaming Laptop", price: 1299.99 } },
//   { key: "product:2", score: ..., data: { name: "Wireless Mouse", price: 29.99 } },
// ]

Keys Only (No Data)

// Set select to {}
const keysOnly = await index.query({
  filter: { inStock: { $eq: true } },
  select: {},
});
// [{ key: "product:1", score: ... }, { key: "product:2", score: ... }]

Pagination

const page2 = await index.query({
  filter: { category: { $eq: "electronics" } },
  select: { name: true },
  limit: 10,
  offset: 10, // skip first 10 results
});