honeymoose/OpenSearch
1
0
Fork 0
mirror of https://github.com/honeymoose/OpenSearch.git synced 2025-03-24 17:09:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

CONSOLify the completion suggester docs (#19758)

Browse Source 
* CONSOLEify search/suggesters/completion
* CONSOLEify context suggester docs
This commit is contained in:
Nik Everett 2016-08-03 18:40:17 -04:00 committed by GitHub
parent be87d50f32
commit 3be1e7ec35
2 changed files with 126 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
docs/reference/search/suggesters/completion-suggest.asciidoc
View File

@ -24,18 +24,24 @@ which indexes the field values for fast completions.
[source,js]
--------------------------------------------------
PUT music/song/_mapping
PUT music
{
"song" : {
"properties" : {
...
"suggest" : {
"type" : "completion"
"mappings": {
"song" : {
"properties" : {
"suggest" : {
"type" : "completion"
},
"title" : {
"type": "keyword"
}
}
}
}
}
--------------------------------------------------
// CONSOLE
// TESTSETUP
Mapping supports the following parameters:
@ -80,7 +86,7 @@ the suggestions will be scored. Indexing a suggestion is as follows:
[source,js]
--------------------------------------------------
PUT music/song/1?refresh=true
PUT music/song/1?refresh
{
"suggest" : {
"input": [ "Nevermind", "Nirvana" ],
@ -88,6 +94,8 @@ PUT music/song/1?refresh=true
}
}
--------------------------------------------------
// CONSOLE
// TEST
The following parameters are supported:
@ -104,7 +112,7 @@ You can index multiple suggestions for a document as follows:
[source,js]
--------------------------------------------------
PUT music/song/1?refresh=true
PUT music/song/1?refresh
{
"suggest" : [
{
@ -118,16 +126,21 @@ PUT music/song/1?refresh=true
]
}
--------------------------------------------------
// CONSOLE
// TEST[continued]
You can use the following shorthand form. Note that you can not specify
a weight with suggestion(s).
[source,js]
--------------------------------------------------
PUT music/song/1?refresh
{
"suggest" : [ "Nevermind", "Nirvana" ]
}
--------------------------------------------------
// CONSOLE
// TEST[continued]
[[querying]]
==== Querying
@ -135,20 +148,27 @@ a weight with suggestion(s).
Suggesting works as usual, except that you have to specify the suggest
type as `completion`. Suggestions are near real-time, which means
new suggestions can be made visible by <<indices-refresh,refresh>> and
documents once deleted are never shown.
documents once deleted are never shown. This request:
[source,js]
--------------------------------------------------
POST music/_suggest?pretty
{
"song-suggest" : {
"prefix" : "n",
"prefix" : "nir",
"completion" : {
"field" : "suggest"
}
}
}
--------------------------------------------------
// CONSOLE
// TEST[continued]
returns this response:
[source,js]
--------------------------------------------------
{
"_shards" : {
"total" : 5,
@ -156,16 +176,17 @@ POST music/_suggest?pretty
"failed" : 0
},
"song-suggest" : [ {
"text" : "n",
"text" : "nir",
"offset" : 0,
"length" : 1,
"length" : 3,
"options" : [ {
"text" : "Nirvana",
"score" : 34.0
"score" : 1.0
} ]
} ]
}
--------------------------------------------------
// TESTRESPONSE
The configured weight for a suggestion is returned as `score`.
The `text` field uses the `input` of your indexed suggestion.
@ -179,12 +200,13 @@ as follows:
[source,js]
--------------------------------------------------
POST music/song
POST music/song?refresh
{
"suggest" : "Nirvana",
"title" : "Nevermind"
}
--------------------------------------------------
// CONSOLE
You can get the "title" as part of the suggestion
payload by specifying it as a `payload`:
@ -196,12 +218,19 @@ POST music/_suggest?pretty
"song-suggest" : {
"prefix" : "n",
"completion" : {
"field" : "suggest"
"field" : "suggest",
"payload" : [ "title" ] <1>
}
}
}
--------------------------------------------------
// CONSOLE
// TEST[continued]
returns:
[source,js]
--------------------------------------------------
{
"_shards" : {
"total" : 5,
@ -214,7 +243,7 @@ POST music/_suggest?pretty
"length" : 1,
"options" : [ {
"text" : "Nirvana",
"score" : 34.0,
"score" : 1.0,
"payload" : {
"title" : [ "Nevermind" ]
}
@ -222,6 +251,7 @@ POST music/_suggest?pretty
} ]
}
--------------------------------------------------
// TESTRESPONSE
<1> The fields to be returned as part of each suggestion payload.
The basic completion suggester query supports the following parameters:
@ -250,7 +280,7 @@ you can have a typo in your search and still get results back.
POST music/_suggest?pretty
{
"song-suggest" : {
"prefix" : "n",
"prefix" : "nor",
"completion" : {
"field" : "suggest",
"fuzzy" : {
@ -260,6 +290,7 @@ POST music/_suggest?pretty
}
}
--------------------------------------------------
// CONSOLE
Suggestions that share the longest prefix to the query `prefix` will
be scored higher.
@ -308,11 +339,12 @@ POST music/_suggest?pretty
"song-suggest" : {
"regex" : "n[ever|i]r",
"completion" : {
"field" : "suggest",
"field" : "suggest"
}
}
}
--------------------------------------------------
// CONSOLE
The regex query can take specific regex parameters.
The following parameters are supported:

172
docs/reference/search/suggesters/context-suggest.asciidoc
View File

@ -13,38 +13,73 @@ Every context mapping has a unique name and a type. There are two types: `catego
and `geo`. Context mappings are configured under the `contexts` parameter in
the field mapping.
The following defines two context mappings for a completion field:
The following defines types, each with two context mappings for a completion
field:
[source,js]
--------------------------------------------------
PUT place/shops/_mapping
PUT place
{
"shops" : {
"properties" : {
...
"suggest" : {
"type" : "completion",
"contexts": [
{ <1>
"name": "place_type",
"type": "category",
"path": "cat"
},
{ <2>
"name": "location"
"type": "geo",
"path": "loc"
}
]
"mappings": {
"shops" : {
"properties" : {
"suggest" : {
"type" : "completion",
"contexts": [
{ <1>
"name": "place_type",
"type": "category",
"path": "cat"
},
{ <2>
"name": "location",
"type": "geo",
"precision": 4
}
]
}
}
}
}
}
PUT place_path_category
{
"mappings": {
"shops" : {
"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"
}
}
}
}
}
--------------------------------------------------
<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>>
// 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.
<1> Defines a `category` context named 'place_type' where the categories are
read from the `cat` field.
<2> 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>>.
@ -56,47 +91,14 @@ is entirely heap resident, you can monitor the completion field index size using
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:
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/shops/1
{
...
"suggest": {
"input": ["timmy's", "starbucks", "dunkin donuts"],
"contexts": {
@ -105,36 +107,21 @@ PUT place/shops/1
}
}
--------------------------------------------------
// CONSOLE
<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:
If the mapping had a `path` then the following index request would be enough to
add the categories:
[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
PUT place_path_category/shops/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
@ -164,6 +151,8 @@ POST place/_suggest?pretty
}
}
--------------------------------------------------
// CONSOLE
// TEST[continued]
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
@ -192,6 +181,8 @@ POST place/_suggest?pretty
}
}
--------------------------------------------------
// CONSOLE
// TEST[continued]
<1> The context query filter suggestions associated with
categories 'cafe' and 'restaurants' and boosts the
suggestions associated with 'restaurants' by a
@ -244,21 +235,6 @@ In addition to the `path` setting, `geo` context mapping accepts the following s
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
@ -273,7 +249,7 @@ PUT place/shops/1
{
"suggest": {
"input": "timmy's",
"contexts": [
"contexts": {
"location": [
{
"lat": 43.6624803,
@ -284,10 +260,11 @@ PUT place/shops/1
"lon": -79.3873227
}
]
]
}
}
}
--------------------------------------------------
// CONSOLE
[float]
===== Geo location Query
@ -315,6 +292,8 @@ POST place/_suggest
}
}
--------------------------------------------------
// 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.
@ -351,6 +330,7 @@ POST place/_suggest?pretty
}
}
--------------------------------------------------
// 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