The Elasticsearch Query DSL is a JSON-based query language used to search and aggregate data in an Elasticsearch index. It supports full-text search, structured filters, geo queries, vector (kNN) search, and a rich aggregation framework, all expressed as nested JSON objects. The Query DSL is the primary interface for application search, log analytics, and dashboards built on Elasticsearch and OpenSearch.
The DSL is sometimes informally called "Query DSL" or "Search DSL". A different SQL-like language, "EQL" (Event Query Language), exists for security-style sequence detection - it is not the same thing. This page indexes the JSON Query DSL.
Query DSL Anatomy
Every search request goes to _search and carries a query clause:
GET /my-index/_search
{
"query": {
"bool": {
"must": [ { "match": { "title": "elasticsearch" } } ],
"filter": [ { "term": { "status": "published" } } ]
}
},
"size": 10,
"from": 0,
"sort": [ { "published_at": "desc" } ],
"aggs": {
"by_category": { "terms": { "field": "category" } }
}
}
Two distinctions to keep clear:
- Query context (inside
must,should) computes a relevance score (_score). - Filter context (inside
filter,must_not) is yes/no, does not score, and is cached.
If you do not need scoring, put the clause in filter. It is faster and the results are cacheable.
Available Elasticsearch Query Types
Term-level queries (exact matches, no analysis):
- Term Query
- Terms Query
- Range Query
- Exists Query
- Prefix Query
- Wildcard Query
- Regexp Query
- Fuzzy Query
- IDs Query
Full-text queries (analyzed against text fields):
Compound queries (combine other queries):
Joining queries (parent-child and nested):
Geo queries:
Scripting and vector search:
Available Elasticsearch Aggregation Types
Metric Aggregations:
- Average Aggregation
- Cardinality Aggregation
- Max Aggregation
- Min Aggregation
- Sum Aggregation
- Value Count Aggregation
- Stats Aggregation
- Extended Stats Aggregation
- Percentiles Aggregation
- Percentile Ranks Aggregation
- Median Absolute Deviation Aggregation
- Top Hits Aggregation
- Weighted Average Aggregation
Bucket Aggregations:
- Terms Aggregation
- Significant Terms Aggregation
- Range Aggregation
- Date Range Aggregation
- IP Range Aggregation
- Histogram Aggregation
- Date Histogram Aggregation
- Geo Distance Aggregation
- Geohash Grid Aggregation
- Adjacency Matrix Aggregation
- Auto Date Histogram Aggregation
- Composite Aggregation
Pipeline Aggregations:
- Average Bucket Aggregation
- Max Bucket Aggregation
- Min Bucket Aggregation
- Sum Bucket Aggregation
- Stats Bucket Aggregation
- Extended Stats Bucket Aggregation
- Percentiles Bucket Aggregation
- Moving Average Aggregation
- Moving Function Aggregation
- Derivative Aggregation
- Cumulative Sum Aggregation
- Bucket Script Aggregation
- Bucket Selector Aggregation
- Bucket Sort Aggregation
Matrix Aggregations:
Geo Aggregations:
Other Aggregations:
Operating Query DSL in Production
The Query DSL is expressive enough to write queries that look reasonable and quietly destroy a cluster. Wildcard queries with leading wildcards, regex queries against text fields, deep from/size pagination, and unbounded terms aggregations are the most common offenders. Pulse Query Analytics profiles real query traffic against your cluster, surfaces the slowest and most expensive queries, and recommends DSL changes (filter context, field rewrites, runtime field push-down) that cut latency without an application rewrite.
Frequently Asked Questions
Q: What is the difference between Elasticsearch Query DSL and EQL?
A: Query DSL is the JSON query language used by every search request - the query, aggs, sort blocks. EQL (Event Query Language) is a separate, SQL-like syntax for sequence and correlation detection in security telemetry. Most application search uses Query DSL.
Q: When should I use filter context vs query context?
A: Use filter context (filter, must_not) for yes/no conditions where relevance scoring does not matter. Filter clauses skip scoring and are cached. Use query context (must, should) when the clause should contribute to _score.
Q: What is the difference between match and term queries?
A: match analyzes the input the same way the field was analyzed at index time (lowercasing, tokenizing) and is the right choice for text fields. term matches the literal value with no analysis and is the right choice for keyword, numeric, date, and boolean fields.
Q: How do I write a query that combines multiple conditions?
A: Wrap them in a bool query with must, should, must_not, and filter clauses. must and filter are AND, should is OR (with optional minimum_should_match), must_not is NOT.
Q: Does Elasticsearch support SQL?
A: Yes, via the SQL API (POST /_sql?format=txt) which translates a subset of SQL into Query DSL. For ad-hoc analysis it is convenient; for production application queries, write Query DSL directly to get full control over filters, scoring, and aggregations.
Q: How is the Elasticsearch Query DSL different from KQL?
A: KQL (Kibana Query Language) is a simplified query syntax used in Kibana's search bar (status:200 AND host:web*). It compiles down to Query DSL at execution time. Use KQL for interactive filtering in Kibana, Query DSL for application code.
Related Reading
- Bool Query: the workhorse compound query for combining clauses.
- Match Query and Term Query: the two most-used leaf queries.
- Date Histogram Aggregation: the typical entry point into aggregations.
- Kibana Query Language (KQL): the simplified Kibana search syntax.
- Using Date Math in Elasticsearch: expressing time ranges in queries.
- Create Index with Mapping: the mapping decisions that constrain what queries you can run.
