Elasticsearch search API for App Search (technical preview) | Elastic App Search Documentation [8.3]

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 »

Elasticsearch search API for App Search (technical preview)edit

The Elasticsearch search API is a technical preview feature. Technical preview features are subject to change and are not covered by the support SLA of generally available (GA) features. Elastic plans to promote this feature to GA in a future release.

A Private API key is required to access this endpoint.

In addition, a feature flag should be set either in the configuration settings:

feature_flag.elasticsearch_search_api: true

or in an environment variable:

ELASTICSEARCH_SEARCH_API=true

By default, the API is disabled.

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/v0/engines/<engine>/elasticsearch/_search
POST <enterprise-search-base-url>/api/as/v0/engines/<engine>/elasticsearch/_search

Path parametersedit

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

Request bodyedit

Request body has the following elements:

request: This is an object that contains the following properties:
request.body: JSON query to be sent directly to Elasticsearch.
request.query_params (optional): A list of query parameters to be included in the request sent to Elasticsearch. Each parameter is an object with a key and a value.

The body contains the actual Elasticsearch query. The query can be written using any elements of the Elasticsearch Query DSL.

analytics.query (optional): Specify the search query associated with this request when recording search analytics.
analytics.tags (optional): See Search API analytics tags.

Query analytics are recorded only if something is specified in analytics params.

Response bodyedit

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.

Examplesedit

Retrieve all documents for a given engine:

curl --request "POST" \
--url "${ENTERPRISE_SEARCH_BASE_URL}/api/as/v0/engines/national-parks-demo/elasticsearch/_search" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer private-g6673wmo7529rmvk7ckry530" \
--data '{
    "request": {
      "body": {"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. We can provide the parameter in query_params. Request:

curl --request "POST" \
--url "${ENTERPRISE_SEARCH_BASE_URL}/api/as/v0/engines/national-parks-demo/elasticsearch/_search" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer private-g6673wmo7529rmvk7ckry530" \
--data '{
    "request": {
      "body": {"query": {"match_all": {}}},
      "query_params": [
        {"key": "size", "value": "1"}
      ]
    }
}'

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.

Limitationsedit

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.