Search Explain API

edit

Search Explain API

edit

A Private API key is required to access this endpoint.

Submit a search and receive an Elasticsearch query built by App Search. You can submit the query directly to Elasticsearch to retrieve the search results.

This API can be used with regular engines and meta-engines.

GET /api/as/v1/engines/<engine_name>/search_explain
POST /api/as/v1/engines/<engine_name>/search_explain

Request body

edit

Request body is exactly the same as the one in Search API: Request body.

Response body

edit
query_string

Query string to be used as part of request to Elasticsearch.

query_body

JSON query to be used as part of request to Elasticsearch.

meta

Object delimiting the results meta data.

meta.request_id

String ID representing the request. Guaranteed to be unique.

Use the ID with the API logs API to search for API requests.

meta.warnings

Array of warnings for the query.

Included with error responses and success responses, so inspect all responses for warnings.

meta.alerts

Array of alerts for your deployment.

Included with error responses and success responses, so inspect all responses for alerts.

meta.precision
Precision tuning value App Search used when constructing the query.
meta.engine
The App Search engine specified in the original query.

Examples

edit

Request:

curl -X POST 'https://[instance id].ent.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/search_explain' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-g6673wmo7529rmvk7ckry530' \
-d '{
  "query": "everglade"
}'

Response:

{
  "meta": {
    "alerts": [],
    "warnings": [],
    "precision": 2,
    "engine": {
      "name": "national-parks-demo",
      "type": "default"
    },
    "request_id": "2dea3062-4a90-491d-bd54-5e10b588f015"
  },
  "query_string": "GET enterprise-search-engine-national-parks-demo/_search",
  "query_body": {
    "query": {
      "bool": {
        "must": {
          "function_score": {
            "boost_mode": "sum",
            "score_mode": "sum",
            "query": {
              "bool": {
                "must": [
                  {
                    "bool": {
                      "should": [
                        {
                          "multi_match": {
                            "query": "everglade",
                            "minimum_should_match": "1<-1 3<49%",
                            "type": "cross_fields",
                            "fields": [
                              "world_heritage_site^1.0",
                              "world_heritage_site.stem^0.95",
                              "world_heritage_site.prefix^0.1",
                              "world_heritage_site.joined^0.75",
                              "world_heritage_site.delimiter^0.4",
                              "description^2.4",
                              "description.stem^2.28",
                              "description.prefix^0.24",
                              "description.joined^1.8",
                              "description.delimiter^0.96",
                              "title^5.0",
                              "title.stem^4.75",
                              "title.prefix^0.5",
                              "title.joined^3.75",
                              "title.delimiter^2.0",
                              "nps_link^0.7",
                              "nps_link.stem^0.665",
                              "nps_link.prefix^0.07",
                              "nps_link.joined^0.525",
                              "nps_link.delimiter^0.28",
                              "states^2.8",
                              "states.stem^2.66",
                              "states.prefix^0.28",
                              "states.joined^2.1",
                              "states.delimiter^1.12",
                              "id^1.0"
                            ]
                          }
                        },
                        {
                          "multi_match": {
                            "query": "everglade",
                            "minimum_should_match": "1<-1 3<49%",
                            "type": "best_fields",
                            "fuzziness": "AUTO",
                            "prefix_length": 2,
                            "fields": [
                              "world_heritage_site.stem^0.1",
                              "description.stem^0.24",
                              "title.stem^0.5",
                              "nps_link.stem^0.07",
                              "states.stem^0.28"
                            ]
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            },
            "functions": [
              {
                "script_score": {
                  "script": {
                    "source": "Math.max(_score + ((1.5 * (doc.containsKey(\"visitors.float\") && !doc[\"visitors.float\"].empty ? doc[\"visitors.float\"].value : 0))) - _score, 0)"
                  }
                }
              }
            ]
          }
        }
      }
    },
    "sort": [
      {
        "_score": "desc"
      },
      {
        "_doc": "desc"
      }
    ],
    "highlight": {
      "fragment_size": 300,
      "type": "plain",
      "number_of_fragments": 1,
      "order": "score",
      "encoder": "html",
      "require_field_match": false,
      "fields": {}
    },
    "size": 10,
    "from": 0,
    "timeout": "30000ms",
    "_source": [
      "visitors",
      "square_km",
      "world_heritage_site",
      "date_established",
      "description",
      "location",
      "id",
      "acres",
      "title",
      "nps_link",
      "states"
    ]
  }
}

Request using Lucene query syntax within the query:

curl -X POST 'https://[instance id].ent.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/search_explain' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-g6673wmo7529rmvk7ckry530' \
-d '{
  "query": "wyoming AND montana"
}'

Response:

{
  "meta": {
    "alerts": [],
    "warnings": [],
    "precision": 2,
    "engine": {
      "name": "national-parks-demo",
      "type": "default"
    },
    "request_id": "7f3682fe-18f3-4703-b2e7-d49645472c22"
  },
  "query_string": "GET enterprise-search-engine-national-parks-demo/_search",
  "query_body": {
    "query": {
      "bool": {
        "must": {
          "function_score": {
            "boost_mode": "sum",
            "score_mode": "sum",
            "query": {
              "bool": {
                "must": [
                  {
                    "bool": {
                      "should": [
                        {
                          "query_string": {
                            "query": "wyoming AND montana",
                            "fields": [
                              "world_heritage_site.stem^0.95",
                              "description.stem^2.28",
                              "title.stem^4.75",
                              "nps_link.stem^0.665",
                              "states.stem^2.66",
                              "id^1.0"
                            ],
                            "minimum_should_match": "1<-1 3<49%",
                            "phrase_slop": 2
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            },
            "functions": [
              {
                "script_score": {
                  "script": {
                    "source": "Math.max(_score + ((1.5 * (doc.containsKey(\"visitors.float\") && !doc[\"visitors.float\"].empty ? doc[\"visitors.float\"].value : 0))) - _score, 0)"
                  }
                }
              }
            ]
          }
        }
      }
    },
    "sort": [
      {
        "_score": "desc"
      },
      {
        "_doc": "desc"
      }
    ],
    "highlight": {
      "fragment_size": 300,
      "type": "plain",
      "number_of_fragments": 1,
      "order": "score",
      "encoder": "html",
      "require_field_match": false,
      "fields": {}
    },
    "size": 10,
    "from": 0,
    "timeout": "30000ms",
    "_source": [
      "visitors",
      "square_km",
      "world_heritage_site",
      "date_established",
      "description",
      "location",
      "id",
      "acres",
      "title",
      "nps_link",
      "states"
    ]
  }
}