mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-07 05:28:34 +00:00
4561c5ee83
This change clarifies the documentation of the context completion suggester regarding filtering and boosting with contexts. Unlike the suggester v1, filtering on multiple contexts works as a disjunction, a suggestion matches if it contains at least one of the provided context values and boosting selects the maximum score among the matching contexts. This commit also adapts an old test that was written for the v1 suggester and commented out for version 2 because the behavior changed.
388 lines
12 KiB
Plaintext
388 lines
12 KiB
Plaintext
[[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.
|
|
|
|
NOTE: It is mandatory to provide a context when indexing and querying
|
|
a context enabled completion field.
|
|
|
|
The following defines types, each with two context mappings for a completion
|
|
field:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT place
|
|
{
|
|
"mappings": {
|
|
"_doc" : {
|
|
"properties" : {
|
|
"suggest" : {
|
|
"type" : "completion",
|
|
"contexts": [
|
|
{ <1>
|
|
"name": "place_type",
|
|
"type": "category"
|
|
},
|
|
{ <2>
|
|
"name": "location",
|
|
"type": "geo",
|
|
"precision": 4
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
PUT place_path_category
|
|
{
|
|
"mappings": {
|
|
"_doc" : {
|
|
"properties" : {
|
|
"suggest" : {
|
|
"type" : "completion",
|
|
"contexts": [
|
|
{ <3>
|
|
"name": "place_type",
|
|
"type": "category",
|
|
"path": "cat"
|
|
},
|
|
{ <4>
|
|
"name": "location",
|
|
"type": "geo",
|
|
"precision": 4,
|
|
"path": "loc"
|
|
}
|
|
]
|
|
},
|
|
"loc": {
|
|
"type": "geo_point"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TESTSETUP
|
|
<1> Defines a `category` context named 'place_type' where the categories must be
|
|
sent with the suggestions.
|
|
<2> Defines a `geo` context named 'location' where the categories must be sent
|
|
with the suggestions.
|
|
<3> Defines a `category` context named 'place_type' where the categories are
|
|
read from the `cat` field.
|
|
<4> Defines a `geo` context named 'location' where the categories are read from
|
|
the `loc` field.
|
|
|
|
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.
|
|
|
|
The mappings are set up like the `place_type` fields above. If `path` is defined
|
|
then the categories are read from that path in the document, otherwise they must
|
|
be sent in the suggest field like this:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT place/_doc/1
|
|
{
|
|
"suggest": {
|
|
"input": ["timmy's", "starbucks", "dunkin donuts"],
|
|
"contexts": {
|
|
"place_type": ["cafe", "food"] <1>
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
<1> These suggestions will be associated with 'cafe' and 'food' category.
|
|
|
|
If the mapping had a `path` then the following index request would be enough to
|
|
add the categories:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT place_path_category/_doc/1
|
|
{
|
|
"suggest": ["timmy's", "starbucks", "dunkin donuts"],
|
|
"cat": ["cafe", "food"] <1>
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
<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/_search?pretty
|
|
{
|
|
"suggest": {
|
|
"place_suggestion" : {
|
|
"prefix" : "tim",
|
|
"completion" : {
|
|
"field" : "suggest",
|
|
"size": 10,
|
|
"contexts": {
|
|
"place_type": [ "cafe", "restaurants" ]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
NOTE: If multiple categories or category contexts are set on the query
|
|
they are merged as a disjunction. This means that suggestions match
|
|
if they contain at least one of the provided context values.
|
|
|
|
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/_search?pretty
|
|
{
|
|
"suggest": {
|
|
"place_suggestion" : {
|
|
"prefix" : "tim",
|
|
"completion" : {
|
|
"field" : "suggest",
|
|
"size": 10,
|
|
"contexts": {
|
|
"place_type": [ <1>
|
|
{ "context" : "cafe" },
|
|
{ "context" : "restaurants", "boost": 2 }
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
<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`
|
|
|
|
NOTE: If a suggestion entry matches multiple contexts the final score is computed as the
|
|
maximum score produced by any matching contexts.
|
|
|
|
[[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.
|
|
|
|
[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.
|
|
|
|
[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/_doc/1
|
|
{
|
|
"suggest": {
|
|
"input": "timmy's",
|
|
"contexts": {
|
|
"location": [
|
|
{
|
|
"lat": 43.6624803,
|
|
"lon": -79.3863353
|
|
},
|
|
{
|
|
"lat": 43.6624718,
|
|
"lon": -79.3873227
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
[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/_search
|
|
{
|
|
"suggest": {
|
|
"place_suggestion" : {
|
|
"prefix" : "tim",
|
|
"completion" : {
|
|
"field" : "suggest",
|
|
"size": 10,
|
|
"contexts": {
|
|
"location": {
|
|
"lat": 43.662,
|
|
"lon": -79.380
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
NOTE: When a location with a lower precision at query time is specified, all suggestions
|
|
that fall within the area will be considered.
|
|
|
|
NOTE: If multiple categories or category contexts are set on the query
|
|
they are merged as a disjunction. This means that suggestions match
|
|
if they contain at least one of the provided context values.
|
|
|
|
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/_search?pretty
|
|
{
|
|
"suggest": {
|
|
"place_suggestion" : {
|
|
"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
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
<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`
|
|
|
|
NOTE: If a suggestion entry matches multiple contexts the final score is computed as the
|
|
maximum score produced by any matching contexts.
|
|
|
|
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.
|