Create or update a query rule

PUT /_query_rules/{ruleset_id}/_rule/{rule_id}

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.

Required authorization

Authentication

Api key

Authorization: <value>

Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:

		curl -X GET "${ES_URL}/_cat/indices?v=true" \
  -H "Authorization: ApiKey ${API_KEY}"

To get API keys, use the /_security/api_key APIs.

Basic

Authorization: Basic <credentials>

Bearer

Authorization: Bearer <token>

Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API. For examples, refer to Token-based authentication services

Path parameters

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[]
actions object required: The actions to take when the rule is matched. The format of this action depends on the rule type.
priority number

Response

application/json

Examples

Request Console 1 / 8 languages

Run POST _query_rules/my-ruleset/_test to test a ruleset. Provide the match criteria that you want to test against.

Console Kibana Dev Tools

POST _query_rules/my-ruleset/_test
{
  "match_criteria": {
    "query_string": "puggles"
  }
}

JavaScript Elasticsearch JavaScript Client

const response = await client.queryRules.test({
  ruleset_id: "my-ruleset",
  match_criteria: {
    query_string: "puggles",
  },
});

Python Elasticsearch Python Client

resp = client.query_rules.test(
    ruleset_id="my-ruleset",
    match_criteria={
        "query_string": "puggles"
    },
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_query_rules/my-ruleset/_test" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "match_criteria": {
      "query_string": "puggles"
    }
  }'

Java Elasticsearch Java Client

client.queryRules().test(t -> t
    .matchCriteria("query_string", JsonData.fromJson("\"puggles\""))
    .rulesetId("my-ruleset")
);

C# Elasticsearch .NET Client

var response = await client.QueryRules
    .TestAsync(rulesetId: "my-ruleset", d1 => d1
        .MatchCriteria(new Dictionary<string, object>()
        {
            { "query_string", "puggles" }
        })
    );

PHP Elasticsearch PHP Client

$resp = $client->queryRules()->test([
    "ruleset_id" => "my-ruleset",
    "body" => [
        "match_criteria" => [
            "query_string" => "puggles",
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.query_rules.test(
  ruleset_id: "my-ruleset",
  body: {
    "match_criteria": {
      "query_string": "puggles"
    }
  }
)

Response

No example

Required authorization

Authentication

Path parameters

Request body { }

Response

Request body