<titleabbrev>Create or update query ruleset</titleabbrev>
++++
Creates or updates a query ruleset.
[[put-query-ruleset-request]]
==== {api-request-title}
`PUT _query_rules/<ruleset_id>`
[[put-query-ruleset-prereqs]]
==== {api-prereq-title}
Requires the `manage_cluster` privilege.
[[put-query-ruleset-path-params]]
==== {api-path-parms-title}
`<body>`::
(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 <<query-dsl-pinned-query,Pinned Query>>.
The following actions are allowed:
- `ids` (Optional, array of strings)
The The unique <<mapping-id-field, document IDs>> 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 <<mapping-id-field, document ID>>.
--
====
[[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`.
