IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Documents API Engines API »
Elastic Docs › ›API Reference

Elasticsearch search API for App Search

edit

Elasticsearch search API for App Search

edit

A valid App Search authentication header is required to access this endpoint, and the authenticated entity must have read access to the underlying index.

This feature is turned on by default but can be disabled in the configuration settings:

feature_flag.elasticsearch_search_api: false

or in an environment variable:

ELASTICSEARCH_SEARCH_API=false

By default, the API is enabled.

This feature flag setting existed primarily to enable or disable this feature while it was in a beta evaluation period. The feature is now intended to be always available. The setting to disable this feature will be removed in version 8.7.

Submit an Elasticsearch search request to the document indices that power an App Search engine and retrieve the results.

You can use this API with regular engines and meta engines.

GET <enterprise-search-base-url>/api/as/v1/engines/<engine>/elasticsearch/_search
POST <enterprise-search-base-url>/api/as/v1/engines/<engine>/elasticsearch/_search

Path parameters

edit
enterprise-search-base-url (required)
The Enterprise Search base URL for the deployment.
engine (required)
The engine name.

Request body

edit

The body of the request contains the Elasticsearch query. The query can be written using the Elasticsearch Query DSL.

Query string parameters

edit

Any parameters (key=value) included in the query string will be passed unmodified to Elasticsearch.

Analytics parameters

edit

Analytics parameters can be specified using optional request headers.

X-Enterprise-Search-Analytics

Specify the search query associated with this request when recording search analytics.

X-Enterprise-Search-Analytics-Tags

See Search API analytics tags.

Query analytics are recorded only if the X-Enterprise-Search-Analytics header is specified.

Response body

edit

Response is returned directly from Elasticsearch and depends on the provided request and its parameters. Unlike the Search endpoint, this endpoint does not do any parsing or formatting of the Elasticsearch response, it simply passes the response back as-is.

Examples

edit

Retrieve all documents for a given engine:

curl --request "POST" \
--url "${ENTERPRISE_SEARCH_BASE_URL}/api/as/v1/engines/national-parks-demo/elasticsearch/_search" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer private-xxxxxx" \
--data '{"query": {"match_all": {}}}'

Response (10 documents are returned, but only 1 is shown here):

{
  "took": 2,
  "timed_out": false,
  "_shards": {
    "total": 2,
    "successful": 2,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 59,
      "relation": "eq"
    },
    "max_score": 1.0,
    "hits": [
      {
        "_index": ".ent-search-engine-documents-national-parks-demo",
        "_id": "park_acadia",
        "_score": 1.0,
        "_ignored": [
          "description.date",
          "title.float",
          "date_established.location",
          "acres.location",
          "nps_link.date",
          "world_heritage_site.float",
          "acres.date",
          "states.float",
          "title.location",
          "states.location",
          "visitors.date",
          "location.float",
          "world_heritage_site.date",
          "description.float",
          "description.location",
          "nps_link.float",
          "square_km.location",
          "title.date",
          "location.date",
          "nps_link.location",
          "world_heritage_site.location",
          "states.date",
          "square_km.date",
          "date_established.float"
        ],
        "_source": {
          "description": "Covering most of Mount Desert Island and other coastal islands, Acadia features the tallest mountain on the Atlantic coast of the United States, granite peaks, ocean shoreline, woodlands, and lakes. There are freshwater, estuary, forest, and intertidal habitats.",
          "nps_link": "https://www.nps.gov/acad/index.htm",
          "states": [
            "Maine"
          ],
          "title": "Acadia",
          "visitors": "3303393",
          "world_heritage_site": "false",
          "location": "44.35,-68.21",
          "acres": "49057.36",
          "square_km": "198.5",
          "date_established": "1919-02-26T06:00:00Z",
          "id": "park_acadia"
        }
      }
    ]
  }
}

By default, Elasticsearch returns 10 documents, unless the size parameter is specified. Example request with size:

curl --request "POST" \
--url "${ENTERPRISE_SEARCH_BASE_URL}/api/as/v1/engines/national-parks-demo/elasticsearch/_search?size=1" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer private-xxxxxx" \
--data '{"query": {"match_all": {}}}'

Response:

{
  "took": 0,
  "timed_out": false,
  "_shards": {
    "total": 2,
    "successful": 2,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 59,
      "relation": "eq"
    },
    "max_score": 1.0,
    "hits": [
      {
        "_index": ".ent-search-engine-documents-national-parks-demo",
        "_id": "park_acadia",
        "_score": 1.0,
        "_ignored": [
          "description.date",
          "title.float",
          "date_established.location",
          "acres.location",
          "nps_link.date",
          "world_heritage_site.float",
          "acres.date",
          "states.float",
          "title.location",
          "states.location",
          "visitors.date",
          "location.float",
          "world_heritage_site.date",
          "description.float",
          "description.location",
          "nps_link.float",
          "square_km.location",
          "title.date",
          "location.date",
          "nps_link.location",
          "world_heritage_site.location",
          "states.date",
          "square_km.date",
          "date_established.float"
        ],
        "_source": {
          "description": "Covering most of Mount Desert Island and other coastal islands, Acadia features the tallest mountain on the Atlantic coast of the United States, granite peaks, ocean shoreline, woodlands, and lakes. There are freshwater, estuary, forest, and intertidal habitats.",
          "nps_link": "https://www.nps.gov/acad/index.htm",
          "states": [
            "Maine"
          ],
          "title": "Acadia",
          "visitors": "3303393",
          "world_heritage_site": "false",
          "location": "44.35,-68.21",
          "acres": "49057.36",
          "square_km": "198.5",
          "date_established": "1919-02-26T06:00:00Z",
          "id": "park_acadia"
        }
      }
    ]
  }
}

For more guidance and examples, please see the Elasticsearch search guide.

Limitations

edit

This API only exposes the Elasticsearch Search API. It’s currently not possible to access other Elasticsearch search APIs, such as Multi search API, Scroll API, Async search API, etc.

See also

edit

You can see exactly how App Search searches for the documents if you use the related Search Explain API endpoint. That endpoint will build and return an Elasticsearch search query being used by App Search. The query can be used as a starting point to create your own queries.

More examples are available in the Elasticsearch search guide.

« Documents API Engines API »