redis-query-engine

Redis Query Engine

Redis Query Engine（RQE）を使用して、Hash または JSON ドキュメントのインデックスを作成し、検索するためのガイドです。FT.CREATE を使ったスキーマ設計、フィールドタイプの選択、クエリ構文、インデックスのライフサイクル管理、よくあるパフォーマンス上の落とし穴について説明します。

適用する場面

• RQE インデックス（FT.CREATE、FT.ALTER）を作成、変更、またはレビューするとき。
• FT.SEARCH／FT.AGGREGATE クエリを作成または最適化するとき。
• フィールドに TEXT、TAG、NUMERIC、GEO、GEOSHAPE、VECTOR のどれを使うか判断するとき。
• ダウンタイムなしで新しいインデックススキーマを導入するとき。
• 新しく書き込まれたキーのみを対象とするインデックスを立ち上げるとき。

1. DIALECT 2 を使用する（最新のデフォルト）

DIALECT 2 が基本です。ほかのダイアレクト（1、3、4）は Redis 8 で非推奨になりました。最新のクライアントライブラリの多くはすでにこれをデフォルトにしていますが、移植性を確保するため、直接コマンドを実行する場合は明示的に指定してください。

FT.SEARCH idx:products "@name:laptop" DIALECT 2

ベクトル検索クエリには DIALECT 2 が必須です。また、特殊文字や NULL も予測どおりに処理します。

references/dialect.md を参照してください。

2. 適切なフィールドタイプを選ぶ

フィールドタイプによって、実行できるクエリとその速度の両方が決まります。アクセスパターンを満たす範囲で、最も限定的なタイプを使用してください。

フィールドタイプ	用途	備考
TEXT	全文検索が必要な場合	トークン化とステミングを実行します。完全一致には使用しないでください
TAG	完全一致／フィルタリング	タグクエリを最速にするには SORTABLE UNF を追加します
NUMERIC	範囲検索、ソート	価格、件数、タイムスタンプ
GEO	緯度／経度による地点検索	単一地点（店舗、ユーザー）
GEOSHAPE	ポリゴン／エリア検索	配達区域、地域
VECTOR	類似検索	HNSW または FLAT。redis-vector-search を参照

よくある間違いは、「文字列だから」という理由でカテゴリやステータスのフィールドに TEXT を使うことです。こうしたフィールドでは TAG のほうが 10 倍高速です。

references/field-types.md を参照してください。

3. クエリ対象のフィールドのみをインデックス化し、必ずプレフィックスを設定する

PREFIX を指定せずに FT.CREATE を実行すると、データベース内の条件に一致するすべてのキーがインデックス化されます。スキーマの範囲が広いと、インデックスサイズと書き込みレイテンシが急増する可能性があります。

FT.CREATE idx:products ON HASH PREFIX 1 product:
    SCHEMA
        name TEXT WEIGHT 2.0
        category TAG SORTABLE
        price NUMERIC SORTABLE
        location GEO

目安：

• 最小限のスキーマから始めます。新しいクエリパターンが出てきたらフィールドを追加します。
• 必ず PREFIX を設定します（または FILTER 式で絞り込みます）。
• フィールドを追加した後は FT.INFO idx:<name> を使ってインデックスサイズを監視します。
• SORTABLE は実際にソートするフィールドにのみ使用してください。メモリコストがかかります。

references/index-creation.md を参照してください。

4. ダウンタイムなしでインデックスを更新するには、エイリアスを使用する

本番環境でスキーマを変更する場合は、アプリケーションのクエリをエイリアスに向けたままにし、エイリアスの参照先インデックスを切り替えます。

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 を参照してください。

5. SKIPINITIALSCAN — 過去のデータが不要な場合にのみ使用する

デフォルトでは、FT.CREATE はプレフィックスに一致する既存のキーをすべて走査してインデックス化します。SKIPINITIALSCAN を使用するのは、次の場合に限ってください。

• 新しい機能のためにインデックスを立ち上げ、既存のデータを検索対象にする必要がない場合。
• 既存のデータが多すぎて、同期的に走査できない場合。
• 将来のイベントのみが対象となるイベントストリームをインデックス化する場合。

ほとんどのスキーマ移行では、デフォルト（すべてを走査する設定）が適切です。

references/skip-initial-scan.md を参照してください。

6. * ではなく、具体的なクエリを記述する

ページングや集計の前にフィルターを使って、結果セットを絞り込みます。

# Good — specific filter, limited fields returned
FT.SEARCH idx:products "@category:{electronics} @price:[100 500]"
    LIMIT 0 20
    RETURN 3 name price category

# Bad — full scan plus unbounded LIMIT
FT.SEARCH idx:products "*" LIMIT 0 10000

ほかの調整項目：

• SORTBY を使うには、ソート対象のフィールドに SORTABLE が必要です。指定がない場合、ソートは遅くなります。
• 早い段階で LIMIT を指定してください。指定しないと、エンジンは上限を超える分もすべて処理します。
• RETURN で必要なフィールドのみを指定してください。必要な情報が一部だけなら、ドキュメント全体を取得しないでください。
• クエリが遅い場合は、FT.PROFILE idx:<name> SEARCH QUERY "<query>" でプロファイリングします。

references/query-optimization.md を参照してください。

References

• Redis: Query Engine — Indexing
• Redis: Query syntax
• Redis: Query dialects
• Redis: Administration (aliases, dropindex)
• FT.CREATE