redis-search

Redis Search

Redis Search に関するガイダンスを一元的にまとめています。語彙、数値、地理空間、JSON パス、ベクトルの各クエリを網羅する検索機能です。ベクトルフィールドは TEXT／TAG／NUMERIC フィールドと同じ FT.CREATE の仕組みで定義し、FT.HYBRID は語彙検索とベクトル検索のランキングを 1 つのコマンドで融合するため、このスキルではこれらをまとめて扱います。

適用する場面

• Redis Search インデックス（FT.CREATE、FT.ALTER）の作成、変更、レビュー。
• FT.SEARCH、FT.AGGREGATE、FT.HYBRID クエリの作成や最適化。
• TEXT、TAG、NUMERIC、GEO、GEOSHAPE、VECTOR、JSON パスフィールドの選択。
• VECTOR フィールドの定義、HNSW と FLAT の選択、HNSW パラメーターの調整。
• 検索拡張生成（RAG）パイプラインの構築。
• ダウンタイムなしでの新しいインデックススキーマの展開。
• FT.EXPLAIN、FT.PROFILE、FT.INFO を使った、結果が空になる問題、クエリの遅延、トークン化の問題のトラブルシューティング。

1. 適切なコマンドを選ぶ

クエリコマンドは 3 種類あります。要件に合う、最も限定的なコマンドを選んでください。

コマンド	使用する場面	考え方	必要な Redis バージョン
FT.SEARCH	ランキングやソートを行うドキュメント検索。最適なデフォルトです。	一致するドキュメントを直接返します。	2.0（モジュール）／8.0（組み込み）
FT.AGGREGATE	ファセット、計算フィールド、カスタム出力形式、分析。	LOAD、APPLY、GROUPBY、REDUCE、SORTBY を使う宣言型パイプラインです。	2.0／8.0
FT.HYBRID	融合方法を設定し、語彙検索（BM25）とベクトル類似度を組み合わせます。	明示的な SEARCH と VSIM の処理、および COMBINE 融合ステージで構成するパイプラインです。	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

Redis 8.4 未満では、語彙検索とベクトル検索の融合を FT.SEARCH の事前フィルターと =>[KNN ...] で近似します。references/command-selection.md と references/hybrid-search.md を参照してください。

2. スキーマの基本 — FT.CREATE

FT.CREATE は PREFIX に一致する Hash または JSON ドキュメントをインデックス化します。必ず PREFIX を設定してください。DIALECT 2 を使用してください（Redis 8 以降のデフォルトであり、ベクトルクエリには必須です）。

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

アクセスパターンに対応する、最も限定的なフィールド型を選んでください。

フィールド型	使用する場面	備考
TEXT	全文検索	トークン化と語幹処理を行います。完全一致には使用しないでください
TAG	完全一致／フィルタリング	タグクエリを最速にするには SORTABLE UNF を追加します
NUMERIC	範囲クエリ、ソート	価格、件数、タイムスタンプ
GEO	緯度／経度の座標	店舗、ユーザー
GEOSHAPE	ポリゴン／エリアクエリ	配送区域、地域
VECTOR	類似度検索	HNSW または FLAT。§4 を参照
JSON $.path AS alias	ネストされた JSON フィールド	ON JSON を指定します。references/json-indexing.md を参照

よくある間違いは、カテゴリやステータスのフィールドが「文字列だから」という理由で TEXT を使うことです。完全一致のフィルタリングでは、TAG の方が約 10 倍高速です。

references/index-creation.md、references/field-types.md、references/dialect.md、references/ft-create-options.md、references/json-indexing.md を参照してください。

3. よく使うクエリ

フィルターで絞り込み、必要なものだけを返してください。

# 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})"

覚えておきたい演算子：空白 = AND、| = OR、- = NOT、~ = オプション（スコアを加算）、=>{$weight: N} = ブースト。TAG 値のハイフンや特殊文字はエスケープしてください（@sku:{ABC\\-123}）。DSL の語彙については、references/query-syntax.md と references/search-syntax-primitives.md を参照してください。

トークン化の注意点（語幹処理、ストップワード、言語）については、references/text-tokenization.md を参照してください。結果の整形（SORTBY、RETURN、HIGHLIGHT、SUMMARIZE、NOCONTENT）については、references/result-shaping.md を参照してください。パフォーマンス調整（事前フィルター、SORTABLE フィールド、絞り込んだ RETURN、FT.PROFILE）については、references/query-optimization.md を参照してください。

4. ベクトルの基本

次の3つのベクトル設定は、埋め込みモデルと完全に一致させる必要があります。

• DIM — 出力の次元数（例：OpenAI text-embedding-3-small の場合は 1536）。一致しないと、気付かないまま無意味なデータが生成されます。
• DISTANCE_METRIC — 正規化されたテキスト埋め込み（一般的なケース）には COSINE、正規化されていない内積には IP、生のユークリッド距離には L2 を使用します。
• TYPE — 通常は FLOAT32 です。メモリが制約となる場合に限り、FLOAT16 または量子化バリアントを使用してください。

# 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

アルゴリズム	速度	精度	メモリ	用途
HNSW	高速（近似）	再現率 約95%以上（調整可能）	多い	本番環境：ベクトル数が1万件超、レイテンシが重視される場合
FLAT	低速（正確）	100%	少ない	小規模なコーパス（1万件未満）、完全一致が必要な場合

HNSW の調整項目：M（16～64、ノードあたりの接続数）、EF_CONSTRUCTION（100～500、構築品質）、EF_RUNTIME（クエリ時の候補リスト）。

references/vector-query.md、references/algorithm-choice.md を参照してください。

5. ハイブリッド検索

「ハイブリッド」と呼ばれるパターンは2種類あります。目的に応じて選択してください。

フィルター後にベクトル検索（Redis のすべてのバージョン）— 属性フィルターを適用して、ベクトル比較の前にエンジンが検索範囲を絞り込みます。

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

語彙検索とベクトル検索の融合（Redis ≥ 8.4）— BM25 のテキストスコアリングとベクトル類似度を組み合わせ、RRF または LINEAR で融合します。FT.HYBRID を使用してください（§1 を参照）。

フィルターを適用せずに大量の結果を取得し、クライアント側で絞り込むのは避けてください。処理が遅くなり、精度も低下します。references/hybrid-search.md を参照してください。

6. 集計と結果の整形

FT.AGGREGATE は、結果を宣言的に整形するコマンドです。ステージをつないでパイプラインを構築します。

# 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

一般的なステージ：LOAD、APPLY（計算フィールド）、FILTER（クエリ後のフィルター）、GROUPBY + REDUCE（SUM、COUNT、AVG、FIRST_VALUE、TOLIST）、SORTBY、LIMIT。

実行時間の長い結果セットには、WITHCURSOR + FT.CURSOR READ を使用して、サーバー側でページ分割します。references/aggregate-pipeline.md と references/aggregate-cursors.md を参照してください。

7. RAG パターン

標準的なパイプライン：クエリを埋め込み、Redis でベクトル検索を行い、上位K件のコンテキストを LLM に渡します。

実践的なヒント：

• メトリックを一致させる — 埋め込みモデルに合わせます（正規化されたテキストモデルでは、ほとんどの場合 COSINE を使用します）。
• 長いドキュメントをチャンクに分割する — 200～500トークンのチャンクは、通常、ページ全体をインデックス化するより効果的です。
• レコードごとに1回呼び出すのではなく、まとめて挿入する。
• ベクトル検索の前に属性で事前フィルターを適用する（テナント、更新日時、ドキュメントの種類）— §5 を参照してください。
• 精度が再現率より重要な場合は、ファネルの上流で再ランキングします。

references/rag-pattern.md を参照してください。

8. 運用

ダウンタイムなしでスキーマを変更するには、アプリケーションのクエリをエイリアスに向けたまま、背後のインデックスを切り替えます。

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}"

便利な管理コマンド：FT.INFO、FT.DROPINDEX、FT._LIST、FT.ALIASADD/UPDATE/DEL。references/index-management.md を参照してください。

クエリで結果が返らない場合や、処理が遅い場合は、FT.EXPLAIN（クエリの解析方法を表示）と FT.PROFILE（実行統計を表示）でデバッグします。references/debugging.md を参照してください。

9. クライアントの例

この SKILL.md 内のインライン例は CLI / RESP 形式です。これは、すべてのクライアントがシリアライズするワイヤープロトコルです。特定のクライアント向けの慣用的なコード例については、以下を参照してください。

• redis-py（Python、低レベルクライアント）：references/clients/python-redis-py.md
• Jedis（Java）：references/clients/java-jedis.md
• RedisVL（Python、redis-py の上位レベルの SDK）：references/clients/python-redisvl.md

その他のクライアント（Lettuce、node-redis、go-redis、NRedisStack、.NET）でも同じ CLI 形式に変換します。対応状況は今後の対応項目として管理されています。

参考資料

• Redis：検索とクエリ
• Redis：ベクトル
• Redis：クエリ構文
• Redis：クエリダイアレクト
• Redis：RAG クイックスタート
• FT.CREATE · FT.SEARCH · FT.AGGREGATE · FT.HYBRID
• RedisVL ドキュメント