Redis Search

RedisOfficialCreated by Redis, Inc.

Skill
Tool integration
Data and AI
MIT
No issues found

From the author

Redis Search guidance covering FT.CREATE schema design, field type selection (TEXT, TAG, NUMERIC, GEO, GEOSHAPE, VECTOR, JSON path), DIALECT 2 query syntax, FT.SEARCH / FT.AGGREGATE / FT.HYBRID command selection, vector similarity with HNSW or FLAT, hybrid retrieval combining lexical and vector ranking, RAG pipelines, zero-downtime index updates via aliases, and debugging with FT.PROFILE and FT.EXPLAIN. Use when defining a search index on Hash or JSON documents, writing FT.SEARCH queries with filters, sorting, aggregation, or vector KNN, tuning HNSW parameters, building a RAG retrieval pipeline, or troubleshooting slow or empty search results.

— the description by Redis, Inc.

AutoGineer summary

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

This skill provides a centralized reference for Redis Search, covering the full lifecycle of index management and query execution. It details schema design using FT.CREATE, command selection between FT.SEARCH, FT.AGGREGATE, and FT.HYBRID, and advanced techniques like vector similarity search (HNSW/FLAT) and RAG pipeline integration. It also includes operational best practices for zero-downtime index updates and performance debugging using FT.PROFILE and FT.EXPLAIN.

What it does

Guides schema design for Hash and JSON documents using various field types.
Explains command selection for lexical, vector, and hybrid search requirements.
Provides patterns for vector similarity search, including HNSW and FLAT algorithm tuning.
Details the construction of declarative aggregation pipelines for analytics.
Offers strategies for zero-downtime index management and schema evolution.
Assists in troubleshooting performance and query results with profiling tools.

When to use it

When defining or modifying a search index schema for Redis.
When building retrieval-augmented generation (RAG) pipelines.
When optimizing complex search queries or aggregation pipelines.
When troubleshooting slow queries or unexpected search results.
When implementing vector similarity search for machine learning applications.

Advantages

Consolidates complex search and vector indexing patterns into a single reference.
Provides clear guidance on choosing the most efficient query command.
Includes practical examples for common search and aggregation scenarios.
Offers actionable advice for performance tuning and debugging.
Supports modern development workflows like RAG and zero-downtime updates.

Usage examples

“How do I create a search index for JSON documents with a vector field?”: The agent provides the FT.CREATE syntax, specifying the ON JSON option, the correct prefix, and the schema definition including the VECTOR field with appropriate DIM and DISTANCE_METRIC settings.
“My vector search is slow. How can I optimize it?”: The agent suggests using FT.PROFILE to identify bottlenecks, checking HNSW parameters like M and EF_RUNTIME, and ensuring the query uses appropriate pre-filters to narrow the search space.
“How do I perform a hybrid search combining text and vector similarity?”: The agent explains the use of FT.HYBRID (for Redis 8.4+) or the pre-filter pattern for earlier versions, detailing how to blend scores using RRF or linear fusion.
“How can I update my index schema without taking the application offline?”: The agent outlines the alias pattern: creating a new index version, populating it, and then using FT.ALIASUPDATE to point the application to the new index seamlessly.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/redis/redis-search/download

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

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

Documentation by Redis, Inc.

Redis Search

Single source of guidance for Redis Search — the retrieval surface that spans lexical, numeric, geo, JSON-path, and vector queries. Vector fields are part of the same FT.CREATE machinery as TEXT/TAG/NUMERIC fields, and FT.HYBRID blends lexical and vector ranking in one command, so this skill covers them together.

When to apply

Creating, modifying, or reviewing a Redis Search index (FT.CREATE, FT.ALTER).
Writing or optimizing FT.SEARCH, FT.AGGREGATE, or FT.HYBRID queries.
Picking between TEXT, TAG, NUMERIC, GEO, GEOSHAPE, VECTOR, or JSON-path fields.
Defining a VECTOR field, choosing HNSW vs FLAT, tuning HNSW parameters.
Building a retrieval-augmented generation (RAG) pipeline.
Rolling out a new index schema without downtime.
Troubleshooting empty results, slow queries, or tokenization issues with FT.EXPLAIN, FT.PROFILE, FT.INFO.

1. Pick the right command

Three query commands. Reach for the narrowest one that fits.

Command	When to use	Mental model	Minimum Redis
FT.SEARCH	Document retrieval, ranked or sorted. Best default.	Returns matching docs directly.	2.0 (module) / 8.0 (built-in)
FT.AGGREGATE	Faceting, computed fields, custom output shape, analytics.	Declarative pipeline: `LOAD`, `APPLY`, `GROUPBY`, `REDUCE`, `SORTBY`.	2.0 / 8.0
FT.HYBRID	Blend lexical (BM25) with vector similarity, with configurable fusion.	Pipeline with explicit `SEARCH` + `VSIM` legs and a `COMBINE` fusion stage.	8.4.0

# FT.SEARCH — most common
FT.SEARCH idx:products "@category:{electronics} @price:[100 500]" LIMIT 0 20 RETURN 3 name price category

# FT.AGGREGATE — top categories by avg price
FT.AGGREGATE idx:products "*" GROUPBY 1 @category REDUCE AVG 1 @price AS avg_price SORTBY 2 @avg_price DESC

# FT.HYBRID (Redis ≥ 8.4) — lexical + vector fusion
FT.HYBRID idx:docs
  SEARCH "@title:transformers" SCORER BM25 YIELD_SCORE_AS lexscore
  VSIM embedding $vec KNN count 1 K 50 YIELD_SCORE_AS vecscore
  COMBINE RRF 2 CONSTANT 60
  PARAMS 2 vec "..."
  DIALECT 2

For Redis < 8.4 the lexical+vector blend is approximated with FT.SEARCH pre-filter + =>[KNN ...]. See references/command-selection.md and references/hybrid-search.md.

2. Schema basics — `FT.CREATE`

FT.CREATE indexes Hash or JSON documents matching a PREFIX. Always set PREFIX. Use DIALECT 2 (the default since Redis 8; required for vector queries).

FT.CREATE idx:products ON HASH PREFIX 1 product:
    SCHEMA
        name TEXT WEIGHT 2.0
        category TAG SORTABLE
        price NUMERIC SORTABLE
        location GEO
        embedding VECTOR HNSW 6
            TYPE FLOAT32
            DIM 1536
            DISTANCE_METRIC COSINE

Pick the narrowest field type that supports your access pattern:

Field type	Use when	Notes
`TEXT`	Full-text search	Tokenized + stemmed; not for exact match
`TAG`	Exact match / filtering	Add `SORTABLE UNF` for fastest tag queries
`NUMERIC`	Range queries, sorting	Prices, counts, timestamps
`GEO`	Lat/long points	Stores, users
`GEOSHAPE`	Polygon / area queries	Delivery zones, regions
`VECTOR`	Similarity search	HNSW or FLAT; see §4
JSON `$.path AS alias`	Nested JSON fields	`ON JSON`; see references/json-indexing.md

The classic mistake is TEXT for a category or status field "because it's a string" — TAG is roughly 10× faster for exact-match filtering.

See references/index-creation.md, references/field-types.md, references/dialect.md, references/ft-create-options.md, references/json-indexing.md.

3. Common queries

Narrow with filters; return only what you need.

# Tag filter + numeric range, sorted by price
FT.SEARCH idx:products "@category:{electronics} @price:[100 500]"
    SORTBY price ASC
    LIMIT 0 20
    RETURN 3 name price category

# Text + tag filter
FT.SEARCH idx:products "wireless headphones @category:{audio}"

# Negation and OR
FT.SEARCH idx:products "@category:{audio} -@brand:{generic} (@price:[0 100] | @on_sale:{true})"

Operators worth remembering: space = AND, | = OR, - = NOT, ~ = optional (scoring boost), =>{$weight: N} = boost. Escape hyphens and special characters inside TAG values (@sku:{ABC\\-123}). See references/query-syntax.md and references/search-syntax-primitives.md for the DSL vocabulary.

For tokenization gotchas (stemming, stopwords, language) see references/text-tokenization.md. For result shaping (SORTBY, RETURN, HIGHLIGHT, SUMMARIZE, NOCONTENT) see references/result-shaping.md. For performance levers (pre-filters, SORTABLE fields, tight RETURN, FT.PROFILE) see references/query-optimization.md.

4. Vector basics

Three vector settings have to match the embedding model exactly:

DIM — output dimensionality (e.g. 1536 for OpenAI text-embedding-3-small). Mismatch produces silent garbage.
DISTANCE_METRIC — COSINE for normalized text embeddings (common case), IP for unnormalized inner-product, L2 for raw Euclidean.
TYPE — usually FLOAT32. Use FLOAT16 or quantized variants only when memory is the binding constraint.

# Index
FT.CREATE idx:docs ON HASH PREFIX 1 doc:
    SCHEMA
        content TEXT
        embedding VECTOR HNSW 6 TYPE FLOAT32 DIM 1536 DISTANCE_METRIC COSINE

# Pure KNN query (top 5 by cosine similarity)
FT.SEARCH idx:docs "*=>[KNN 5 @embedding $vec AS score]"
    PARAMS 2 vec "..."
    SORTBY score
    DIALECT 2

Algorithm	Speed	Accuracy	Memory	Use for
HNSW	Fast (approximate)	~95%+ recall (tunable)	Higher	Production: >10k vectors, latency-sensitive
FLAT	Slow (exact)	100%	Lower	Small corpora (<10k), exact-match required

HNSW tuning levers: M (16–64, connections per node), EF_CONSTRUCTION (100–500, build quality), EF_RUNTIME (query-time candidate list).

See references/vector-query.md, references/algorithm-choice.md.

5. Hybrid retrieval

Two distinct patterns get called "hybrid." Pick by intent.

Filter-then-vector (any Redis version) — apply attribute filters so the engine narrows the search space before the vector comparison.

FT.SEARCH idx:docs "(@category:{tech} @date:[2024 +inf])=>[KNN 10 @embedding $vec AS score]"
    PARAMS 2 vec "..."
    SORTBY score
    DIALECT 2

Lexical + vector fusion (Redis ≥ 8.4) — blend BM25 text scoring with vector similarity, fuse with RRF or LINEAR. Use FT.HYBRID (see §1).

Don't fetch a wide unfiltered result and filter client-side — slower and less accurate. See references/hybrid-search.md.

6. Aggregations and shaping

FT.AGGREGATE is the declarative result-shaping command. Build a pipeline of stages.

# Top 5 categories by total revenue
FT.AGGREGATE idx:orders "@status:{shipped}"
    LOAD 2 @category @amount
    GROUPBY 1 @category
        REDUCE SUM 1 @amount AS revenue
    SORTBY 2 @revenue DESC
    LIMIT 0 5

Common stages: LOAD, APPLY (computed fields), FILTER (post-query), GROUPBY + REDUCE (SUM, COUNT, AVG, FIRST_VALUE, TOLIST), SORTBY, LIMIT.

For long-running result sets use WITHCURSOR + FT.CURSOR READ to page server-side. See references/aggregate-pipeline.md and references/aggregate-cursors.md.

7. RAG pattern

Standard pipeline: embed the query, vector-search Redis, pass top-K context to the LLM.

Practical tips:

Match the metric to the embedding model (almost always COSINE for normalized text models).
Chunk long documents (200–500-token chunks usually beat indexing whole pages).
Batch inserts rather than one call per record.
Pre-filter with attributes (tenant, recency, document type) before the vector search — see §5.
Re-rank at the top of the funnel if precision matters more than recall.

See references/rag-pattern.md.

8. Operations

Zero-downtime schema changes: keep app queries pointed at an alias and swap the underlying index.

FT.CREATE idx:products_v2 ON HASH PREFIX 1 product: SCHEMA ...
FT.ALIASUPDATE products idx:products_v2
# App queries are stable:
FT.SEARCH products "@category:{electronics}"

Useful management commands: FT.INFO, FT.DROPINDEX, FT._LIST, FT.ALIASADD/UPDATE/DEL. See references/index-management.md.

Debug empty or slow queries with FT.EXPLAIN (shows how the query was parsed) and FT.PROFILE (shows execution stats). See references/debugging.md.

9. Client examples

Inline examples in this SKILL.md are CLI / RESP form — the wire protocol every client serializes to. For idiomatic snippets in a specific client:

redis-py (Python, raw client): references/clients/python-redis-py.md
Jedis (Java): references/clients/java-jedis.md
RedisVL (Python, higher-level SDK on top of redis-py): references/clients/python-redisvl.md

Other clients (Lettuce, node-redis, go-redis, NRedisStack, .NET) translate the same CLI form; coverage is tracked as a follow-up.

References

Files

ATTRIBUTION.mdAdded by AutoGineer879 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md11.2 KiB
references/aggregate-cursors.md3.9 KiB
references/aggregate-pipeline.md15.0 KiB
references/algorithm-choice.md4.0 KiB
references/clients/java-jedis.md50.0 KiB
references/clients/python-redis-py.md33.8 KiB
references/clients/python-redisvl.md49.1 KiB
references/command-selection.md9.2 KiB
references/debugging.md4.6 KiB
references/dialect.md2.6 KiB
references/field-types.md3.7 KiB
references/ft-create-options.md6.2 KiB
references/hybrid-search.md5.0 KiB
references/index-creation.md6.9 KiB
references/index-management.md3.9 KiB
references/json-indexing.md6.2 KiB
references/query-optimization.md3.9 KiB
references/query-syntax.md9.7 KiB
references/rag-pattern.md5.1 KiB
references/result-shaping.md5.9 KiB
references/search-syntax-primitives.md6.6 KiB
references/text-tokenization.md4.8 KiB
references/vector-query.md4.7 KiB

references/rag-pattern.md

Implement RAG Retrieval Against Redis Correctly

A RAG pipeline against Redis is three steps: (1) store documents + embeddings in a HASH or JSON index, (2) embed the user's question with the same model, (3) run a KNN query that returns the top-k passages and their distance. Step 3 is where most quality bugs live — see vector-query.md for the canonical query form.

Correct: minimal end-to-end pipeline. The retrieval step is CLI-form first; the embedding/LLM steps are deliberately client-side.

# 1. Index, built once
FT.CREATE idx:bicycle ON HASH PREFIX 1 bicycle:
    SCHEMA
        description TEXT
        type TAG
        price NUMERIC SORTABLE
        description_embeddings VECTOR HNSW 6 TYPE FLOAT32 DIM 1536 DISTANCE_METRIC COSINE

# 2. Documents inserted with HSET (or JSON.SET for JSON indexes).
#    The vector field holds the raw FLOAT32 little-endian blob.

# 3. Retrieval — pre-filtered KNN, score aliased, only the fields the LLM needs returned
FT.SEARCH idx:bicycle "(@type:{mountain})=>[KNN 5 @description_embeddings $query_vec AS score]"
    SORTBY score
    PARAMS 2 query_vec "<query_vector_blob>"
    RETURN 3 description type score
    DIALECT 2

End-to-end pattern (redis-py)

# redis-py — STEP_START rag_pipeline
# Distilled from doctests/search_vss.py
import numpy as np
from redis import Redis
from redis.commands.search.query import Query

r = Redis()

def embed(text: str) -> bytes:
    # Replace with your model — must produce the SAME dim as the index (1536 here)
    return np.array(embed_model.encode(text), dtype=np.float32).tobytes()

def retrieve(question: str, k: int = 5, type_filter: str = "mountain"):
    q = (Query(f"(@type:{{{type_filter}}})=>[KNN {k} @description_embeddings $vec AS score]")
         .sort_by("score").return_fields("description", "type", "score")
         .dialect(2).paging(0, k))
    return r.ft("idx:bicycle").search(q, query_params={"vec": embed(question)})

passages = retrieve("lightweight mountain bicycle for trails")
context = "\n\n".join(d.description for d in passages.docs)
# Pass `context` + question to your LLM of choice.
# STEP_END

End-to-end pattern (Jedis)

// Jedis — STEP_START rag_pipeline
import redis.clients.jedis.UnifiedJedis;
import redis.clients.jedis.search.Query;

try (UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379")) {
    byte[] vec = embed("lightweight mountain bicycle for trails"); // FLOAT32 little-endian
    Query q = new Query("(@type:{mountain})=>[KNN 5 @description_embeddings $vec AS score]")
        .setSortBy("score", true)
        .returnFields("description", "type", "score")
        .addParam("vec", vec)
        .dialect(2)
        .limit(0, 5);
    var result = jedis.ftSearch("idx:bicycle", q);
    // Build the prompt from result.getDocuments() and call your LLM.
}
// STEP_END

Retrieval-quality checklist

Match the metric to the model. Most modern text embedding models pair best with COSINE. Normalize embeddings if the model isn't already producing unit vectors and you use COSINE.
Pre-filter with TAG/NUMERIC before =>[KNN ...] when the user supplies categorical or range constraints — see vector-query.md.
Return only what the LLM consumes (the score alias + the passage text). Returning the embedding wastes bandwidth.
Chunk long documents to a size near the embedding model's effective context (e.g., 200–500 tokens) before indexing — retrieval quality drops sharply on chunks too large for the embedding model.
Re-embed the corpus after a model change — you cannot mix embeddings from different models in the same index.
Batch inserts rather than one call per record (e.g., redis-py pipeline or RedisVL index.load([...])).

Incorrect: Returning everything and filtering client-side, mismatched embedding models, or skipping the pre-filter.

# Bad: client-side filter wastes vector work
results = r.ft("idx:bicycle").search(
    Query("*=>[KNN 1000 @description_embeddings $vec AS score]")
    .sort_by("score").dialect(2),
    query_params={"vec": vec_blob})
mountain = [d for d in results.docs if d.type == "mountain"][:5]

# Bad: question embedded with model A, corpus embedded with model B — distances meaningless

Cross-links

KNN syntax in depth: vector-query.md
Vector index configuration: index-creation.md
Hybrid retrieval (pre-filter vs FT.HYBRID): hybrid-search.md

RedisVL SearchIndex.load() for bulk doc + embedding insertion and VectorQuery end-to-end pipelines live in clients/python-redisvl.md.

Upstream sources

redis-py: doctests/search_vss.py
Jedis: VectorSearchExample.java
Reference: Redis RAG Quickstart, Vector Search

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 Python, 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

Redis, Inc.

Publisher

Redis (Official)

Source

redis/agent-skills · skills/redis-search · commit 74708da

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

Also distributed in

redis/agent-skills

AutoGineer is not affiliated with or endorsed by Redis, Inc. or Redis.

Download ZIP

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

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by Redis, Inc.

Redis Search

When to apply

1. Pick the right command

2. Schema basics — FT.CREATE

3. Common queries

4. Vector basics

5. Hybrid retrieval

6. Aggregations and shaping

7. RAG pattern

8. Operations

9. Client examples

References

Files

references/rag-pattern.md

Implement RAG Retrieval Against Redis Correctly

End-to-end pattern (redis-py)

End-to-end pattern (Jedis)

Retrieval-quality checklist

Cross-links

Upstream sources

Requirements and compatibility

Security

Attribution and licence

Related skills

Anndata

Liteparse

Usfiscaldata

Geopandas

Markitdown

Zarr Python

Download ZIP

2. Schema basics — `FT.CREATE`