Link Search Menu Expand Document Documentation Menu
Documentation

Search configurations

A search configuration defines the query pattern used to run experiments, specifying how queries should be constructed and executed.

Creating search configurations

You can define a search configuration to describe how every query of a query set is run. Every search configuration has a name and consists of a query body (a query in OpenSearch query domain-specific language [DSL]) and the target index. You can optionally define a search pipeline for the search configuration.

Endpoint

PUT _plugins/_search_relevance/search_configurations

Request body fields

The following table lists the available input parameters.

Field Data type Description
name String The name of the search configuration.
description String Description of the search configuration.
query Object Defines the query in OpenSearch query DSL, provided as a JSON string with the inner quotation marks escaped (for example, "query": "{\"query\":{\"multi_match\":{...}}}"). Use the %SearchText% placeholder or Mustache template variables (such as {{queryText}}) to substitute query set values at runtime. For more information, see Using Mustache templates.
index String The target index queried by this search configuration.
searchPipeline String Specifies an existing search pipeline. Optional.

Example request: Creating a search configuration

PUT _plugins/_search_relevance/search_configurations
{
  "name": "baseline",
  "query": "{\"query\":{\"multi_match\":{\"query\":\"%SearchText%\",\"fields\":[\"id\",\"title\",\"category\",\"bullets\",\"description\",\"attrs.Brand\",\"attrs.Color\"]}}}",
  "description": "Current production algorithm",
  "index": "ecommerce"
}

Using Mustache templates

Instead of the %SearchText% placeholder, you can use Mustache template variables in a query. If the query parameter contains double curly braces ({{}}), OpenSearch renders the query as a Mustache template; otherwise, OpenSearch substitutes the %SearchText% placeholder. Existing %SearchText% configurations continue to work unchanged.

When OpenSearch renders a template, the following variables are available:

  • {{queryText}}: The queryText value from the current query set entry.
  • {{<field_name>}}: Any custom field from the query set entry, referenced by its field name (for example, {{category}}). For more information, see Query sets.

OpenSearch automatically escapes substituted values, so query text that contains quotation marks or other special characters remains valid in JSON.

Mustache partials ({{>...}}) are not supported and cause the query to be rejected.

For example, the following request creates a search configuration that matches the user query against the title field and filters the results by the category custom field from each query set entry:

PUT _plugins/_search_relevance/search_configurations
{
  "name": "mustache_filter",
  "query": "{\"query\":{\"bool\":{\"must\":[{\"match\":{\"title\":\"{{queryText}}\"}}],\"filter\":[{\"term\":{\"category\":\"{{category}}\"}}]}}}",
  "description": "Title match filtered by a category custom field",
  "index": "ecommerce"
}

Managing search configurations

You can retrieve or delete configurations using the following APIs.

Retrieve search configurations

This API retrieves search configurations.

Endpoint

GET _plugins/_search_relevance/search_configurations
GET _plugins/_search_relevance/search_configurations/{search_configuration_id}

Example response

{
  "took": 3,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": null,
    "hits": [
      {
        "_index": "search-relevance-search-config",
        "_id": "92810080-9c5a-470f-a0ff-0eb85e7b818c",
        "_score": null,
        "_source": {
          "id": "92810080-9c5a-470f-a0ff-0eb85e7b818c",
          "name": "baseline",
          "description": "Current production algorithm",
          "timestamp": "2025-06-12T08:23:03.305Z",
          "index": "ecommerce",
          "query": """{"query":{"multi_match":{"query":"%SearchText%","fields":["id","title","category","bullets","description","attrs.Brand","attrs.Color"]}}}""",
          "searchPipeline": ""
        },
        "sort": [
          1749716583305
        ]
      }
    ]
  }
}

Path parameters

The following table lists the available path parameters.

Parameter Data type Description
search_configuration_id String The ID of the search configuration to retrieve. Retrieves all search configurations when empty.

Delete a search configuration

You can delete a search configuration using the search configuration ID.

Endpoint

DELETE _plugins/_search_relevance/search_configurations/{search_configuration_id}

Example request

DELETE _plugins/_search_relevance/search_configurations/bb45c4c4-48ce-461b-acbc-f154c0a17ec9

Example response

{
  "_index": "search-relevance-search-config",
  "_id": "92810080-9c5a-470f-a0ff-0eb85e7b818c",
  "_version": 2,
  "result": "deleted",
  "forced_refresh": true,
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 9,
  "_primary_term": 1
}

Search for a search configuration

You can search for available search configurations using query DSL.

Endpoint

GET _plugins/_search_relevance/search_configurations/_search
POST _plugins/_search_relevance/search_configurations/_search

Example request: Searching for all search configurations

GET _plugins/_search_relevance/search_configurations/_search
{
  "query":
  {
    "match_all": {}
  }
}

Example request: Searching for a search configuration by name

GET _plugins/_search_relevance/search_configurations/_search
{
  "query": {
    "match": {
      "name": "baseline"
    }
  }
}

Note that the index storing the search configurations contains several fields of the type keyword that require exact matching.

Example request: Searching for a search configuration using multiple criteria

Search for a search configuration by a specific target index and query pattern:

GET _plugins/_search_relevance/search_configurations/_search
{
  "query": {
    "bool": {
      "must": [
        {
          "term": {
            "index": "ecommerce"
          }
        },
        {
          "match": {
            "query": "multi_match"
          }
        }
      ]
    }
  },
  "size": 10
}

Example response

{
  "took": 1,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": 1.2086178,
    "hits": [
      {
        "_index": "search-relevance-search-config",
        "_id": "c86af6ed-a91e-450d-a630-aa2a3c525618",
        "_score": 1.2086178,
        "_source": {
          "id": "c86af6ed-a91e-450d-a630-aa2a3c525618",
          "name": "baseline",
          "description": "Current production algorithm",
          "timestamp": "2026-01-26T12:11:47.657Z",
          "index": "ecommerce",
          "query": """{"query":{"multi_match":{"query":"%SearchText%","fields":["asin","title","category","bullet_points","description","brand","color"]}}}""",
          "searchPipeline": ""
        }
      },
      {
        "_index": "search-relevance-search-config",
        "_id": "a4697191-744e-404a-b869-bbefb7e753ed",
        "_score": 1.2015147,
        "_source": {
          "id": "a4697191-744e-404a-b869-bbefb7e753ed",
          "name": "baseline with title weight",
          "timestamp": "2026-01-26T12:11:48.199Z",
          "index": "ecommerce",
          "query": """{"query":{"multi_match":{"query":"%SearchText%","fields":["asin","title^25","category","bullet_points","description","brand","color"]}}}""",
          "searchPipeline": ""
        }
      }
    ]
  }
}
350 characters left

Have a question? .

Want to contribute? or .