Path parameters

  • ruleset_idstring Required

    The unique identifier of the query ruleset to be created or updated.

application/json

BodyRequired

  • rulesobject | array[object]

    One of:
    QueryRuleobjectarray-2array[object]
    Hide attributes Show attributes object
    • rule_idstring Required
    • typestring Required

      Values are pinned or exclude.

    • criteriaobject | array[object]

      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.

      One of:
      QueryRuleCriteriaobjectarray-2array[object]
      Hide attributes Show attributes object
      • typestring Required

        Values are global, exact, exact_fuzzy, fuzzy, prefix, suffix, contains, lt, lte, gt, gte, or always.

      • metadatastring

        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.

      • valuesarray[object]

        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.

    • actionsobject Required
      Hide actions attributes Show actions attributes object
      • idsarray[string]

        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.

      • docsarray[object]

        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.
        Hide docs attributes Show docs attributes object
    • prioritynumber

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • resultstring Required

      Values are created, updated, deleted, not_found, or noop.

PUT /_query_rules/{ruleset_id}
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"
                    }
                ]
            }
        }
    ]
}
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"
                    }
                ]
            }
        }
    ],
)
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",
          },
        ],
      },
    },
  ],
});
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"
            }
          ]
        }
      }
    ]
  }
)
$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",
                        ],
                    ),
                ],
            ],
        ),
    ],
]);
curl -X PUT -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"}]}}]}' "$ELASTICSEARCH_URL/_query_rules/my-ruleset"
Request example
Run `PUT _query_rules/my-ruleset` to create a new query ruleset. Two rules are associated with `my-ruleset`. `my-rule1` will pin documents with IDs `id1` and `id2` when `user_query` contains `pugs` or `puggles` and `user_country` exactly matches `us`. `my-rule2` will exclude documents from different specified indices with IDs `id3` and `id4` when the `query_string` fuzzily matches `rescue dogs`.
{
    "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"
                    }
                ]
            }
        }
    ]
}