NestJS Elasticsearch
NestJS GraphQL + MongoDB アプリケーションに Elasticsearch ベースの検索を追加するための統合ガイドです。 アーキテクチャの境界（汎用インフラ、共有検索レイヤー、フィーチャーごとに所有するインデックス）を固定し、 検索プロジェクション、インデックス作成と同期、MongoDB ハイドレーションを伴う ID のみのクエリ、 カーソルページネーション、エンティティ間の派生フィールド、設定可能なバックエンドシームによる検索のオプション化、 ライブクラスターなしでのテスト、およびこれらに関する運用と DX を網羅します。
基本契約は Elasticsearch が検索し、MongoDB が提供する です。Elasticsearch は 識別子を返す純粋な検索インデックスであり、要求されたエンティティは常に真実の情報源である MongoDB から ハイドレーションされます。
適用タイミング
以下の場合にこれらのガイドラインを参照してください:
- 既存の NestJS GraphQL + MongoDB アプリケーションに検索を追加する場合
@nestjs/elasticsearchクライアントと共有検索レイヤーを配線する場合- インデックスマッピングまたは検索プロジェクションを定義または変更する場合
- MongoDB から Elasticsearch への同期、再インデックス、またはインデックスマイグレーションを実装する場合
- 検索クエリ、カーソルページネーション、または結果のハイドレーションを作成する場合
- エンティティ間で派生値（カウント、レーティング）を検索可能にする場合
- クラスターなしで検索をオプション化したり、設定からバックエンドを交換したりする場合
- モックされたバックエンドシーム、または実際の使い捨てクラスターに対して検索をテストする場合
- 古い検索結果やインデックスストームをデバッグする場合
優先順位別ルールカテゴリ
| 優先順位 | カテゴリ | 影響度 | プレフィックス |
|---|---|---|---|
| 1 | アーキテクチャ | CRITICAL | arch- |
| 2 | インデックス作成と同期 | CRITICAL | sync- |
| 3 | スキーマとマッピング | HIGH | map- |
| 4 | クエリ | HIGH | query- |
| 5 | エンティティ間 | MEDIUM-HIGH | rel- |
| 6 | 運用と DX | MEDIUM | ops- |
| 7 | 設定と環境 | HIGH | cfg- |
| 8 | テスト | MEDIUM-HIGH | test- |
クイックリファレンス
1. アーキテクチャ (CRITICAL)
arch-base-search-repository- 共有インデックスとクエリロジックをベースリポジトリに配置するarch-entity-vs-search-document- Elasticsearch フィールドをエンティティから分離するarch-feature-owned-index- 各フィーチャーが自身のインデックスを所有および登録するarch-infra-module- Elasticsearch クライアントを汎用インフラモジュールに分離する
2. インデックス作成と同期 (CRITICAL)
sync-bulk-index- Bulk API を使用してバッチでインデックス作成するsync-debounce-same-id- 同一 ID のバーストをデバウンスするsync-delete-immediately- インデックスから即座に削除するsync-enqueue-index- インデックス作成をキューに入れる。Elasticsearch にインラインで書き込まないsync-full-reindex-alias-swap- バージョン管理されたインデックスを通じて再インデックスし、エイリアスを交換するsync-idempotent-index-creation- 決定論的な名前で冪等にインデックスを作成する
3. スキーマとマッピング (HIGH)
map-analyzers- テキストアナライザーを意図的に選択するmap-derived-fields- バッチマッパーで派生フィールドとリレーションフィールドを計算するmap-exclude-non-search-fields- 検索目的のあるフィールドのみインデックスするmap-mapping-object- マッピングを型付きオブジェクトとして宣言するmap-typed-search-document- 検索ドキュメントをエンティティに対して型付けする
4. クエリ (HIGH)
query-cursor-pagination- search_after でページネーションするquery-hydrate-restore-order- MongoDB からハイドレーションし、関連性順序を復元するquery-ids-only-search- 検索は ID のみを返すquery-sort-tiebreaker- 常にユニークなソートタイブレーカーを含める
5. エンティティ間 (MEDIUM-HIGH)
rel-derived-counter-cache- 所有ドキュメントに派生カウンターをキャッシュするrel-owning-module-subscribes- 所有モジュールがサブスクライブし、他のモジュールは自身のイベントを発行する
6. 運用と DX (MEDIUM)
ops-cli-scripts- マイグレーションと再インデックスの CLI コマンドを提供するops-explain-debug- Explain フックを提供するops-health-check- ヘルスチェックに Elasticsearch を含めるops-log-es-requests- Elasticsearch のリクエストとレスポンスをログに記録するops-no-cron-for-indexing- インプロセスタイマーでインデックス作成をスケジュールしない
7. 設定と環境 (HIGH)
cfg-mongo-fallback-backend- 決定論的な MongoDB ファインダーにフォールバックするcfg-search-backend-seam- 検索をバックエンドシームの背後に配置する
8. テスト (MEDIUM-HIGH)
test-mock-elasticsearch-seam- ユニットテストで検索バックエンドシームをモックするtest-real-es-for-query-semantics- 実際の Elasticsearch に対してクエリセマンティクスをテストする
使用方法
個別のルールファイルで詳細な説明とコード例を参照してください:
rules/arch-entity-vs-search-document.md
rules/sync-full-reindex-alias-swap.md
rules/query-ids-only-search.md
各ルールファイルには以下が含まれています:
- なぜ重要か、どのレイヤーに適用されるかの簡単な説明
- 説明付きの誤ったコード例
- 説明付きの正しいコード例
- 追加のコンテキストと参照
他のスキルとの関連
nestjs-graphql-structure— ファイル配置。このスキルはフィーチャーにsearch/フォルダーとcommon/search/+infra/elasticsearch/レイヤーを追加します。そのスキルのフィーチャーモジュール、 リポジトリ、イベントルールに従います。nestjs-best-practices— このスキルの例が基づくサービス、イベント、キュー、設定、ヘルスチェックの 動作ルール。- 1つの意図的な例外 —
nestjs-graphql-structureのservice-background-jobsルールは プロセッサーを所有フィーチャーに保持します。検索パイプラインはcommon/search/で1回実行され、 インデックスレジストリを通じて各フィーチャーのリポジトリを解決します。これはパイプラインが すべてのフィーチャーで同一であるためです。arch-base-search-repositoryを参照してください。
完全なコンパイル済みドキュメント
すべてのルールを展開した完全なガイドについては、AGENTS.md を参照してください。