[role="xpack"]
[[put-query-ruleset]]
=== Create or update query ruleset

preview::[]

++++
<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`.

[source,console]
----
PUT _query_rules/my-ruleset
{
    "rules": [
        {
            "rule_id": "my-rule1",
            "type": "pinned",
            "criteria": [
                {
                    "type": "exact",
                    "metadata": "query_string",
                    "values": ["marvel"]
                }
            ],
            "actions": {
                "ids": [
                    "id1",
                    "id2"
                ]
            }
        },
        {
            "rule_id": "my-rule2",
            "type": "pinned",
            "criteria": [
                {
                    "type": "exact",
                    "metadata": "query_string",
                    "values": ["dc"]
                }
            ],
            "actions": {
                "docs": [
                    {
                        "_index": "index1",
                        "_id": "id3"
                    },
                    {
                        "_index": "index2",
                        "_id": "id4"
                    }
                ]
            }
        }
    ]
}
----
// TESTSETUP

//////////////////////////

[source,console]
--------------------------------------------------
DELETE _query_rules/my-ruleset
--------------------------------------------------
// TEARDOWN

//////////////////////////
