--- type: api title: Create or update a query ruleset description: There is a limit of 100 rules per ruleset. url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/operation/operation-query-rules-put-ruleset resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/operation/operation-query-rules-put-ruleset products: - Elasticsearch --- # Create or update a query ruleset Availability: 8.10+ ## Paths - `PUT` `/_query_rules/{ruleset_id}` - [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#apikeyauth) - [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#basicauth) - [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#bearerauth) #### Path Parameters - `ruleset_id` (string Id) The unique identifier of the query ruleset to be created or updated. ## Description There is a limit of 100 rules per ruleset. This limit can be increased by using the `xpack.applications.rules.max_rules_per_ruleset` cluster setting. IMPORTANT: Due to limitations within pinned queries, you can only select 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 * Cluster privileges: `manage_search_query_rules` [About editing rules and rulesets](https://www.elastic.co/docs/solutions/search/query-rules-ui#edit-a-rule) ## Request Body `application/json` - `rules` (union oneOf) — required `QueryRule` or `QueryRule[]` - `rule_id` (string Id) — required A unique identifier for the rule. - `type` (enum QueryRuleType) — required The type of rule. `pinned` will identify and pin specific documents to the top of search results. `exclude` will exclude specific documents from search results. 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. `QueryRuleCriteria` or `QueryRuleCriteria[]` - `type` (enum QueryRuleCriteriaType) — 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) — optional 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) — optional 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` ({} QueryRuleActions) — required The actions to take when the rule is matched. The format of this action depends on the rule type. - `ids` ([] string Id) — optional 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. - `docs` ([] PinnedDoc) — optional The documents to apply the rule to. Only one of `ids` or `docs` may be specified and at least one must be specified. There is a maximum value of 100 documents in a rule. You can specify the following attributes for each document: * `_index`: The index of the document to pin. * `_id`: The unique document ID. - `_id` (string Id) — required The unique document ID. - `_index` (string IndexName) — optional The index that contains the document. - `priority` (number) — optional ## Response `application/json` - `result` (enum Result) Values: `created`, `updated`, `deleted`, `not_found`, `noop` ## Code Examples #### Console ```console PUT _query_rules/my-ruleset { "rules": [ { "rule_id": "my-rule1", "type": "pinned", "criteria": [ { "type": "contains", "metadata": "user_query", "values": [ "pugs", "puggles" ] }, { "type": "exact", "metadata": "user_country", "values": [ "us" ] } ], "actions": { "ids": [ "id1", "id2" ] } }, { "rule_id": "my-rule2", "type": "pinned", "criteria": [ { "type": "fuzzy", "metadata": "user_query", "values": [ "rescue dogs" ] } ], "actions": { "docs": [ { "_index": "index1", "_id": "id3" }, { "_index": "index2", "_id": "id4" } ] } } ] } ``` #### JavaScript ```javascript const response = await client.queryRules.putRuleset({ ruleset_id: "my-ruleset", rules: [ { rule_id: "my-rule1", type: "pinned", criteria: [ { type: "contains", metadata: "user_query", values: ["pugs", "puggles"], }, { type: "exact", metadata: "user_country", values: ["us"], }, ], actions: { ids: ["id1", "id2"], }, }, { rule_id: "my-rule2", type: "pinned", criteria: [ { type: "fuzzy", metadata: "user_query", values: ["rescue dogs"], }, ], actions: { docs: [ { _index: "index1", _id: "id3", }, { _index: "index2", _id: "id4", }, ], }, }, ], }); ``` #### Python ```python resp = client.query_rules.put_ruleset( ruleset_id="my-ruleset", rules=[ { "rule_id": "my-rule1", "type": "pinned", "criteria": [ { "type": "contains", "metadata": "user_query", "values": [ "pugs", "puggles" ] }, { "type": "exact", "metadata": "user_country", "values": [ "us" ] } ], "actions": { "ids": [ "id1", "id2" ] } }, { "rule_id": "my-rule2", "type": "pinned", "criteria": [ { "type": "fuzzy", "metadata": "user_query", "values": [ "rescue dogs" ] } ], "actions": { "docs": [ { "_index": "index1", "_id": "id3" }, { "_index": "index2", "_id": "id4" } ] } } ], ) ``` #### curl ```curl curl -X PUT "$ELASTICSEARCH_URL/_query_rules/my-ruleset" \ -H "Authorization: ApiKey $ELASTIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "rules": [ { "rule_id": "my-rule1", "type": "pinned", "criteria": [ { "type": "contains", "metadata": "user_query", "values": [ "pugs", "puggles" ] }, { "type": "exact", "metadata": "user_country", "values": [ "us" ] } ], "actions": { "ids": [ "id1", "id2" ] } }, { "rule_id": "my-rule2", "type": "pinned", "criteria": [ { "type": "fuzzy", "metadata": "user_query", "values": [ "rescue dogs" ] } ], "actions": { "docs": [ { "_index": "index1", "_id": "id3" }, { "_index": "index2", "_id": "id4" } ] } } ] }' ``` #### Java ```java client.queryRules().putRuleset(p -> p .rules(List.of(QueryRule.queryRuleOf(q -> q .ruleId("my-rule1") .type(QueryRuleType.Pinned) .criteria(List.of(QueryRuleCriteria.of(qu -> qu .type(QueryRuleCriteriaType.Contains) .metadata("user_query") .values(List.of(JsonData.fromJson("\"pugs\""),JsonData.fromJson("\"puggles\""))) ),QueryRuleCriteria.of(qu -> qu .type(QueryRuleCriteriaType.Exact) .metadata("user_country") .values(JsonData.fromJson("\"us\"")) ))) .actions(a -> a .ids(List.of("id1","id2")) ) ),QueryRule.queryRuleOf(q -> q .ruleId("my-rule2") .type(QueryRuleType.Pinned) .criteria(c -> c .type(QueryRuleCriteriaType.Fuzzy) .metadata("user_query") .values(JsonData.fromJson("\"rescue dogs\"")) ) .actions(a -> a .docs(List.of(PinnedDoc.of(pi -> pi .id("id3") .index("index1") ),PinnedDoc.of(pi -> pi .id("id4") .index("index2") ))) ) ))) .rulesetId("my-ruleset") ); ``` #### C# ```c# var response = await client.QueryRules .PutRulesetAsync(rulesetId: "my-ruleset", d1 => d1 .Rules(d2 => d2 .Actions(d3 => d3 .Ids(["id1", "id2"]) ) .Criteria(d3 => d3 .Metadata("user_query") .Type(QueryRuleCriteriaType.Contains) .Values(["pugs", "puggles"]), d3 => d3 .Metadata("user_country") .Type(QueryRuleCriteriaType.Exact) .Values(["us"]) ) .RuleId("my-rule1") .Type(QueryRuleType.Pinned), d2 => d2 .Actions(d3 => d3 .Docs(d4 => d4 .Id("id3") .Index("index1"), d4 => d4 .Id("id4") .Index("index2") ) ) .Criteria(d3 => d3 .Metadata("user_query") .Type(QueryRuleCriteriaType.Fuzzy) .Values(["rescue dogs"]) ) .RuleId("my-rule2") .Type(QueryRuleType.Pinned) ) ); ``` #### PHP ```php $resp = $client->queryRules()->putRuleset([ "ruleset_id" => "my-ruleset", "body" => [ "rules" => array( [ "rule_id" => "my-rule1", "type" => "pinned", "criteria" => array( [ "type" => "contains", "metadata" => "user_query", "values" => array( "pugs", "puggles", ), ], [ "type" => "exact", "metadata" => "user_country", "values" => array( "us", ), ], ), "actions" => [ "ids" => array( "id1", "id2", ), ], ], [ "rule_id" => "my-rule2", "type" => "pinned", "criteria" => array( [ "type" => "fuzzy", "metadata" => "user_query", "values" => array( "rescue dogs", ), ], ), "actions" => [ "docs" => array( [ "_index" => "index1", "_id" => "id3", ], [ "_index" => "index2", "_id" => "id4", ], ), ], ], ), ], ]); ``` #### Ruby ```ruby response = client.query_rules.put_ruleset( ruleset_id: "my-ruleset", body: { "rules": [ { "rule_id": "my-rule1", "type": "pinned", "criteria": [ { "type": "contains", "metadata": "user_query", "values": [ "pugs", "puggles" ] }, { "type": "exact", "metadata": "user_country", "values": [ "us" ] } ], "actions": { "ids": [ "id1", "id2" ] } }, { "rule_id": "my-rule2", "type": "pinned", "criteria": [ { "type": "fuzzy", "metadata": "user_query", "values": [ "rescue dogs" ] } ], "actions": { "docs": [ { "_index": "index1", "_id": "id3" }, { "_index": "index2", "_id": "id4" } ] } } ] } ) ```