ℹ️ For new users, we recommend using our native Elasticsearch tools, rather than the standalone App Search product. We are actively developing new features and capabilities in the Elastic Stack to help you build powerful search applications. Refer to this blog for more information.

« Search API analytics tags Search Explain API »

› ›

Search settings API

edit

IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Search settings API

edit

Use the search settings API to set engine defaults for the following search API request parameters:

Each query sent to an engine will use these default parameters, unless they are overridden directly within the query.

The changes you make to result_fields through this API will affect those shown within the Result Settings UI.

Requires a Private API Key.

Show search settings

edit

Show the search settings for a given engine.

GET <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/{ENGINE_NAME}/search_settings

Example - A GET request to national-parks-demo:

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/search_settings' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx'

Example response:

{
  "search_fields": {
    "description": {
      "weight": 1
    },
    "nps_link": {
      "weight": 1
    },
    "states": {
      "weight": 1
    },
    "title": {
      "weight": 3
    },
    "world_heritage_site": {
      "weight": 1
    },
    "id": {
      "weight": 1
    }
  },
  "result_fields": {
    "id": {
      "raw": {}
    },
    "description": {
      "raw": {}
    },
    "nps_link": {
      "raw": {}
    },
    "states": {
      "raw": {}
    },
    "title": {
      "raw": {}
    },
    "visitors": {
      "raw": {}
    },
    "world_heritage_site": {
      "raw": {}
    },
    "location": {
      "raw": {}
    },
    "acres": {
      "raw": {}
    },
    "square_km": {
      "raw": {}
    },
    "date_established": {
      "raw": {}
    }
  },
  "boosts": {},
  "precision": 2,
  "precision_enabled": true
}

Update search settings

edit

Update the search settings for a given engine.

The precision_enabled field is read-only. It tells you whether it is possible to change the precision setting. If you try to change the precision_enabled field, or the precision setting when precision_enabled is false for an engine, you will receive an error.

To understand how to enable precision tuning with an Elasticsearch based engine, check Elasticsearch engines text field conventions.

Removing fields from result_fields means that those fields are not returned in results.

PUT <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/{ENGINE_NAME}/search_settings

Example - A PUT request to national-parks-demo. This example selects which fields to search, calibrates field weights, boosts specific field values, and tunes precision. Responses for this example return only the "title", "description", and "states" fields, with snippets.

curl -X PUT '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/search_settings' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx' \
-d '{
  "search_fields": {
    "description": {
      "weight": 9.2
    },
    "nps_link": {
      "weight": 1
    },
    "states": {
      "weight": 3
    },
    "title": {
      "weight": 1
    },
    "world_heritage_site": {
      "weight": 1
    },
    "id": {
      "weight": 1
    }
  },
  "result_fields": {
    "title": {
      "snippet": {
        "size": 20,
        "fallback": true
      }
    },
    "description": {
      "raw": {
        "size": 200
      },
      "snippet": {
        "size": 100
      }
    },
    "states": {
      "raw" : {},
      "snippet": {
        "size": 20,
        "fallback": true
      }
    }
  },
  "boosts": {
    "world_heritage_site": [
      {
        "type": "value",
        "factor": 9.5,
        "value": [
          "true"
        ]
      }
    ]
  },
  "precision": 3
}'

Example response:

{
  "search_fields": {
    "description": {
      "weight": 9.2
    },
    "nps_link": {
      "weight": 1
    },
    "states": {
      "weight": 3
    },
    "title": {
      "weight": 1
    },
    "world_heritage_site": {
      "weight": 1
    },
    "id": {
      "weight": 1
    }
  },
  "boosts": {
    "world_heritage_site": [
      {
        "type": "value",
        "factor": 9.5,
        "value": [
          "true"
        ]
      }
    ]
  },
  "precision": 3,
  "precision_enabled": true
}

Reset search settings

edit

Reset the search settings for a given engine back to the App Search default values.

Your search settings will be lost. You may want to back up your settings before resetting them.

POST <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/{ENGINE_NAME}/search_settings/reset

Example - A POST request to national-parks-demo.

curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/search_settings/reset' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxx'

Example response:

{
  "search_fields": {
    "description": {
      "weight": 1
    },
    "nps_link": {
      "weight": 1
    },
    "states": {
      "weight": 1
    },
    "title": {
      "weight": 1
    },
    "world_heritage_site": {
      "weight": 1
    },
    "id": {
      "weight": 1
    }
  },
  "boosts": {},
  "precision": 2,
  "precision_enabled": true
}

« Search API analytics tags Search Explain API »