Similarity

The similarity mapping parameter lets you customize how relevance scores are calculated for a text field during search. It defines the scoring algorithm used to rank matching documents, which directly impacts how results are ordered in search responses.

Supported similarity types

• BM25 (default): Uses a modern, probabilistic ranking model that balances term frequency, document length, and inverse document frequency.
• boolean: Returns constant scores (1 or 0), so should be used if you care only about matching, not relevance.

Setting a custom similarity on a field

The following request creates an index named products with a title field that uses the boolean similarity, which assigns all matches the same score:

PUT /products
{
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "similarity": "boolean"
      }
    }
  }
}

Indexing a document

Use the following command to index a sample document:

PUT /products/_doc/1
{
  "title": "Compact Wireless Mouse"
}

Querying and inspecting scoring impact

Use the following command to search by the title field:

POST /products/_search
{
  "query": {
    "match": {
      "title": "wireless mouse"
    }
  }
}

You can examine the score returned in the _score field of the response:

{
  ...
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 2,
    "hits": [
      {
        "_index": "products",
        "_id": "1",
        "_score": 2,
        "_source": {
          "title": "Compact Wireless Mouse"
        }
      }
    ]
  }
}