elasticsearch/docs/reference/mapping/params/similarity.asciidoc

[[similarity]]
=== `similarity`

{es} allows you to configure a text scoring algorithm or _similarity_
per field. The `similarity` setting provides a simple way of choosing a
text similarity algorithm other than the default `BM25`, such as `boolean`.

Only text-based field types like <<text,`text`>> and <<keyword,`keyword`>>
support this configuration.

Custom similarities can be configured by tuning the parameters of the built-in
similarities. For more details about this expert options, see the
<<index-modules-similarity,similarity module>>.

The only similarities which can be used out of the box, without any further
configuration are:

`BM25`::
The {wikipedia}/Okapi_BM25[Okapi BM25 algorithm]. The
algorithm used by default in {es} and Lucene.

`boolean`::
A simple boolean similarity, which is used when full-text ranking is not needed
and the score should only be based on whether the query terms match or not.
Boolean similarity gives terms a score equal to their query boost.


The `similarity` can be set on the field level when a field is first created,
as follows:

[source,console]
--------------------------------------------------
PUT my-index-000001
{
  "mappings": {
    "properties": {
      "default_field": { <1>
        "type": "text"
      },
      "boolean_sim_field": {
        "type": "text",
        "similarity": "boolean" <2>
      }
    }
  }
}
--------------------------------------------------

<1> The `default_field` uses the `BM25` similarity.
<2> The `boolean_sim_field` uses the `boolean` similarity.