Query DSL Reference

Full-Text Queries

Full-text queries analyze the input text before searching. Use on text fields.

// match: standard full-text search
GET /articles/_search
{
  "query": {
    "match": {
      "title": {
        "query": "elasticsearch performance",
        "operator": "and",
        "fuzziness": "AUTO"
      }
    }
  }
}

// match_phrase: words in order
{ "match_phrase": { "body": "distributed search engine" } }

// multi_match: search across multiple fields
{
  "multi_match": {
    "query": "elasticsearch",
    "fields": ["title^3", "body", "tags"],
    "type": "best_fields"
  }
}

// match_all: return all documents
{ "match_all": {} }

Term-Level Queries

Term queries do not analyze input. Use on keyword, numeric, date, boolean fields.

// term: exact match
{ "term": { "status": { "value": "published" } } }

// terms: match any in list
{ "terms": { "status": ["published", "featured"] } }

// range: numeric or date range
{
  "range": {
    "price": { "gte": 10, "lte": 100 }
  }
}
{
  "range": {
    "created_at": {
      "gte": "2024-01-01",
      "lt":  "2025-01-01",
      "format": "yyyy-MM-dd"
    }
  }
}

// exists: field has a value
{ "exists": { "field": "published_at" } }

// prefix: field starts with
{ "prefix": { "username": "ali" } }

// wildcard: glob pattern (slow on large indexes)
{ "wildcard": { "email": "*@example.com" } }

// ids: match by document IDs
{ "ids": { "values": ["1", "2", "3"] } }

Bool Query

Combine queries with must (AND), should (OR), must_not (NOT), and filter (AND, no scoring).

{
  "query": {
    "bool": {
      "must": [
        { "match": { "title": "elasticsearch" } }
      ],
      "filter": [
        { "term": { "status": "published" } },
        { "range": { "price": { "lte": 50 } } }
      ],
      "should": [
        { "term": { "tags": "featured" } }
      ],
      "must_not": [
        { "term": { "deleted": true } }
      ],
      "minimum_should_match": 1
    }
  }
}

// filter context: no relevance scoring, results cached
// must/should context: affects _score

Nested & Join Queries

// nested: query objects in nested arrays
// Mapping must declare field as nested type
{
  "query": {
    "nested": {
      "path": "comments",
      "query": {
        "bool": {
          "must": [
            { "match": { "comments.author": "alice" } },
            { "range":  { "comments.rating": { "gte": 4 } } }
          ]
        }
      },
      "score_mode": "avg"
    }
  }
}

// has_child / has_parent (join field type required)
{
  "query": {
    "has_child": {
      "type": "comment",
      "query": { "match": { "text": "great" } },
      "score_mode": "max"
    }
  }
}

Pagination & Sorting

// from/size pagination (avoid deep pagination)
GET /products/_search
{
  "from": 0, "size": 20,
  "query": { "match_all": {} },
  "sort": [
    { "price": "asc" },
    { "_score": "desc" }
  ]
}

// search_after: efficient deep pagination
{
  "size": 20,
  "query": { "match_all": {} },
  "sort": [{ "price": "asc" }, { "_id": "asc" }],
  "search_after": [49.99, "doc_id_xyz"]
}

// Point in time (PIT) for stable pagination (ES 7.10+)
POST /products/_pit?keep_alive=1m
// returns { "id": "pit_id..." }
{ "size": 20, "pit": { "id": "pit_id...", "keep_alive": "1m" } }