- Elasticsearch Guide: other versions:
- Getting Started
- Setup
- Breaking changes
- Breaking changes in 2.3
- Breaking changes in 2.2
- Breaking changes in 2.1
- Breaking changes in 2.0
- Removed features
- Network changes
- Multiple
path.data
striping - Mapping changes
- CRUD and routing changes
- Query DSL changes
- Search changes
- Aggregation changes
- Parent/Child changes
- Scripting changes
- Index API changes
- Snapshot and Restore changes
- Plugin and packaging changes
- Setting changes
- Stats, info, and
cat
changes - Java API changes
- API Conventions
- Document APIs
- Search APIs
- Aggregations
- Metrics Aggregations
- Avg Aggregation
- Cardinality Aggregation
- Extended Stats Aggregation
- Geo Bounds Aggregation
- Geo Centroid Aggregation
- Max Aggregation
- Min Aggregation
- Percentiles Aggregation
- Percentile Ranks Aggregation
- Scripted Metric Aggregation
- Stats Aggregation
- Sum Aggregation
- Top hits Aggregation
- Value Count Aggregation
- Bucket Aggregations
- Children Aggregation
- Date Histogram Aggregation
- Date Range Aggregation
- Filter Aggregation
- Filters Aggregation
- Geo Distance Aggregation
- GeoHash grid Aggregation
- Global Aggregation
- Histogram Aggregation
- IPv4 Range Aggregation
- Missing Aggregation
- Nested Aggregation
- Range Aggregation
- Reverse nested Aggregation
- Sampler Aggregation
- Significant Terms Aggregation
- Terms Aggregation
- Pipeline Aggregations
- Avg Bucket Aggregation
- Derivative Aggregation
- Max Bucket Aggregation
- Min Bucket Aggregation
- Sum Bucket Aggregation
- Stats Bucket Aggregation
- Extended Stats Bucket Aggregation
- Percentiles Bucket Aggregation
- Moving Average Aggregation
- Cumulative Sum Aggregation
- Bucket Script Aggregation
- Bucket Selector Aggregation
- Serial Differencing Aggregation
- Caching heavy aggregations
- Returning only aggregation results
- Aggregation Metadata
- Metrics Aggregations
- Indices APIs
- Create Index
- Delete Index
- Get Index
- Indices Exists
- Open / Close Index API
- Put Mapping
- Get Mapping
- Get Field Mapping
- Types Exists
- Index Aliases
- Update Indices Settings
- Get Settings
- Analyze
- Index Templates
- Warmers
- Shadow replica indices
- Indices Stats
- Indices Segments
- Indices Recovery
- Indices Shard Stores
- Clear Cache
- Flush
- Refresh
- Force Merge
- Optimize
- Upgrade
- cat APIs
- Cluster APIs
- Query DSL
- Mapping
- Field datatypes
- Meta-Fields
- Mapping parameters
analyzer
boost
coerce
copy_to
doc_values
dynamic
enabled
fielddata
format
geohash
geohash_precision
geohash_prefix
ignore_above
ignore_malformed
include_in_all
index
index_options
lat_lon
fields
norms
null_value
position_increment_gap
precision_step
properties
search_analyzer
similarity
store
term_vector
- Dynamic Mapping
- Transform
- Analysis
- Analyzers
- Tokenizers
- Token Filters
- Standard Token Filter
- ASCII Folding Token Filter
- Length Token Filter
- Lowercase Token Filter
- Uppercase Token Filter
- NGram Token Filter
- Edge NGram Token Filter
- Porter Stem Token Filter
- Shingle Token Filter
- Stop Token Filter
- Word Delimiter Token Filter
- Stemmer Token Filter
- Stemmer Override Token Filter
- Keyword Marker Token Filter
- Keyword Repeat Token Filter
- KStem Token Filter
- Snowball Token Filter
- Phonetic Token Filter
- Synonym Token Filter
- Compound Word Token Filter
- Reverse Token Filter
- Elision Token Filter
- Truncate Token Filter
- Unique Token Filter
- Pattern Capture Token Filter
- Pattern Replace Token Filter
- Trim Token Filter
- Limit Token Count Token Filter
- Hunspell Token Filter
- Common Grams Token Filter
- Normalization Token Filter
- CJK Width Token Filter
- CJK Bigram Token Filter
- Delimited Payload Token Filter
- Keep Words Token Filter
- Keep Types Token Filter
- Classic Token Filter
- Apostrophe Token Filter
- Decimal Digit Token Filter
- Character Filters
- Modules
- Index Modules
- Testing
- Glossary of terms
- Release Notes
- 2.3.5 Release Notes
- 2.3.4 Release Notes
- 2.3.3 Release Notes
- 2.3.2 Release Notes
- 2.3.1 Release Notes
- 2.3.0 Release Notes
- 2.2.2 Release Notes
- 2.2.1 Release Notes
- 2.2.0 Release Notes
- 2.1.2 Release Notes
- 2.1.1 Release Notes
- 2.1.0 Release Notes
- 2.0.2 Release Notes
- 2.0.1 Release Notes
- 2.0.0 Release Notes
- 2.0.0-rc1 Release Notes
- 2.0.0-beta2 Release Notes
- 2.0.0-beta1 Release Notes
WARNING: Version 2.3 of Elasticsearch has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
Context Suggester
editContext Suggester
editThe 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:
PUT services/_mapping/service { "service": { "properties": { "name": { "type" : "string" }, "tag": { "type" : "string" }, "suggest_field": { "type": "completion", "context": { "color": { "type": "category", "path": "color_field", "default": ["red", "green", "blue"] }, "location": { "type": "geo", "precision": "5m", "neighbors": true, "default": "u33" } } } } } }
See Category Context |
|
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. Both 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.
Category Context
editThe 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.
Category Mapping
editThe mapping for a category is simply defined by its default
values. These can either be
defined as list of default categories:
"context": { "color": { "type": "category", "default": ["red", "orange"] } }
or as a single value
"context": { "color": { "type": "category", "default": "red" } }
or as reference to another field within the documents indexed:
"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.
Indexing category contexts
editWithin 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.
PUT services/service/1 { "name": "knapsack", "suggest_field": { "input": ["knacksack", "backpack", "daypack"], "context": { "color": ["red", "yellow"] } } }
Category Query
editA 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.
POST services/_suggest?pretty' { "suggest" : { "text" : "m", "completion" : { "field" : "suggest_field", "size": 10, "context": { "color": "red" } } } }
Geo location Context
editA 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.
Geo location Mapping
editThe mapping for a geo context accepts four settings, only of which precision
is required:
|
This defines the precision of the geohash and can be specified as |
|
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
|
|
Optionally specify a field to use to look up the geopoint. |
|
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.
"context": { "location": { "type": "geo", "precision": ["1km", "5m"], "neighbors": true, "path": "pin", "default": { "lat": 0.0, "lon": 0.0 } } }
Geo location Config
editWithin 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
.
PUT services/service/1 { "name": "some hotel 1", "suggest_field": { "input": ["my hotel", "this hotel"], "context": { "location": { "lat": 0, "lon": 0 "contexts": [ "location": [ { "lat": 43.6624803, "lon": -79.3863353 }, { "lat": 43.6624718, "lon": -79.3873227 } } } }
Geo location Query
editLike 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.
POST services/_suggest { "suggest" : { "text" : "m", "completion" : { "field" : "suggest_field", "size": 10, "contexts": { "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.
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:
POST services/_suggest { "suggest" : { "text" : "m", "completion" : { "field" : "suggest_field", "size": 10, "context": { "location": { "lat": 0, "lon": 0, "precision": "1km" } } } } }
On this page