CONTEXT.md

Project Context: Elasticsearch Query & Mapping Expert

Core Stack

• Engine: Elasticsearch 8.x
• Client: elasticsearch-py
• DSL: Elasticsearch Query DSL (JSON)
• Features: ELSER (Semantic Search), Dense Vector (kNN), Explicit Mappings

Architectural Rules (Strict)

1. Explicit Mapping over Dynamic Mapping

• RULE: Never rely on dynamic mapping for production indices.
• RATIONALE: Prevents "mapping explosions" where unexpected fields (e.g., from deep taxonomies or user-generated keys) bloat the cluster state and degrade performance.
• ACTION: Always define strict properties and set dynamic: strict or dynamic: false at the root level.

2. Search Strategy (Hybrid)

• Traditional: Use multi_match with best_fields or cross_fields for keywords.
• Semantic (ELSER): Use text_expansion queries with the .elser_model_2 (or current version) for conceptual matching.
• Vector: Use knn search for high-dimensional similarity.
• Hybrid Scoring: Combine scores using reciprocal_rank_fusion (RRF) or linear boosting.

3. Field Types

• Use keyword for exact matches, sorting, and aggregations.
• Use text with specialized analyzers for full-text search.
• Use dense_vector for embeddings.
• Use flattened for nested objects with unpredictable keys that don't need independent indexing.

Query DSL Guidelines

• Prefer bool queries for combining filters and boosts.
• Use filter context for non-scoring criteria to leverage caching.
• Implement hierarchical faceting using nested aggregations or path_hierarchy tokenizers.