Query structure and contexts

A tree of clauses

A leaf query checks a condition such as term, range or match. A compound query combines queries or changes their scoring, as bool, dis_max and constant_score do. JSON describes a tree, not an instruction sequence. Filter array order does not guarantee execution order: the engine optimizes internally.

Two questions for a document

Query context can score how well a document matches. Filter context decides eligibility. Stock, tenant_id and price bounds are normally constraints. Moving match into filter does not change its analyzer, but removes its scoring contribution. This is a semantic decision, not just a mechanical optimization.

Constant scores and caching

match_all selects every document; match_none selects none. constant_score wraps a filter with a uniform contribution. Filter context can make results eligible for caching, but caching depends on usage, segments and internal policies. A filter is not guaranteed to be cached or faster on the second request.

{
  "query": {
    "constant_score": {
      "filter": {
        "term": {
          "brand": "Sony"
        }
      }
    }
  }
}

Catalog reasoning example

For “wireless” with price<100, name matching supports relevance comparison while price determines budget eligibility. A product costing 20 is not automatically more textually relevant than one costing 90. Put match in must and range in filter. A user-selected price sort is a separate ordering contract. Putting every clause in must can add unwanted scoring and make results harder to explain.

Retrieve all products

The root of a search body is a JSON object. query defines which documents match. match_all with an empty object imposes no restriction, so it is useful for exploring a dataset before adding conditions. size controls the number of returned hits, not how many documents match; sort makes this small demonstration reproducible. JSON requires double quotes and does not allow comments or a trailing comma.

hits.total.value reports the number of matching documents; relation: eq means this count is exact. hits.hits is the returned page. _id identifies a hit, _source contains requested original fields, and _score is the relevance metadata. took is measured in milliseconds and varies between runs. Our fragments omit took, shard information and index metadata; that omission is presentation, not another Elasticsearch response format.

{
  "query": {
    "match_all": {}
  },
  "size": 2,
  "_source": [
    "name",
    "price"
  ],
  "sort": [
    {
      "id": "asc"
    }
  ]
}

{
  "hits": {
    "total": {
      "value": 300,
      "relation": "eq"
    },
    "hits": [
      {
        "_id": "1",
        "_score": null,
        "_source": {
          "name": "Wireless",
          "price": 100
        }
      },
      {
        "_id": "2",
        "_score": null,
        "_source": {
          "name": "Reference device",
          "price": 100
        }
      }
    ]
  }
}

Filter without scoring

bool.filter requires every listed restriction without adding a relevance contribution. Exact brand, stock and price restrictions are good examples: an available product should not gain relevance just because it is available. With no scored clause, a filter-only bool normally returns score zero.

Context applies to the whole clause below it. A nested bool with two filters represents a grouped AND. Keep query structure readable rather than using extra levels without purpose. Filter clauses can be considered for caching by Elasticsearch, but correctness must never depend on a cache hit or a particular execution order.

{
  "query": {
    "bool": {
      "filter": [
        {
          "term": {
            "brand.keyword": "Sony"
          }
        },
        {
          "term": {
            "in_stock": false
          }
        },
        {
          "range": {
            "price": {
              "lt": 1200
            }
          }
        }
      ]
    }
  },
  "size": 2,
  "_source": [
    "name",
    "brand",
    "price",
    "in_stock"
  ],
  "sort": [
    {
      "id": "asc"
    }
  ]
}

{
  "hits": {
    "total": {
      "value": 40,
      "relation": "eq"
    },
    "hits": [
      {
        "_id": "3",
        "_score": null,
        "_source": {
          "name": "Sony Travel Speaker 3",
          "brand": "Sony",
          "price": 100,
          "in_stock": false
        }
      },
      {
        "_id": "15",
        "_score": null,
        "_source": {
          "name": "Sony USB Cable 15",
          "brand": "Sony",
          "price": 499,
          "in_stock": false
        }
      }
    ]
  }
}

Combine relevance and filters

A practical search often combines a scored match in must with stock and price restrictions in filter. All conditions remain mandatory, but only the text query contributes to relevance. The example searches gaming and restricts products to in-stock items below 800.

Putting the text clause under filter can return the same matching set while discarding text ranking. Putting business restrictions under must can introduce scoring contributions. Preserve the distinction even when a small sample makes the outputs appear similar.

{
  "query": {
    "bool": {
      "must": [
        {
          "match": {
            "name": "gaming"
          }
        }
      ],
      "filter": [
        {
          "term": {
            "in_stock": true
          }
        },
        {
          "range": {
            "price": {
              "lt": 800
            }
          }
        }
      ]
    }
  },
  "size": 2,
  "_source": [
    "name",
    "price",
    "in_stock"
  ]
}

{
  "hits": {
    "total": {
      "value": 20,
      "relation": "eq"
    },
    "hits": [
      {
        "_id": "4",
        "_score": 2.3304372,
        "_source": {
          "name": "Logitech Gaming Keyboard 4",
          "price": 199,
          "in_stock": true
        }
      },
      {
        "_id": "14",
        "_score": 2.3304372,
        "_source": {
          "name": "Samsung Gaming Keyboard 14",
          "price": 199,
          "in_stock": true
        }
      }
    ]
  }
}