[role="xpack"]
[[put-query-ruleset]]
=== Create or update query ruleset
preview::[]
++++
Create or update query ruleset
++++
Creates or updates a query ruleset.
[[put-query-ruleset-request]]
==== {api-request-title}
`PUT _query_rules/`
[[put-query-ruleset-prereqs]]
==== {api-prereq-title}
Requires the `manage_cluster` privilege.
[[put-query-ruleset-path-params]]
==== {api-path-parms-title}
``::
(Required, object)
Contains parameters for a query ruleset:
====
`rules`::
(Required, array of objects)
The specific rules included in this query ruleset.
Each rule must have the following information:
- `rule_id` (Required, string)
A unique identifier for this rule.
- `type` (Required, string)
The type of rule. At this time only `pinned` query rule types are allowed.
- `criteria` (Required, array of objects)
- `actions` (Required, object)
The actions to take when the rule is matched. The format of this action depends on the rule type.
Criteria must have the following information:
- `type` (Required, string)
The type of criteria. At this time only `exact` criteria types are allowed.
- `metadata` (Required, string)
The metadata field to match against. At this time only `query_string` metadata types are allowed.
- `value` (Required, string)
The value to match against the metadata field.
Actions depend on the rule type.
For `pinned` rules, actions follow the format specified by the <>.
The following actions are allowed:
- `ids` (Optional, array of strings)
The The unique <> of the documents to pin. Only one of `ids` or `docs` may be specified, and at least one must be specified.
- `docs` (Optional, array of objects)
The documents to pin. Only one of `ids` or `docs` may be specified, and at least one must be specified.
You can specify the following attributes for each document:
+
--
- `_index` (Required, string)
The index of the document to pin.
- `_id` (Required, string)
The unique <>.
--
====
[[put-query-ruleset-example]]
==== {api-examples-title}
The following example creates a new query ruleset called `my-ruleset`.
Two rules are associated with `my-ruleset`:
- `my-rule1` will pin documents with IDs `id1` and `id2` when the `query_string` exactly matches `marvel`.
- `my-rule2` will pin documents from different, specified indices with IDs `id3` and `id4` when the `query_string` exactly matches `dc`.
[source,console]
----
PUT _query_rules/my-ruleset
{
"rules": [
{
"rule_id": "my-rule1",
"type": "pinned",
"criteria": [
{
"type": "exact",
"metadata": "query_string",
"value": "marvel"
}
],
"actions": {
"ids": [
"id1",
"id2"
]
}
},
{
"rule_id": "my-rule2",
"type": "pinned",
"criteria": [
{
"type": "exact",
"metadata": "query_string",
"value": "dc"
}
],
"actions": {
"docs": [
{
"_index": "index1",
"_id": "id3"
},
{
"_index": "index2",
"_id": "id4"
}
]
}
}
]
}
----
// TESTSETUP
//////////////////////////
[source,console]
--------------------------------------------------
DELETE _query_rules/my-ruleset
--------------------------------------------------
// TEARDOWN
//////////////////////////