Build your search queries

Once you know which search approaches you need to use, you can start building and testing your search queries. Elasticsearch provides several query interfaces to help you express your search logic.

These query interfaces are complementary, not mutually exclusive. You can use different interfaces for different parts of your application, based on your specific needs. This flexibility allows you to gradually adopt newer interfaces as your requirements evolve.

Use the following guidance to decide which interface best fits your use case.

Choose Query DSL when you need:

• Fine-grained control over individual query clauses, scoring, and boosting
• The widest ecosystem support — all Elasticsearch clients, tools, and integrations work with Query DSL
• A single-stage query like a match, bool, or term query without multi-stage retrieval

Query DSL is the foundational query language and remains the right choice for straightforward search queries, especially when you're using a single retrieval strategy.

Choose retrievers when you need to:

• Compose multi-stage retrieval pipelines in a single _search call (for example, retrieve → rerank → diversify)
• Combine multiple retrieval strategies using RRF or linear combination
• Apply semantic reranking with the text_similarity_reranker retriever
• Use the multi-field query format for simple hybrid search across lexical and semantic fields with automatic score normalization

Retrievers wrap Query DSL and add composability. If your search involves multiple retrieval stages — such as combining BM25 with vector search, or adding a reranking step — retrievers let you express the entire pipeline declaratively.

Choose ES|QL when you need to:

• Transform or aggregate results alongside your search (for example, filter → search → rerank → generate)
• Build end-to-end search workflows using piped syntax, including hybrid search with FORK/FUSE, reranking with RERANK, and text generation with COMPLETION
• Explore data interactively using a familiar SQL-like syntax in Kibana or the API
• Combine search with analytics such as aggregations, stats, or data transformations in a single query

ES|QL is a good fit when your workflow extends beyond retrieval — for example, when you want to search, rerank, and summarize results in a single piped query.

The following table summarizes which capabilities are available in each interface.