OpenSearch/docs/reference/search/suggesters/context-suggest.asciidoc

[[suggester-context]]
=== Context Suggester

added[1.2.0]

The context suggester is an extension to the suggest API of Elasticsearch. Namely the
suggester system provides a very fast way of searching documents by handling these
entirely in memory. But this special treatment does not allow the handling of
traditional queries and filters, because those would have notable impact on the
performance. So the context extension is designed to take so-called context information
into account to specify a more accurate way of searching within the suggester system. 
Instead of using the traditional query and filter system a predefined ``context`` is
configured to limit suggestions to a particular subset of suggestions.
Such a context is defined by a set of context mappings which can either be a simple
*category* or a *geo location*. The information used by the context suggester is
configured in the type mapping with the `context` parameter, which lists all of the
contexts that need to be specified in each document and in each suggestion request.
For instance:

[source,js]
--------------------------------------------------
PUT services/service/_mapping
{
    "service": {
        "properties": {
            "name": {
                "type" : "string"
            },
            "tag": {
                "type" : "string"
            },
            "suggest_field": {
                "type": "completion",
                "context": {
                    "color": { <1>
                        "type": "category",
                        "path": "color_field",
                        "default": ["red", "green", "blue"]
                    },
                    "location": { <2>
                        "type": "geo",
                        "precision": "5m",
                        "neighbors": true,
                        "default": "u33"
                    }
                }
            }
        }
    }
}
--------------------------------------------------
<1> See <<suggester-context-category>>
<2> See <<suggester-context-geo>>

However contexts are specified (as type `category` or `geo`, which are discussed below), each
context value generates a new sub-set of documents which can be queried by the completion
suggester. All three types accept a `default` parameter which provides a default value to use
if the corresponding context value is absent.

The basic structure of this element is that each field forms a new context and the fieldname
is used to reference this context information later on during indexing or querying. All context
mappings have the `default` and the `type` option in common. The value of the `default` field
is used, when ever no specific is provided for the certain context. Note that a context is
defined by at least one value. The `type` option defines the kind of information hold by this
context. These type will be explained further in the following sections.

[[suggester-context-category]]
[float]
==== Category Context
The `category` context allows you to specify one or more categories in the document at index time.
The document will be assigned to each named category, which can then be queried later. The category
type also allows to specify a field to extract the categories from. The `path` parameter is used to
specify this field of the documents that should be used. If the referenced field contains multiple
values, all these values will be used as alternative categories.

[float]
===== Category Mapping

The mapping for a category is simply defined by its `default` values. These can either be
defined as list of *default* categories:

[source,js]
--------------------------------------------------
"context": {
    "color": {
        "type": "category",
        "default": ["red", "orange"]
    }
}
--------------------------------------------------

or as a single value

[source,js]
--------------------------------------------------
"context": {
    "color": {
        "type": "category",
        "default": "red"
    }
}
--------------------------------------------------

or as reference to another field within the documents indexed:

[source,js]
--------------------------------------------------
"context": {
    "color": {
        "type": "category",
        "default": "red"
        "path": "color_field"
    }
}
--------------------------------------------------

in this case the *default* categories will only be used, if the given field does not
exist within the document. In the example above the categories are received from a
field named `color_field`. If this field does not exist a category *red* is assumed for
the context *color*.

[float]
===== Indexing category contexts
Within a document the category is specified either as an `array` of values, a
single value or `null`. A list of values is interpreted as alternative categories. So
a document belongs to all the categories defined. If the category is `null` or remains
unset the categories will be retrieved from the documents field addressed by the `path`
parameter. If this value is not set or the field is missing, the default values of the
mapping will be assigned to the context.

[source,js]
--------------------------------------------------
PUT services/service/1
{
    "name": "knapsack",
    "suggest_field": {
        "input": ["knacksack", "backpack", "daypack"],
        "context": {
            "color": ["red", "yellow"]
        }
    }
}
--------------------------------------------------

[float]
===== Category Query
A query within a category works similar to the configuration. If the value is `null`
the mappings default categories will be used. Otherwise the suggestion takes place
for all documents that have at least one category in common with the query.

[source,js]
--------------------------------------------------
POST services/_suggest?pretty'
{
    "suggest" : {
        "text" : "m",
        "completion" : {
            "field" : "suggest_field",
            "size": 10,
            "context": {
                "color": "red"
            }
        }
    }
}
--------------------------------------------------

[[suggester-context-geo]]
[float]
==== Geo location Context
A `geo` context allows you to limit results to those that lie within a certain distance
of a specified geolocation. At index time, a lat/long geo point is converted into a
geohash of a certain precision, which provides the context.

[float]
===== Geo location Mapping
The mapping for a geo context accepts four settings, only of which `precision` is required:

[horizontal]
`precision`::  This defines the precision of the geohash and can be specified as `5m`, `10km`,
               or as a raw geohash precision: `1`..`12`. It's also possible to setup multiple
               precisions by defining a list of precisions: `["5m", "10km"]`
`neighbors`::  Geohashes are rectangles, so a geolocation, which in reality is only 1 metre
               away from the specified point, may fall into the neighbouring rectangle. Set
               `neighbours` to `true` to include the neighbouring geohashes in the context.
               (default is *on*)
`path`::       Optionally specify a field to use to look up the geopoint.
`default`::    The geopoint to use if no geopoint has been specified.

Since all locations of this mapping are translated into geohashes, each location matches
a geohash cell. So some results that lie within the specified range but not in the same
cell as the query location will not match. To avoid this the `neighbors` option allows a
matching of cells that join the bordering regions of the documents location. This option
is turned on by default.
If a document or a query doesn't define a location a value to use instead can defined by
the `default` option. The value of this option supports all the ways a `geo_point` can be
defined. The `path` refers to another field within the document to retrieve the
location. If this field contains multiple values, the document will be linked to all these
locations.

[source,js]
--------------------------------------------------
"context": {
    "location": {
        "type": "geo",
        "precision": ["1km", "5m"],
        "neighbors": true,
        "path": "pin",
        "default": {
            "lat": 0.0,
            "lon": 0.0
        }
    }
}
--------------------------------------------------

[float]
===== Geo location Config

Within a document a geo location retrieved from the mapping definition can be overridden
by another location. In this case the context mapped to a geo location supports all
variants of defining a `geo_point`.

[source,js]
--------------------------------------------------
PUT services/service/1
{
    "name": "some hotel 1",
    "suggest_field": {
        "input": ["my hotel", "this hotel"],
        "context": {
            "location": {
                    "lat": 0,
                    "lon": 0
            }
        }
    }
}
--------------------------------------------------

[float]
===== Geo location Query

Like in the configuration, querying with a geo location in context, the geo location
query supports all representations of a `geo_point` to define the location. In this
simple case all precision values defined in the mapping will be applied to the given
location.

[source,js]
--------------------------------------------------
POST services/_suggest
{
    "suggest" : {
        "text" : "m",
        "completion" : {
            "field" : "suggest_field",
            "size": 10,
            "context": {
                "location": {
                    "lat": 0,
                    "lon": 0
                }
            }
        }
    }
}
--------------------------------------------------

But it also possible to set a subset of the precisions set in the mapping, by using the
`precision` parameter. Like in the mapping, this parameter is allowed to be set to a
single precision value or a list of these.

[source,js]
--------------------------------------------------
POST services/_suggest
{
    "suggest" : {
        "text" : "m",
        "completion" : {
            "field" : "suggest_field",
            "size": 10,
            "context": {
                "location": {
                    "value": {
                        "lat": 0,
                        "lon": 0
                    },
                    "precision": "1km"
                }
            }
        }
    }
}
--------------------------------------------------

A special form of the query is defined by an extension of the object representation of
the `geo_point`. Using this representation allows to set the `precision` parameter within
the location itself:

[source,js]
--------------------------------------------------
POST services/_suggest
{
    "suggest" : {
        "text" : "m",
        "completion" : {
            "field" : "suggest_field",
            "size": 10,
            "context": {
                "location": {
                        "lat": 0,
                        "lon": 0,
                        "precision": "1km"
                }
            }
        }
    }
}
--------------------------------------------------