Query DSL

match queries accept text/numerics/dates, analyzes them, and constructs a query. For example:

Note, message is the name of a field, you can substitute the name of any field instead.

The match_phrase query analyzes the text and creates a phrase query out of the analyzed text. For example:

A phrase query matches terms up to a configurable slop (which defaults to 0) in any order. Transposed terms have a slop of 2.

The analyzer can be set to control which analyzer will perform the analysis process on the text. It defaults to the field explicit mapping definition, or the default search analyzer, for example:

This query also accepts zero_terms_query, as explained in match query.

The match_phrase_prefix is the same as match_phrase, except that it allows for prefix matches on the last term in the text. For example:

It accepts the same parameters as the phrase type. In addition, it also accepts a max_expansions parameter (default 50) that can control to how many suffixes the last term will be expanded. It is highly recommended to set it to an acceptable value to control the execution time of the query. For example:

The multi_match query builds on the match query to allow multi-field queries:

Fields can be specified with wildcards, eg:

Individual fields can be boosted with the caret (^) notation:

If no fields are provided, the multi_match query defaults to the index.query.default_field index settings, which in turn defaults to . extracts all fields in the mapping that are eligible to term queries and filters the metadata fields. All extracted fields are then combined to build a query.

The way the multi_match query is executed internally depends on the type parameter, which can be set to:

The common terms query is a modern alternative to stopwords which improves the precision and recall of search results (by taking stopwords into account), without sacrificing performance.

Every term in a query has a cost. A search for "The brown fox" requires three term queries, one for each of "the", "brown" and "fox", all of which are executed against all documents in the index. The query for "the" is likely to match many documents and thus has a much smaller impact on relevance than the other two terms.

Previously, the solution to this problem was to ignore terms with high frequency. By treating "the" as a stopword, we reduce the index size and reduce the number of term queries that need to be executed.

The problem with this approach is that, while stopwords have a small impact on relevance, they are still important. If we remove stopwords, we lose precision, (eg we are unable to distinguish between "happy" and "not happy") and we lose recall (eg text like "The The" or "To be or not to be" would simply not exist in the index).

The common terms query divides the query terms into two groups: more important (ie low frequency terms) and less important (ie high frequency terms which would previously have been stopwords).

First it searches for documents which match the more important terms. These are the terms which appear in fewer documents and have a greater impact on relevance.

Then, it executes a second query for the less important terms — terms which appear frequently and have a low impact on relevance. But instead of calculating the relevance score for all matching documents, it only calculates the _score for documents already matched by the first query. In this way the high frequency terms can improve the relevance calculation without paying the cost of poor performance.

If a query consists only of high frequency terms, then a single query is executed as an AND (conjunction) query, in other words all terms are required. Even though each individual term will match many documents, the combination of terms narrows down the resultset to only the most relevant. The single query can also be executed as an OR with a specific minimum_should_match, in this case a high enough value should probably be used.

Terms are allocated to the high or low frequency groups based on the cutoff_frequency, which can be specified as an absolute frequency (>=1) or as a relative frequency (0.0 .. 1.0). (Remember that document frequencies are computed on a per shard level as explained in the blog post {defguide}/relevance-is-broken.html[Relevance is broken].)

Perhaps the most interesting property of this query is that it adapts to domain specific stopwords automatically. For example, on a video hosting site, common terms like "clip" or "video" will automatically behave as stopwords without the need to maintain a manual list.

In this example, words that have a document frequency greater than 0.1% (eg "this" and "is") will be treated as common terms.

The number of terms which should match can be controlled with the minimum_should_match (high_freq, low_freq), low_freq_operator (default "or") and high_freq_operator (default "or") parameters.

For low frequency terms, set the low_freq_operator to "and" to make all terms required:

which is roughly equivalent to:

Alternatively use minimum_should_match to specify a minimum number or percentage of low frequency terms which must be present, for instance:

which is roughly equivalent to:

A different minimum_should_match can be applied for low and high frequency terms with the additional low_freq and high_freq parameters. Here is an example when providing additional parameters (note the change in structure):

which is roughly equivalent to:

In this case it means the high frequency terms have only an impact on relevance when there are at least three of them. But the most interesting use of the minimum_should_match for high frequency terms is when there are only high frequency terms:

which is roughly equivalent to:

The high frequency generated query is then slightly less restrictive than with an AND.

The common terms query also supports boost and analyzer as parameters.

A query that uses a query parser in order to parse its content. Here is an example:

The query_string query parses the input and splits text around operators. Each textual part is analyzed independently of each other. For instance the following query:

When multiple fields are provided it is also possible to modify how the different field queries are combined inside each textual part using the type parameter. The possible modes are described here and the default is best_fields.

The query_string top level parameters include:

When a multi term query is being generated, one can control how it gets rewritten using the rewrite parameter.

When not explicitly specifying the field to search on in the query string syntax, the index.query.default_field will be used to derive which field to search on. If the index.query.default_field is not specified, the query_string will automatically attempt to determine the existing fields in the index’s mapping that are queryable, and perform the search on those fields. This will not include nested documents, use a nested query to search those documents.

The query_string query can also run against multiple fields. Fields can be provided via the fields parameter (example below).

The idea of running the query_string query against multiple fields is to expand each query term to an OR clause like this:

For example, the following query

matches the same words as

Since several queries are generated from the individual search terms, combining them is automatically done using a dis_max query with a tie_breaker. For example (the name is boosted by 5 using ^5 notation):

Simple wildcard can also be used to search "within" specific inner elements of the document. For example, if we have a city object with several fields (or inner object with fields) in it, we can automatically search on all "city" fields:

Another option is to provide the wildcard fields search in the query string itself (properly escaping the sign), for example: city.\:something:

When running the query_string query against multiple fields, the following additional parameters are allowed:

The fields parameter can also include pattern based field names, allowing to automatically expand to the relevant fields (dynamically introduced fields included). For example:

The query_string query supports multi-terms synonym expansion with the synonym_graph token filter. When this filter is used, the parser creates a phrase query for each multi-terms synonyms. For example, the following synonym: ny, new york would produce:

(ny OR ("new york"))

It is also possible to match multi terms synonyms with conjunctions instead:

The example above creates a boolean query:

(ny OR (new AND york)) city)

that matches documents with the term ny or the conjunction new AND york. By default the parameter auto_generate_synonyms_phrase_query is set to true.

The query_string splits the query around each operator to create a boolean query for the entire input. You can use minimum_should_match to control how many "should" clauses in the resulting query should match.

The example above creates a boolean query:

(title:this title:that title:thus)~2

that matches documents with at least two of the terms this, that or thus in the single field title.

The example above creates a boolean query:

content:this content:that content:thus) | (title:this title:that title:thus

that matches documents with the disjunction max over the fields title and content. Here the minimum_should_match parameter can’t be applied.

Adding explicit operators forces each term to be considered as a separate clause.

The example above creates a boolean query:

content:this | title:this) (content:that | title:that) (content:thus | title:thus~2

that matches documents with at least two of the three "should" clauses, each of them made of the disjunction max over the fields for each term.

The cross_fields value in the type field indicates that fields that have the same analyzer should be grouped together when the input is analyzed.

The example above creates a boolean query:

(blended(terms:[field2:this, field1:this]) blended(terms:[field2:that, field1:that]) blended(terms:[field2:thus, field1:thus]))~2

that matches documents with at least two of the three per-term blended queries.

A query that uses the SimpleQueryParser to parse its context. Unlike the regular query_string query, the simple_query_string query will never throw an exception, and discards invalid parts of the query. Here is an example:

The simple_query_string top level parameters include:

The simple_query_string supports the following special characters:

In order to search for any of these special characters, they will need to be escaped with \.

Be aware that this syntax may have a different behavior depending on the default_operator value. For example, consider the following query:

You may expect that documents containing only "foo" or "bar" will be returned, as long as they do not contain "baz", however, due to the default_operator being OR, this really means "match documents that contain "foo" or documents that contain "bar", or documents that don’t contain "baz". If this is unintended then the query can be switched to "foo bar +-baz" which will not return documents that contain "baz".

When not explicitly specifying the field to search on in the query string syntax, the index.query.default_field will be used to derive which fields to search on. It defaults to * and the query will automatically attempt to determine the existing fields in the index’s mapping that are queryable, and perform the search on those fields.

The fields parameter can also include pattern based field names, allowing to automatically expand to the relevant fields (dynamically introduced fields included). For example:

simple_query_string support multiple flags to specify which parsing features should be enabled. It is specified as a |-delimited string with the flags parameter:

The available flags are:

The simple_query_string query supports multi-terms synonym expansion with the synonym_graph token filter. When this filter is used, the parser creates a phrase query for each multi-terms synonyms. For example, the following synonym: "ny, new york" would produce:

(ny OR ("new york"))

It is also possible to match multi terms synonyms with conjunctions instead:

The example above creates a boolean query:

(ny OR (new AND york)) city)

that matches documents with the term ny or the conjunction new AND york. By default the parameter auto_generate_synonyms_phrase_query is set to true.

The term query finds documents that contain the exact term specified in the inverted index. For instance:

A boost parameter can be specified to give this term query a higher relevance score than another query, for instance:

A term query can also match against range data types.

Filters documents that have fields that match any of the provided terms (not analyzed). For example:

When it’s needed to specify a terms filter with a lot of terms it can be beneficial to fetch those term values from a document in an index. A concrete example would be to filter tweets tweeted by your followers. Potentially the amount of user ids specified in the terms filter can be a lot. In this scenario it makes sense to use the terms filter’s terms lookup mechanism.

The terms lookup mechanism supports the following options:

The values for the terms filter will be fetched from a field in a document with the specified id in the specified type and index. Internally a get request is executed to fetch the values from the specified path. At the moment for this feature to work the _source needs to be stored.

Also, consider using an index with a single shard and fully replicated across all nodes if the "reference" terms data is not large. The lookup terms filter will prefer to execute the get request on a local node if possible, reducing the need for networking.

At first we index the information for user with id 2, specifically, its followers, then index a tweet from user with id 1. Finally we search on all the tweets that match the followers of user 2.

The structure of the external terms document can also include an array of inner objects, for example:

In which case, the lookup path will be followers.id.

Returns any documents that match with at least one or more of the provided terms. The terms are not analyzed and thus must match exactly. The number of terms that must match varies per document and is either controlled by a minimum should match field or computed per document in a minimum should match script.

The field that controls the number of required terms that must match must be a number field:

An example that uses the minimum should match field:

Response:

Scripts can also be used to control how many terms are required to match in a more dynamic way. For example a create date or a popularity field can be used as basis for the number of required terms to match.

Also the params.num_terms parameter is available in the script to indicate the number of terms that have been specified.

An example that always limits the number of required terms to match to never become larger than the number of terms specified:

Matches documents with fields that have terms within a certain range. The type of the Lucene query depends on the field type, for string fields, the TermRangeQuery, while for number/date fields, the query is a NumericRangeQuery. The following example returns all documents where age is between 10 and 20:

The range query accepts the following parameters:

Returns documents that contain a value other than null or [] in a provided field.

Matches documents that have fields containing terms with a specified prefix (not analyzed). The prefix query maps to Lucene PrefixQuery. The following matches documents where the user field contains a term that starts with ki:

A boost can also be associated with the query:

This multi term query allows you to control how it gets rewritten using the rewrite parameter.

Returns documents that contain terms matching a wildcard pattern.

A wildcard operator is a placeholder that matches one or more characters. For example, the * wildcard operator matches zero or more characters. You can combine wildcard operators with other characters to create a wildcard pattern.

The regexp query allows you to use regular expression term queries. See Regular expression syntax for details of the supported regular expression language. The "term queries" in that first sentence means that Elasticsearch will apply the regexp to the terms produced by the tokenizer for that field, and not to the original text of the field.

Note: The performance of a regexp query heavily depends on the regular expression chosen. Matching everything like . is very slow as well as using lookaround regular expressions. If possible, you should try to use a long prefix before your regular expression starts. Wildcard matchers like .?+ will mostly lower performance.

Boosting is also supported

You can also use special flags

Possible flags are ALL (default), ANYSTRING, COMPLEMENT, EMPTY, INTERSECTION, INTERVAL, or NONE. Please check the Lucene documentation for their meaning

Regular expressions are dangerous because it’s easy to accidentally create an innocuous looking one that requires an exponential number of internal determinized automaton states (and corresponding RAM and CPU) for Lucene to execute. Lucene prevents these using the max_determinized_states setting (defaults to 10000). You can raise this limit to allow more complex regular expressions to execute.

The fuzzy query uses similarity based on Levenshtein edit distance.

Filters documents matching the provided document / mapping type.

Returns documents based on their IDs. This query uses document IDs stored in the _id field.

Wraps a filter query and returns every matching document with a relevance score equal to the boost parameter value.

A query that matches documents matching boolean combinations of other queries. The bool query maps to Lucene BooleanQuery. It is built using one or more boolean clauses, each clause with a typed occurrence. The occurrence types are:

The bool query takes a more-matches-is-better approach, so the score from each matching must or should clause will be added together to provide the final _score for each document.

A query that generates the union of documents produced by its subqueries, and that scores each document with the maximum score for that document as produced by any subquery, plus a tie breaking increment for any additional matching subqueries.

This is useful when searching for a word in multiple fields with different boost factors (so that the fields cannot be combined equivalently into a single search field). We want the primary score to be the one associated with the highest boost, not the sum of the field scores (as Boolean Query would give). If the query is "albino elephant" this ensures that "albino" matching one field and "elephant" matching another gets a higher score than "albino" matching both fields. To get this result, use both Boolean Query and DisjunctionMax Query: for each term a DisjunctionMaxQuery searches for it in each field, while the set of these DisjunctionMaxQuery’s is combined into a BooleanQuery.

The tie breaker capability allows results that include the same term in multiple fields to be judged better than results that include this term in only the best of those multiple fields, without confusing this with the better case of two different terms in the multiple fields.The default tie_breaker is 0.0.

This query maps to Lucene DisjunctionMaxQuery.

The function_score allows you to modify the score of documents that are retrieved by a query. This can be useful if, for example, a score function is computationally expensive and it is sufficient to compute the score on a filtered set of documents.

To use function_score, the user has to define a query and one or more functions, that compute a new score for each document returned by the query.

function_score can be used with only one function like this:

Furthermore, several functions can be combined. In this case one can optionally choose to apply the function only if a document matches a given filtering query

If no filter is given with a function this is equivalent to specifying "match_all": {}

First, each document is scored by the defined functions. The parameter score_mode specifies how the computed scores are combined:

Because scores can be on different scales (for example, between 0 and 1 for decay functions but arbitrary for field_value_factor) and also because sometimes a different impact of functions on the score is desirable, the score of each function can be adjusted with a user defined weight. The weight can be defined per function in the functions array (example above) and is multiplied with the score computed by the respective function. If weight is given without any other function declaration, weight acts as a function that simply returns the weight.

In case score_mode is set to avg the individual scores will be combined by a weighted average. For example, if two functions return score 1 and 2 and their respective weights are 3 and 4, then their scores will be combined as (1*3+2*4)/(3+4) and not (1*3+2*4)/2.

The new score can be restricted to not exceed a certain limit by setting the max_boost parameter. The default for max_boost is FLT_MAX.

The newly computed score is combined with the score of the query. The parameter boost_mode defines how:

By default, modifying the score does not change which documents match. To exclude documents that do not meet a certain score threshold the min_score parameter can be set to the desired score threshold.

The function_score query provides several types of score functions.

The boosting query can be used to effectively demote results that match a given query. Unlike the "NOT" clause in bool query, this still selects documents that contain undesirable terms, but reduces their overall score.

Wraps another query to search nested fields.

The nested query searches nested field objects as if they were indexed as separate documents. If an object matches the search, the nested query returns the root parent document.

The has_child filter accepts a query and the child type to run against, and results in parent documents that have child docs matching the query. Here is an example:

Note that the has_child is a slow query compared to other queries in the query dsl due to the fact that it performs a join. The performance degrades as the number of matching child documents pointing to unique parent documents increases. If you care about query performance you should not use this query. However if you do happen to use this query then use it as little as possible. Each has_child query that gets added to a search request can increase query time significantly.

The has_child also has scoring support. The supported score modes are min, max, sum, avg or none. The default is none and yields the same behaviour as in previous versions. If the score mode is set to another value than none, the scores of all the matching child documents are aggregated into the associated parent documents. The score type can be specified with the score_mode field inside the has_child query:

The has_child query allows you to specify that a minimum and/or maximum number of children are required to match for the parent doc to be considered a match:

The min_children and max_children parameters can be combined with the score_mode parameter.

When set to true the ignore_unmapped option will ignore an unmapped type and will not match any documents for this query. This can be useful when querying multiple indexes which might have different mappings. When set to false (the default value) the query will throw an exception if the type is not mapped.

Parent documents can’t be sorted by fields in matching child documents via the regular sort options. If you need to sort parent document by field in the child documents then you should use the function_score query and then just sort by _score.

Sorting blogs by child documents' click_count field:

The has_parent query accepts a query and a parent type. The query is executed in the parent document space, which is specified by the parent type. This query returns child documents which associated parents have matched. For the rest has_parent query has the same options and works in the same manner as the has_child query.

Note that the has_parent is a slow query compared to other queries in the query dsl due to the fact that it performs a join. The performance degrades as the number of matching parent documents increases. If you care about query performance you should not use this query. However if you do happen to use this query then use it as less as possible. Each has_parent query that gets added to a search request can increase query time significantly.

The has_parent also has scoring support. The default is false which ignores the score from the parent document. The score is in this case equal to the boost on the has_parent query (Defaults to 1). If the score is set to true, then the score of the matching parent document is aggregated into the child documents belonging to the matching parent document. The score mode can be specified with the score field inside the has_parent query:

When set to true the ignore_unmapped option will ignore an unmapped type and will not match any documents for this query. This can be useful when querying multiple indexes which might have different mappings. When set to false (the default value) the query will throw an exception if the type is not mapped.

Child documents can’t be sorted by fields in matching parent documents via the regular sort options. If you need to sort child documents by field in the parent documents then you should use the function_score query and then just sort by _score.

Sorting tags by parent document' view_count field:

The parent_id query can be used to find child documents which belong to a particular parent. Given the following mapping definition:

Filter documents indexed using the geo_shape type.

Requires the geo_shape Mapping.

The geo_shape query uses the same grid square representation as the geo_shape mapping to find documents that have a shape that intersects with the query shape. It will also use the same Prefix Tree configuration as defined for the field mapping.

The query supports two ways of defining the query shape, either by providing a whole shape definition, or by referencing the name of a shape pre-indexed in another index. Both formats are defined below with examples.

A query allowing to filter hits based on a point location using a bounding box. Assuming the following indexed document:

Then the following simple query can be executed with a geo_bounding_box filter:

In much the same way the geo_point type can accept different representations of the geo point, the filter can accept it as well:

Format in [lon, lat], note, the order of lon/lat here in order to conform with GeoJSON.

Format in lat,lon.

The vertices of the bounding box can either be set by top_left and bottom_right or by top_right and bottom_left parameters. More over the names topLeft, bottomRight, topRight and bottomLeft are supported. Instead of setting the values pairwise, one can use the simple names top, left, bottom and right to set the values separately.

The filter requires the geo_point type to be set on the relevant field.

The filter can work with multiple locations / points per document. Once a single location / point matches the filter, the document will be included in the filter

The type of the bounding box execution by default is set to memory, which means in memory checks if the doc falls within the bounding box range. In some cases, an indexed option will perform faster (but note that the geo_point type must have lat and lon indexed in this case). Note, when using the indexed option, multi locations per document field are not supported. Here is an example:

When set to true the ignore_unmapped option will ignore an unmapped field and will not match any documents for this query. This can be useful when querying multiple indexes which might have different mappings. When set to false (the default value) the query will throw an exception if the field is not mapped.

Geopoints have limited precision and are always rounded down during index time. During the query time, upper boundaries of the bounding boxes are rounded down, while lower boundaries are rounded up. As a result, the points along on the lower bounds (bottom and left edges of the bounding box) might not make it into the bounding box due to the rounding error. At the same time points alongside the upper bounds (top and right edges) might be selected by the query even if they are located slightly outside the edge. The rounding error should be less than 4.20e-8 degrees on the latitude and less than 8.39e-8 degrees on the longitude, which translates to less than 1cm error even at the equator.

Filters documents that include only hits that exists within a specific distance from a geo point. Assuming the following mapping and indexed document:

Then the following simple query can be executed with a geo_distance filter:

In much the same way the geo_point type can accept different representations of the geo point, the filter can accept it as well:

Format in [lon, lat], note, the order of lon/lat here in order to conform with GeoJSON.

Format in lat,lon.

The following are options allowed on the filter:

The filter requires the geo_point type to be set on the relevant field.

The geo_distance filter can work with multiple locations / points per document. Once a single location / point matches the filter, the document will be included in the filter.

When set to true the ignore_unmapped option will ignore an unmapped field and will not match any documents for this query. This can be useful when querying multiple indexes which might have different mappings. When set to false (the default value) the query will throw an exception if the field is not mapped.

A query returning hits that only fall within a polygon of points. Here is an example:

Format as [lon, lat]

Note: the order of lon/lat here must conform with GeoJSON.

Format in lat,lon.

The query requires the geo_point type to be set on the relevant field.

When set to true the ignore_unmapped option will ignore an unmapped field and will not match any documents for this query. This can be useful when querying multiple indexes which might have different mappings. When set to false (the default value) the query will throw an exception if the field is not mapped.

The More Like This Query finds documents that are "like" a given set of documents. In order to do so, MLT selects a set of representative terms of these input documents, forms a query using these terms, executes the query and returns the results. The user controls the input documents, how the terms should be selected and how the query is formed.

The simplest use case consists of asking for documents that are similar to a provided piece of text. Here, we are asking for all movies that have some text similar to "Once upon a time" in their "title" and in their "description" fields, limiting the number of selected terms to 12.

A more complicated use case consists of mixing texts with documents already existing in the index. In this case, the syntax to specify a document is similar to the one used in the Multi GET API.

Finally, users can mix some texts, a chosen set of documents but also provide documents not necessarily present in the index. To provide documents not present in the index, the syntax is similar to artificial documents.

A query allowing to define scripts as queries. They are typically used in a filter context, for example:

Scripts are compiled and cached for faster execution. If the same script can be used, just with different parameters provider, it is preferable to use the ability to pass parameters to the script itself, for example:

The percolate query can be used to match queries stored in an index. The percolate query itself contains the document that will be used as query to match with the stored queries.

Create an index with two fields:

The message field is the field used to preprocess the document defined in the percolator query before it gets indexed into a temporary index.

The query field is used for indexing the query documents. It will hold a json object that represents an actual Elasticsearch query. The query field has been configured to use the percolator field type. This field type understands the query dsl and stores the query in such a way that it can be used later on to match documents defined on the percolate query.

Register a query in the percolator:

Match a document to the registered percolator queries:

The above request will yield the following response:

The following parameters are required when percolating a document:

Instead of specifying the source of the document being percolated, the source can also be retrieved from an already stored document. The percolate query will then internally execute a get request to fetch that document.

In that case the document parameter can be substituted with the following parameters:

In case you are not interested in the score, better performance can be expected by wrapping the percolator query in a bool query’s filter clause or in a constant_score query:

At index time terms are extracted from the percolator query and the percolator can often determine whether a query matches just by looking at those extracted terms. However, computing scores requires to deserialize each matching query and run it against the percolated document, which is a much more expensive operation. Hence if computing scores is not required the percolate query should be wrapped in a constant_score query or a bool query’s filter clause.

Note that the percolate query never gets cached by the query cache.

The percolate query can match multiple documents simultaneously with the indexed percolator queries. Percolating multiple documents in a single request can improve performance as queries only need to be parsed and matched once instead of multiple times.

The _percolator_document_slot field that is being returned with each matched percolator query is important when percolating multiple documents simultaneously. It indicates which documents matched with a particular percolator query. The numbers correlate with the slot in the documents array specified in the percolate query.

In order to percolate a newly indexed document, the percolate query can be used. Based on the response from an index request, the _id and other meta information can be used to immediately percolate the newly added document.

Based on the previous example.

Index the document we want to percolate:

Index response:

Percolating an existing document, using the index response as basis to build to new search request:

The search response returned is identical as in the previous example.

The percolate query is handled in a special way when it comes to highlighting. The queries hits are used to highlight the document that is provided in the percolate query. Whereas with regular highlighting the query in the search request is used to highlight the hits.

This example is based on the mapping of the first example.

Save a query:

Save another query:

Execute a search request with the percolate query and highlighting enabled:

This will yield the following response.

Instead of the query in the search request highlighting the percolator hits, the percolator queries are highlighting the document defined in the percolate query.

When percolating multiple documents at the same time like the request below then the highlight response is different:

The slightly different response:

It is possible to specify multiple percolate queries in a single search request:

The _percolator_document_slot field name will be suffixed with what is specified in the _name parameter. If that isn’t specified then the field parameter will be used, which in this case will result in ambiguity.

The above search request returns a response similar to this:

When indexing a document into an index that has the percolator field type mapping configured, the query part of the document gets parsed into a Lucene query and is stored into the Lucene index. A binary representation of the query gets stored, but also the query’s terms are analyzed and stored into an indexed field.

At search time, the document specified in the request gets parsed into a Lucene document and is stored in a in-memory temporary Lucene index. This in-memory index can just hold this one document and it is optimized for that. After this a special query is built based on the terms in the in-memory index that select candidate percolator queries based on their indexed query terms. These queries are then evaluated by the in-memory index if they actually match.

The selecting of candidate percolator queries matches is an important performance optimization during the execution of the percolate query as it can significantly reduce the number of candidate matches the in-memory index needs to evaluate. The reason the percolate query can do this is because during indexing of the percolator queries the query terms are being extracted and indexed with the percolator query. Unfortunately the percolator cannot extract terms from all queries (for example the wildcard or geo_shape query) and as a result of that in certain cases the percolator can’t do the selecting optimization (for example if an unsupported query is defined in a required clause of a boolean query or the unsupported query is the only query in the percolator document). These queries are marked by the percolator and can be found by running the following search:

Given the design of percolation, it often makes sense to use separate indices for the percolate queries and documents being percolated, as opposed to a single index as we do in examples. There are a few benefits to this approach:

A query that accepts any other query as base64 encoded string.

This query is more useful in the context of the Java high-level REST client or transport client to also accept queries as json formatted string. In these cases queries can be specified as a json or yaml formatted string or as a query builder (which is a available in the Java high-level REST client).

Matches spans containing a term. The span term query maps to Lucene SpanTermQuery. Here is an example:

A boost can also be associated with the query:

Or :

The span_multi query allows you to wrap a multi term query (one of wildcard, fuzzy, prefix, range or regexp query) as a span query, so it can be nested. Example:

A boost can also be associated with the query:

Matches spans near the beginning of a field. The span first query maps to Lucene SpanFirstQuery. Here is an example:

The match clause can be any other span type query. The end controls the maximum end position permitted in a match.

Matches spans which are near one another. One can specify slop, the maximum number of intervening unmatched positions, as well as whether matches are required to be in-order. The span near query maps to Lucene SpanNearQuery. Here is an example:

The clauses element is a list of one or more other span type queries and the slop controls the maximum number of intervening unmatched positions permitted.

Matches the union of its span clauses. The span or query maps to Lucene SpanOrQuery. Here is an example:

The clauses element is a list of one or more other span type queries.

Removes matches which overlap with another span query or which are within x tokens before (controlled by the parameter pre) or y tokens after (controled by the parameter post) another SpanQuery. The span not query maps to Lucene SpanNotQuery. Here is an example:

The include and exclude clauses can be any span type query. The include clause is the span query whose matches are filtered, and the exclude clause is the span query whose matches must not overlap those returned.

In the above example all documents with the term hoya are filtered except the ones that have 'la' preceding them.

Other top level options:

Returns matches which enclose another span query. The span containing query maps to Lucene SpanContainingQuery. Here is an example:

The big and little clauses can be any span type query. Matching spans from big that contain matches from little are returned.

Returns matches which are enclosed inside another span query. The span within query maps to Lucene SpanWithinQuery. Here is an example:

The big and little clauses can be any span type query. Matching spans from little that are enclosed within big are returned.

Wrapper to allow span queries to participate in composite single-field span queries by 'lying' about their search field. The span field masking query maps to Lucene’s SpanFieldMaskingQuery

This can be used to support queries like span-near or span-or across different fields, which is not ordinarily permitted.

Span field masking query is invaluable in conjunction with multi-fields when same content is indexed with multiple analyzers. For instance we could index a field with the standard analyzer which breaks text up into words, and again with the english analyzer which stems words into their root form.

Example:

Note: as span field masking query returns the masked field, scoring will be done using the norms of the field name supplied. This may lead to unexpected scoring behaviour.