Searching with query rules
editSearching with query rules
editThis functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
Query rules allow customization of search results for queries that match specified criteria metadata.
This allows for more control over results, for example ensuring that promoted documents that match defined criteria are returned at the top of the result list.
Metadata is defined in the query rule, and is matched against the query criteria.
Query rules use metadata to match a query.
Metadata is provided as part of the rule_query
as an object and can be anything that helps differentiate the query, for example:
- A user-entered query string
- Personalized metadata about users (e.g. country, language, etc)
- A particular topic
- A referring site
- etc.
Query rules define a metadata key that will be used to match the metadata provided in the rule_query
with the criteria specified in the rule.
When a query rule matches the rule_query
metadata according to its defined criteria, the query rule action is applied to the underlying organic_query
.
For example, a query rule could be defined to match a user-entered query string of pugs
and a country us
and promote adoptable shelter dogs if the rule query met both criteria.
Rules are defined using the query rules API and searched using the rule query.
Rule definition
editWhen defining a rule, consider the following:
Rule type
editThe type of rule we want to apply. For the moment there is a single rule type:
-
pinned
will re-write the query into a pinned query, pinning specified results matching the query rule at the top of the returned result set.
Rule criteria
editThe criteria for which this rule will match. Criteria is defined as type
, metadata
, and values
.
Allowed criteria types are:
Type | Match Requirements |
---|---|
|
Rule metadata matches the specified value exactly. |
|
Rule metadata matches the specified value within an allowed Levenshtein edit distance. |
|
Rule metadata starts with the specified value. |
|
Rule metadata ends with the specified value. |
|
Rule metadata contains the specified value. |
|
Rule metadata is less than the specified value. |
|
Rule metadata is less than or equal to the specified value. |
|
Rule metadata is greater than the specified value. |
|
Rule metadata is greater than or equal to the specified value. |
|
Always matches for all rule queries. |
Rule actions
editThe actions to take when the rule matches a query:
-
ids
will pin the specified_id
s. -
docs
will pin the specified documents in the specified indices.
Use ids
when searching over a single index, and docs
when searching over multiple indices.
ids
and docs
cannot be combined in the same query.
See pinned query for details.
Add query rules
editYou can add query rules using the Create or update query ruleset call. This adds a ruleset containing one or more query rules that will be applied to queries that match their specified criteria.
The following command will create a query ruleset called my-ruleset
with two pinned document rules:
-
The first rule will generate a Pinned Query pinning the
_id
sid1
andid2
when thequery_string
metadata value is a fuzzy match to eitherpuggles
orpugs
and the user’s location is in the US. -
The second rule will generate a Pinned Query pinning the
_id
ofid3
specifically from themy-index-000001
index andid4
from themy-index-000002
index when thequery_string
metadata value containsbeagles
.
PUT /_query_rules/my-ruleset { "rules": [ { "rule_id": "rule1", "type": "pinned", "criteria": [ { "type": "fuzzy", "metadata": "query_string", "values": [ "puggles", "pugs" ] }, { "type": "exact", "metadata": "user_country", "values": [ "us" ] } ], "actions": { "ids": [ "id1", "id2" ] } }, { "rule_id": "rule2", "type": "pinned", "criteria": [ { "type": "contains", "metadata": "query_string", "values": [ "beagles" ] } ], "actions": { "docs": [ { "_index": "my-index-000001", "_id": "id3" }, { "_index": "my-index-000002", "_id": "id4" } ] } } ] }
The API response returns a results of created
or updated
depending on whether this was a new or edited ruleset.
There is a limit of 100 rules per ruleset.
This can be increased up to 1000 using the xpack.applications.rules.max_rules_per_ruleset
cluster setting.
{ "result": "created" }
You can use the Get query ruleset call to retrieve the ruleset you just created, the List query rulesets call to retrieve a summary of all query rulesets, and the Delete query ruleset call to delete a query ruleset.
Perform a rule query
editOnce you have defined a query ruleset, you can search this ruleset using the Rule query.
An example query for the my-ruleset
defined above is:
GET /my-index-000001/_search { "query": { "rule_query": { "organic": { "query_string": { "query": "puggles" } }, "match_criteria": { "query_string": "puggles", "user_country": "us" }, "ruleset_id": "my-ruleset" } } }
This rule query will match against rule1
in the defined query ruleset, and will convert the organic query into a pinned query with id1
and id2
pinned as the top hits.
Any other matches from the organic query will be returned below the pinned results.
It’s possible to have multiple rules in a ruleset match a single rule_query
. In this case, the pinned documents are returned in the following order:
- Where the matching rule appears in the ruleset
- If multiple documents are specified in a single rule, in the order they are specified