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

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

The completion suggester considers all documents in the index, but it is often
desirable to serve suggestions filtered and/or boosted by some criteria.
For example, you want to suggest song titles filtered by certain artists or
you want to boost song titles based on their genre.

To achieve suggestion filtering and/or boosting, you can add context mappings while
configuring a completion field. You can define multiple context mappings for a
completion field.
Every context mapping has a unique name and a type. There are two types: `category`
and `geo`. Context mappings are configured under the `contexts` parameter in
the field mapping.

The following defines two context mappings for a completion field:

[source,js]
--------------------------------------------------
PUT place/shops/_mapping
{
  "shops" : {
        "properties" : {
            ...
            "suggest" : {
                "type" : "completion",
                "contexts": [
                    { <1>
                        "name": "place_type",
                        "type": "category",
                        "path": "cat"
                    },
                    { <2>
                        "name": "location"
                        "type": "geo",
                        "path": "loc"
                    }
                ]
            }
        }
    }
}
--------------------------------------------------
<1> Defines a `category` context named 'place_type', which will index values from field 'cat'.
    See <<suggester-context-category>>
<2> Defines a `geo` context named 'location', which will index values from field 'loc'.
    See <<suggester-context-geo>>

NOTE: Adding context mappings increases the index size for completion field. The completion index
is entirely heap resident, you can monitor the completion field index size using <<indices-stats>>.

[[suggester-context-category]]
[float]
==== Category Context

The `category` context allows you to associate one or more categories with suggestions at index
time. At query time, suggestions can be filtered and boosted by their associated categories.

[float]
===== Category Mapping

A `category` context mapping, where categories are provided explicitly with suggestions
can be defined as follows:

[source,js]
--------------------------------------------------
"contexts": [
    {
        "name": "cat_context",
        "type": "category",
    }
]
--------------------------------------------------

Alternatively, A `category` context mapping that references another field within a document
can be defined as follows:

[source,js]
--------------------------------------------------
"contexts": [
    {
        "name": "cat_context",
        "type": "category",
        "path": "cat_field"
    }
]
--------------------------------------------------

[float]
===== Indexing category contexts

Category contexts can be specified explicitly when indexing suggestions. If a suggestion has
multiple categories, the suggestion will be indexed for each category:

[source,js]
--------------------------------------------------
PUT place/shops/1
{
    ...
    "suggest": {
        "input": ["timmy's", "starbucks", "dunkin donuts"],
        "contexts": {
            "place_type": ["cafe", "food"] <1>
        }
    }
}
--------------------------------------------------

<1> These suggestions will be associated with 'cafe' and 'food' category.

Category contexts can also be referenced from another indexed field in the document via
the `path` parameter in the field mapping:

[source,js]
--------------------------------------------------
"contexts": [
    {
        "name": "cat_context",
        "type": "category",
        "path": "cat"
    }
]
--------------------------------------------------

With the above mapping, the following will index the suggestions, treating the values of the
'cat' field as category contexts:

[source,js]
--------------------------------------------------
PUT place/shops/1
{
    ...
    "suggest": ["timmy's", "starbucks", "dunkin donuts"],
    "cat": ["cafe", "food"] <1>
}
--------------------------------------------------

<1> These suggestions will be associated with 'cafe' and 'food' category.

NOTE: If context mapping references another field and the categories
are explicitly indexed, the suggestions are indexed with both set
of categories.


[float]
===== Category Query

Suggestions can be filtered by one or more categories. The following
filters suggestions by multiple categories:

[source,js]
--------------------------------------------------
POST place/_suggest?pretty
{
    "suggest" : {
        "prefix" : "tim",
        "completion" : {
            "field" : "suggest",
            "size": 10,
            "contexts": {
                "place_type": [ "cafe", "restaurants" ]
            }
        }
    }
}
--------------------------------------------------

NOTE: When no categories are provided at query-time, all indexed documents are considered.
Querying with no categories on a category enabled completion field should be avoided, as it
will degrade search performance.

Suggestions with certain categories can be boosted higher than others.
The following filters suggestions by categories and additionally boosts
suggestions associated with some categories:

[source,js]
--------------------------------------------------
POST place/_suggest?pretty
{
    "suggest" : {
        "prefix" : "tim",
        "completion" : {
            "field" : "suggest",
            "size": 10,
            "contexts": {
                "place_type": [ <1>
                    { "context" : "cafe" },
                    { "context" : "restaurants", "boost": 2 }
                 ]
            }
        }
    }
}
--------------------------------------------------
<1> The context query filter suggestions associated with
    categories 'cafe' and 'restaurants' and boosts the
    suggestions associated with 'restaurants' by a
    factor of `2`

In addition to accepting category values, a context query can be composed of
multiple category context clauses. The following parameters are supported for a
`category` context clause:

[horizontal]
`context`::
    The value of the category to filter/boost on.
    This is mandatory.

`boost`::
    The factor by which the score of the suggestion
    should be boosted, the score is computed by
    multiplying the boost with the suggestion weight,
    defaults to `1`

`prefix`::
    Whether the category value should be treated as a
    prefix or not. For example, if set to `true`,
    you can filter category of 'type1', 'type2' and
    so on, by specifying a category prefix of 'type'.
    Defaults to `false`

[[suggester-context-geo]]
[float]
==== Geo location Context

A `geo` context allows you to associate one or more geo points or geohashes with suggestions
at index time. At query time, suggestions can be filtered and boosted if they are within
a certain distance of a specified geo location.

Internally, geo points are encoded as geohashes with the specified precision.
See <<geohash>> for more background details.

[float]
===== Geo Mapping

In addition to the `path` setting, `geo` context mapping accepts the following settings:

[horizontal]
`precision`::
    This defines the precision of the geohash to be indexed and can be specified
    as a distance value (`5m`, `10km` etc.), or as a raw geohash precision (`1`..`12`).
    Defaults to a raw geohash precision value of `6`.

NOTE: The index time `precision` setting sets the maximum geohash precision that
can be used at query time.

The following defines a `geo` context mapping with an index time precision of `4`
indexing values from a geo point field 'pin':

[source,js]
--------------------------------------------------
"contexts": [
    {
        "name": "location"
        "type": "geo",
        "precision": 4,
        "path": "pin",
    }
]
--------------------------------------------------

[float]
===== Indexing geo contexts

`geo` contexts can be explicitly set with suggestions or be indexed from a geo point field in the
document via the `path` parameter, similar to `category` contexts. Associating multiple geo location context
with a suggestion, will index the suggestion for every geo location. The following indexes a suggestion
with two geo location contexts:

[source,js]
--------------------------------------------------
PUT place/shops/1
{
    "suggest": {
        "input": "timmy's",
        "contexts": [
            "location": [
                {
                    "lat": 43.6624803,
                    "lon": -79.3863353
                },
                {
                    "lat": 43.6624718,
                    "lon": -79.3873227
                }
            ]
        ]
    }
}
--------------------------------------------------

[float]
===== Geo location Query

Suggestions can be filtered and boosted with respect to how close they are to one or
more geo points. The following filters suggestions that fall within the area represented by
the encoded geohash of a geo point:

[source,js]
--------------------------------------------------
POST place/_suggest
{
    "suggest" : {
        "prefix" : "tim",
        "completion" : {
            "field" : "suggest",
            "size": 10,
            "contexts": {
                "location": {
                    "lat": 43.662,
                    "lon": -79.380
                }
            }
        }
    }
}
--------------------------------------------------

NOTE: When a location with a lower precision at query time is specified, all suggestions
that fall within the area will be considered.

Suggestions that are within an area represented by a geohash can also be boosted higher
than others, as shown by the following:

[source,js]
--------------------------------------------------
POST place/_suggest?pretty
{
    "suggest" : {
        "prefix" : "tim",
        "completion" : {
            "field" : "suggest",
            "size": 10,
            "contexts": {
                "location": [ <1>
                    {
                        "lat": 43.6624803,
                        "lon": -79.3863353,
                        "precision": 2
                    },
                    {
                        "context": {
                            "lat": 43.6624803,
                            "lon": -79.3863353
                        },
                        "boost": 2
                    }
                 ]
            }
        }
    }
}
--------------------------------------------------
<1> The context query filters for suggestions that fall under
    the geo location represented by a geohash of '(43.662, -79.380)'
    with a precision of '2' and boosts suggestions
    that fall under the geohash representation of '(43.6624803, -79.3863353)'
    with a default precision of '6' by a factor of `2`

In addition to accepting context values, a context query can be composed of
multiple context clauses. The following parameters are supported for a
`category` context clause:

[horizontal]
`context`::
    A geo point object or a geo hash string to filter or
    boost the suggestion by. This is mandatory.

`boost`::
    The factor by which the score of the suggestion
    should be boosted, the score is computed by
    multiplying the boost with the suggestion weight,
    defaults to `1`

`precision`::
    The precision of the geohash to encode the query geo point.
    This can be specified as a distance value (`5m`, `10km` etc.),
    or as a raw geohash precision (`1`..`12`).
    Defaults to index time precision level.

`neighbours`::
    Accepts an array of precision values at which
    neighbouring geohashes should be taken into account.
    precision value can be a distance value (`5m`, `10km` etc.)
    or a raw geohash precision (`1`..`12`). Defaults to
    generating neighbours for index time precision level.