[[search-suggesters]]
== Suggesters

The suggest feature suggests similar looking terms based on a provided
text by using a suggester. Parts of the suggest feature are still under
development.

The suggest request part is either defined alongside the query part in a
`_search` request or via the REST `_suggest` endpoint.

[source,js]
--------------------------------------------------
curl -s -XPOST 'localhost:9200/_search' -d '{
  "query" : {
    ...
  },
  "suggest" : {
    ...
  }
}' 
--------------------------------------------------

Suggest requests executed against the `_suggest` endpoint should omit
the surrounding `suggest` element which is only used if the suggest
request is part of a search.

[source,js]
--------------------------------------------------
curl -XPOST 'localhost:9200/_suggest' -d '{
  "my-suggestion" : {
    "text" : "the amsterdma meetpu",
    "term" : {
      "field" : "body"
    }
  }
}'
--------------------------------------------------

Several suggestions can be specified per request. Each suggestion is
identified with an arbitrary name. In the example below two suggestions
are requested. Both `my-suggest-1` and `my-suggest-2` suggestions use
the `term` suggester, but have a different `text`.

[source,js]
--------------------------------------------------
"suggest" : {
  "my-suggest-1" : {
    "text" : "the amsterdma meetpu",
    "term" : {
      "field" : "body"
    }
  },
  "my-suggest-2" : {
    "text" : "the rottredam meetpu",
    "term" : {
      "field" : "title"
    }
  }
}
--------------------------------------------------

The below suggest response example includes the suggestion response for
`my-suggest-1` and `my-suggest-2`. Each suggestion part contains
entries. Each entry is effectively a token from the suggest text and
contains the suggestion entry text, the original start offset and length
in the suggest text and if found an arbitrary number of options.

[source,js]
--------------------------------------------------
{
  ...
  "suggest": {
    "my-suggest-1": [
      {
        "text" : "amsterdma",
        "offset": 4,
        "length": 9,
        "options": [
           ...
        ]
      },     
      ...       
    ],
    "my-suggest-2" : [
      ... 
    ]
  }
  ...
}
--------------------------------------------------

Each options array contains an option object that includes the
suggested text, its document frequency and score compared to the suggest
entry text. The meaning of the score depends on the used suggester. The
term suggester's score is based on the edit distance.

[source,js]
--------------------------------------------------
"options": [
  {
    "text": "amsterdam",
    "freq": 77,
    "score": 0.8888889
  },
  ...
]  
--------------------------------------------------

[float]
[[global-suggest]]
=== Global suggest text

To avoid repetition of the suggest text, it is possible to define a
global text. In the example below the suggest text is defined globally
and applies to the `my-suggest-1` and `my-suggest-2` suggestions.

[source,js]
--------------------------------------------------
"suggest" : {
  "text" : "the amsterdma meetpu",
  "my-suggest-1" : {
    "term" : {
      "field" : "title"
    }
  },
  "my-suggest-2" : {
    "term" : {
      "field" : "body"
    }
  }
}
--------------------------------------------------

The suggest text can in the above example also be specified as
suggestion specific option. The suggest text specified on suggestion
level override the suggest text on the global level.

[float]
=== Other suggest example

In the below example we request suggestions for the following suggest
text: `devloping distibutd saerch engies` on the `title` field with a
maximum of 3 suggestions per term inside the suggest text. Note that in
this example we set `size` to `0`. This isn't required, but a
nice optimization. The suggestions are gathered in the `query` phase and
in the case that we only care about suggestions (so no hits) we don't
need to execute the `fetch` phase.

[source,js]
--------------------------------------------------
curl -s -XPOST 'localhost:9200/_search' -d '{
  "size": 0,
  "suggest" : {
    "my-title-suggestions-1" : {
      "text" : "devloping distibutd saerch engies",
      "term" : {
        "size" : 3,
        "field" : "title"  
      }
    }
  }
}'
--------------------------------------------------

The above request could yield the response as stated in the code example
below. As you can see if we take the first suggested options of each
suggestion entry we get `developing distributed search engines` as
result.

[source,js]
--------------------------------------------------
{
  ...
  "suggest": {
    "my-title-suggestions-1": [
      {
        "text": "devloping",
        "offset": 0,
        "length": 9,
        "options": [
          {
            "text": "developing",
            "freq": 77,
            "score": 0.8888889
          },
          {
            "text": "deloping",
            "freq": 1,
            "score": 0.875
          },
          {
            "text": "deploying",
            "freq": 2,
            "score": 0.7777778
          }
        ]
      },
      {
        "text": "distibutd",
        "offset": 10,
        "length": 9,
        "options": [
          {
            "text": "distributed",
            "freq": 217,
            "score": 0.7777778
          },
          {
            "text": "disributed",
            "freq": 1,
            "score": 0.7777778
          },
          {
            "text": "distribute",
            "freq": 1,
            "score": 0.7777778
          }
        ]
      },
      {
        "text": "saerch",
        "offset": 20,
        "length": 6,
        "options": [
          {
            "text": "search",
            "freq": 1038,
            "score": 0.8333333
          },
          {
            "text": "smerch",
            "freq": 3,
            "score": 0.8333333
          },
          {
            "text": "serch",
            "freq": 2,
            "score": 0.8
          }
        ]
      },
      {
        "text": "engies",
        "offset": 27,
        "length": 6,
        "options": [
          {
            "text": "engines",
            "freq": 568,
            "score": 0.8333333
          },
          {
            "text": "engles",
            "freq": 3,
            "score": 0.8333333
          },
          {
            "text": "eggies",
            "freq": 1,
            "score": 0.8333333
          }
        ]
      }
    ]
  }
  ...
}
--------------------------------------------------

include::suggesters/term-suggest.asciidoc[]

include::suggesters/phrase-suggest.asciidoc[]

include::suggesters/completion-suggest.asciidoc[]

include::suggesters/context-suggest.asciidoc[]