index-management

Index Management

Overview

Create, inspect, and drop search indexes. Wait for indexing to complete after data changes. Indexes automatically track Redis keys matching a specified prefix, or the entries of a single stream.

Good For

• Creating indexes over existing or new Redis data
• Inspecting index schema and configuration
• Rebuilding or dropping indexes
• Ensuring data consistency after bulk writes

Examples

Create an Index

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

const redis = Redis.fromEnv();

// JSON index with nested schema
const index = await redis.search.createIndex({
  name: "products",
  prefix: "product:",
  dataType: "json",
  schema: s.object({
    name: s.string(),
    price: s.number("F64"),
    metadata: s.object({
      brand: s.facet(),
      tags: s.keyword(),
    }),
  }),
});

// Hash index (flat schema only)
const hashIndex = await redis.search.createIndex({
  name: "sessions",
  prefix: "session:",
  dataType: "hash",
  schema: {
    userId: { type: "TEXT" as const },
    lastActive: { type: "DATE" as const },
  },
});

Create a Stream Index

A stream index is bound to one exact stream key (no prefix). Every entry added with XADD becomes a document whose key is the entry ID. The stream does not need to exist yet, and entries removed with XDEL/XTRIM (or by deleting the stream) leave the index too.

const events = await redis.search.createIndex({
  name: "event-search",
  dataType: "stream",
  stream: "events", // exact stream key, not a prefix
  schema: s.object({
    message: s.string(),
    service: s.keyword(),
    severity: s.number("U64"),
    occurredAt: s.date().fast(),
  }),
});

await redis.xadd("events", "*", {
  message: "Payment authorization failed",
  service: "checkout",
  severity: 4,
  occurredAt: new Date().toISOString(),
});
await events.waitIndexing();

const hits = await events.query({
  filter: { message: "authorization", severity: { $gte: 3 } },
});
// [{ key: "1757000000000-0", score: 0.5, data: { message: "...", service: "checkout", severity: 4, ... } }]

// Read the full original entry by its ID
const entries = await redis.xrange("events", hits[0].key, hits[0].key);
const entry = entries[hits[0].key];