Type to search.

Create or update a query rule

Auth The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 8.15 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

Create or update a query rule within a query ruleset.

Important

Due to limitations within pinned queries, you can only pin documents using ids or docs, but cannot use both in single rule. It is advised to use one or the other in query rulesets, to avoid errors. Additionally, pinned queries have a maximum limit of 100 pinned hits. If multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.

About editing rules and rulesets

Required privileges

Cluster privileges manage_search_query_rules

Path parameters

ruleset_id string required

The unique identifier of the query ruleset containing the rule to be created or updated.

rule_id string required

The unique identifier of the query rule within the specified ruleset to be created or updated.

Request body

type enum required

The type of rule.

Values: pinned exclude
criteria union oneOf required

The criteria that must be met for the rule to be applied. If multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.

object or object[]
type enum required

The type of criteria. The following criteria types are supported:

  • always: Matches all queries, regardless of input.
  • contains: Matches that contain this value anywhere in the field meet the criteria defined by the rule. Only applicable for string values.
  • exact: Only exact matches meet the criteria defined by the rule. Applicable for string or numerical values.
  • fuzzy: Exact matches or matches within the allowed Levenshtein Edit Distance meet the criteria defined by the rule. Only applicable for string values.
  • gt: Matches with a value greater than this value meet the criteria defined by the rule. Only applicable for numerical values.
  • gte: Matches with a value greater than or equal to this value meet the criteria defined by the rule. Only applicable for numerical values.
  • lt: Matches with a value less than this value meet the criteria defined by the rule. Only applicable for numerical values.
  • lte: Matches with a value less than or equal to this value meet the criteria defined by the rule. Only applicable for numerical values.
  • prefix: Matches that start with this value meet the criteria defined by the rule. Only applicable for string values.
  • suffix: Matches that end with this value meet the criteria defined by the rule. Only applicable for string values.
Values: global exact fuzzy prefix suffix contains lt lte gt gte always
metadata string

The metadata field to match against. This metadata will be used to match against match_criteria sent in the rule. It is required for all criteria types except always.

values object[]

The values to match against the metadata field. Only one value must match for the criteria to be met. It is required for all criteria types except always.

actions object required

The actions to take when the rule is matched. The format of this action depends on the rule type.

ids string[]

The unique document IDs of the documents to apply the rule to. Only one of ids or docs may be specified and at least one must be specified.

priority number

Response

application/json
result enum required
Values: created updated deleted not_found noop