Redis Search

Guide unique pour Redis Search — la surface de retrieval couvrant les requêtes lexicales, numériques, géographiques, JSON-path et vectorielles. Les champs vectoriels font partie de la même machinerie FT.CREATE que les champs TEXT/TAG/NUMERIC, et FT.HYBRID fusionne le classement lexical et vectoriel en une seule commande, donc cette skill les couvre ensemble.

Quand appliquer

• Créer, modifier ou examiner un index Redis Search (FT.CREATE, FT.ALTER).
• Écrire ou optimiser des requêtes FT.SEARCH, FT.AGGREGATE ou FT.HYBRID.
• Choisir entre les champs TEXT, TAG, NUMERIC, GEO, GEOSHAPE, VECTOR, ou JSON-path.
• Définir un champ VECTOR, choisir HNSW vs FLAT, régler les paramètres HNSW.
• Construire un pipeline de retrieval-augmented generation (RAG).
• Déployer un nouveau schéma d'index sans interruption de service.
• Résoudre les problèmes de résultats vides, requêtes lentes ou tokenization avec FT.EXPLAIN, FT.PROFILE, FT.INFO.

1. Choisir la bonne commande

Trois commandes de requête. Optez pour la plus spécifique qui convient.

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

# FT.AGGREGATE — top catégories par prix moyen
FT.AGGREGATE idx:products "*" GROUPBY 1 @category REDUCE AVG 1 @price AS avg_price SORTBY 2 @avg_price DESC

# FT.HYBRID (Redis ≥ 8.4) — fusion lexical + vectoriel
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

Pour Redis < 8.4, la fusion lexical+vectoriel est approximée avec FT.SEARCH pré-filtre + =>[KNN ...]. Voir references/command-selection.md et references/hybrid-search.md.

2. Bases du schéma — FT.CREATE

FT.CREATE indexe les documents Hash ou JSON correspondant à un PREFIX. Toujours définir PREFIX. Utiliser DIALECT 2 (défaut depuis Redis 8 ; requis pour les requêtes vectorielles).

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

Choisissez le type de champ le plus spécifique supportant votre modèle d'accès :

L'erreur classique est TEXT pour un champ catégorie ou statut "parce que c'est une chaîne" — TAG est environ 10× plus rapide pour le filtrage exact match.

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

3. Requêtes courantes

Filtrez étroitement ; retournez uniquement ce dont vous avez besoin.

# Filtre tag + plage numérique, trié par prix
FT.SEARCH idx:products "@category:{electronics} @price:[100 500]"
    SORTBY price ASC
    LIMIT 0 20
    RETURN 3 name price category

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

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

Opérateurs à retenir : espace = AND, | = OR, - = NOT, ~ = optionnel (boost de score), =>{$weight: N} = boost. Échappez les tirets et caractères spéciaux dans les valeurs TAG (@sku:{ABC\\-123}). Voir references/query-syntax.md et references/search-syntax-primitives.md pour le vocabulaire DSL.

Pour les pièges de tokenization (stemming, stopwords, langue) voir references/text-tokenization.md. Pour la mise en forme des résultats (SORTBY, RETURN, HIGHLIGHT, SUMMARIZE, NOCONTENT) voir references/result-shaping.md. Pour les leviers de performance (pré-filtres, champs SORTABLE, RETURN serré, FT.PROFILE) voir references/query-optimization.md.

4. Bases vectorielles

Trois paramètres vectoriels doivent correspondre exactement au modèle d'embedding :

• DIM — dimensionnalité de sortie (ex. 1536 pour text-embedding-3-small d'OpenAI). Une non-correspondance produit des résultats silencieusement invalides.
• DISTANCE_METRIC — COSINE pour les embeddings texte normalisés (cas courant), IP pour le produit interne non normalisé, L2 pour l'Euclidien brut.
• TYPE — habituellement FLOAT32. Utiliser FLOAT16 ou variantes quantifiées seulement quand la mémoire est le facteur limitant.

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

# Requête KNN pure (top 5 par similarité cosinus)
FT.SEARCH idx:docs "*=>[KNN 5 @embedding $vec AS score]"
    PARAMS 2 vec "..."
    SORTBY score
    DIALECT 2

Leviers de réglage HNSW : M (16–64, connexions par nœud), EF_CONSTRUCTION (100–500, qualité de build), EF_RUNTIME (liste de candidats au temps de requête).

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

5. Retrieval hybride

Deux patterns distincts s'appellent "hybrides". Choisissez selon l'intention.

Filtre-puis-vectoriel (toute version Redis) — appliquer des filtres d'attribut pour que le moteur réduise l'espace de recherche avant la comparaison vectorielle.

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

Fusion lexical + vectoriel (Redis ≥ 8.4) — fusionner le score texte BM25 avec la similarité vectorielle, fusionner avec RRF ou LINEAR. Utiliser FT.HYBRID (voir §1).

Ne pas récupérer un large résultat non filtré et filtrer côté client — plus lent et moins précis. Voir references/hybrid-search.md.

6. Agrégations et mise en forme

FT.AGGREGATE est la commande déclarative de mise en forme des résultats. Construisez un pipeline d'étapes.

# Top 5 catégories par chiffre d'affaires total
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

Étapes courantes : LOAD, APPLY (champs calculés), FILTER (post-requête), GROUPBY + REDUCE (SUM, COUNT, AVG, FIRST_VALUE, TOLIST), SORTBY, LIMIT.

Pour les longs ensembles de résultats utiliser WITHCURSOR + FT.CURSOR READ pour paginer côté serveur. Voir references/aggregate-pipeline.md et references/aggregate-cursors.md.

7. Pattern RAG

Pipeline standard : embedder la requête, recherche vectorielle Redis, passer le contexte top-K au LLM.

Conseils pratiques :

• Correspondre la métrique au modèle d'embedding (presque toujours COSINE pour les modèles texte normalisés).
• Fragmenter les longs documents (chunks de 200–500 tokens battent habituellement l'indexation de pages entières).
• Insérer par lot plutôt qu'un appel par enregistrement.
• Pré-filtrer avec des attributs (tenant, récence, type de document) avant la recherche vectorielle — voir §5.
• Re-classer en haut de l'entonnoir si la précision importe plus que le rappel.

Voir references/rag-pattern.md.

8. Opérations

Changements de schéma sans interruption : garder les requêtes app pointées vers un alias et échanger l'index sous-jacent.

FT.CREATE idx:products_v2 ON HASH PREFIX 1 product: SCHEMA ...
FT.ALIASUPDATE products idx:products_v2
# Les requêtes app sont stables :
FT.SEARCH products "@category:{electronics}"

Commandes de gestion utiles : FT.INFO, FT.DROPINDEX, FT._LIST, FT.ALIASADD/UPDATE/DEL. Voir references/index-management.md.

Déboguer les requêtes vides ou lentes avec FT.EXPLAIN (affiche comment la requête a été analysée) et FT.PROFILE (affiche les stats d'exécution). Voir references/debugging.md.

9. Exemples client

Les exemples inline dans ce SKILL.md sont en forme CLI / RESP — le protocole wire que chaque client sérialise. Pour les snippets idiomatiques dans un client spécifique :

• redis-py (Python, raw client) : references/clients/python-redis-py.md
• Jedis (Java) : references/clients/java-jedis.md
• RedisVL (Python, SDK haut niveau au-dessus de redis-py) : references/clients/python-redisvl.md

Les autres clients (Lettuce, node-redis, go-redis, NRedisStack, .NET) traduisent la même forme CLI ; la couverture est tracée comme suivi ultérieur.

Références

• Redis: Search and query
• Redis: Vectors
• Redis: Query syntax
• Redis: Query dialects
• Redis: RAG quickstart
• FT.CREATE · FT.SEARCH · FT.AGGREGATE · FT.HYBRID
• RedisVL documentation