IMPORTANT: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
current release documentation.
Elasticsearch search for App Search Guide
editElasticsearch search for App Search Guide
editApp Search has two APIs designed for search. With Search API the user sends a query and retrieves a list of matching documents. See our Search guide for more details.
However, more advanced Elasticsearch users might need additional functionality. We created the Elasticsearch search API (beta) for these advanced use cases. While the App Search Search API uses its own domain-specific language (DSL), the Elasticsearch search API uses the Elasticsearch Query DSL, and accepts queries built for Elasticsearch.
This guide provides practical examples and explains how this API can supplement the Search API. This will give you a deeper understanding of App Search, Elasticsearch, and how they work together.
Who is this API for?
editWe designed this API for:
- Users with more complex use cases than the App Search Search API can manage. These users feel they can improve and customize their searches themselves, and don’t want to wait to submit a feature request.
- Users who feel their data can be indexed more efficiently. They want to pick and choose which fields are indexed and which ones are calculated at runtime, with the help of runtime fields.
- Users who already have, or want to gain more knowledge about querying Elasticsearch.
In other words:
- If you are happy with App Search out of the box, you might not need this additional functionality.
- If you don’t know anything about querying Elasticsearch, and would rather keep it that way, you won’t need this API.
Are you still with us? Then please read on!
Why would I use it?
edit- To supplement the current Search API.
- To experiment and explore different ways of presenting data.
- Or even to replace the current Search API.
We think that the current Search API is great, but it can be extended with Elasticsearch Search API, and the best part is, you can extend it yourself.
Example use cases
editWe’re going to explore several use cases:
- Aggregate the documents that match your query, without retrieving them
- Add a runtime field to your document and return it in your search
- Search for documents that are like a specific document in the same index
- Use a custom function to calculate document scores
- Retrieve a subset of documents without applying any scoring or grouping
Let’s do something with this API that you can’t currently do with the Search API.
Aggregate the documents that match your query, without retrieving them
editIn some cases, you might want to retrieve statistics (aggregated data) about documents, without the overhead of actually retrieving them.
This can be solved by building a query body with aggs.
The following query returns counts of documents grouped by state:
curl --request "POST" \
--url "${ENTERPRISE_SEARCH_BASE_URL}/api/as/v0/engines/national-parks-demo/elasticsearch/_search?size=0" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer private-xxxxxx" \
--data '{"aggs": {"states": {"terms": {"field": "states.enum", "size": 100}}}}'
Response:
{
"took": 7,
"timed_out": false,
"_shards": {
"total": 2,
"successful": 2,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 59,
"relation": "eq"
},
"max_score": null,
"hits": []
},
"aggregations": {
"states": {
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0,
"buckets": [
{
"key": "California",
"doc_count": 9
},
{
"key": "Alaska",
"doc_count": 8
},
{
"key": "Utah",
"doc_count": 5
},
{
"key": "Colorado",
"doc_count": 4
},
{
"key": "Arizona",
"doc_count": 3
},
{
"key": "Florida",
"doc_count": 3
},
{
"key": "Washington",
"doc_count": 3
},
{
"key": "Hawaii",
"doc_count": 2
},
{
"key": "Montana",
"doc_count": 2
},
{
"key": "Nevada",
"doc_count": 2
},
{
"key": "South Dakota",
"doc_count": 2
},
{
"key": "Texas",
"doc_count": 2
},
{
"key": "Wyoming",
"doc_count": 2
},
{
"key": "American Samoa",
"doc_count": 1
},
{
"key": "Arkansas",
"doc_count": 1
},
{
"key": "Idaho",
"doc_count": 1
},
{
"key": "Kentucky",
"doc_count": 1
},
{
"key": "Maine",
"doc_count": 1
},
{
"key": "Michigan",
"doc_count": 1
},
{
"key": "Minnesota",
"doc_count": 1
},
{
"key": "New Mexico",
"doc_count": 1
},
{
"key": "North Carolina",
"doc_count": 1
},
{
"key": "North Dakota",
"doc_count": 1
},
{
"key": "Ohio",
"doc_count": 1
},
{
"key": "Oregon",
"doc_count": 1
},
{
"key": "South Carolina",
"doc_count": 1
},
{
"key": "Tennessee",
"doc_count": 1
},
{
"key": "US Virgin Islands",
"doc_count": 1
},
{
"key": "Virginia",
"doc_count": 1
}
]
}
}
}
Notice that the above example aggregates on states.enum, because states is a text field which does not support aggregations. By default, all properties on an App Search document use multi-fields to index the data for multiple use cases. Fields with a .enum suffix are mapped to the Elasticsearch keyword data type.
App Search typically simplifies the user experience by abstracting away the underlying details of a search request. However, this API empowers the user by providing direct access to Elasticsearch.
Add a runtime field to your document and return it in your search
editWhat if you want to add a runtime field to your data? The API makes it possible. The following query adds a runtime field called miles_to_sfo to all documents in the result set:
curl --request POST \
--url "${ENTERPRISE_SEARCH_BASE_URL}/api/as/v0/engines/national-parks-demo/elasticsearch/_search?size=3" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer private-xxxxxx" \
--data '{
"runtime_mappings": {
"miles_to_sfo": {
"type": "double",
"script": {
"source": "emit(0.00062137 * doc[\"location.location\"].planeDistance(37.62126189231072, -122.3790626898805))"
}
}
},
"fields": [
"miles_to_sfo"
]
}'
Response:
{
"took": 3,
"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"
},
"fields": {
"miles_to_sfo": [
2863.2771722448347
]
}
},
{
"_index": ".ent-search-engine-documents-national-parks-demo",
"_id": "park_badlands",
"_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": "The Badlands are a collection of buttes, pinnacles, spires, and mixed-grass prairies. The White River Badlands contain the largest assemblage of known late Eocene and Oligocene mammal fossils. The wildlife includes bison, bighorn sheep, black-footed ferrets, and prairie dogs.",
"nps_link": "https://www.nps.gov/badl/index.htm",
"states": [
"South Dakota"
],
"title": "Badlands",
"visitors": "996263",
"world_heritage_site": "false",
"location": "43.75,-102.5",
"acres": "242755.94",
"square_km": "982.4",
"date_established": "1978-11-10T06:00:00Z",
"id": "park_badlands"
},
"fields": {
"miles_to_sfo": [
1124.3209377048445
]
}
},
{
"_index": ".ent-search-engine-documents-national-parks-demo",
"_id": "park_big-bend",
"_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": "Named for the prominent bend in the Rio Grande along the U.S.–Mexico border, this park encompasses a large and remote part of the Chihuahuan Desert. Its main attraction is backcountry recreation in the arid Chisos Mountains and in canyons along the river. A wide variety of Cretaceous and Tertiary fossils as well as cultural artifacts of Native Americans also exist within its borders.",
"nps_link": "https://www.nps.gov/bibe/index.htm",
"states": [
"Texas"
],
"title": "Big Bend",
"visitors": "388290",
"world_heritage_site": "false",
"location": "29.25,-103.25",
"acres": "801163.21",
"square_km": "3242.2",
"date_established": "1944-06-12T05:00:00Z",
"id": "park_big-bend"
},
"fields": {
"miles_to_sfo": [
1245.415162914423
]
}
}
]
}
}
Note that runtime fields are not great for performance reasons, but they are still an excellent way to explore and experiment with your data when developing and finalizing the mappings.
Search for documents that are like a specific document in the same index
editFor this, use the Elasticsearch’s more_like_this (MLT) query. Example:
curl --request POST \
--url "${ENTERPRISE_SEARCH_BASE_URL}/api/as/v0/engines/national-parks-demo/elasticsearch/_search?size=3" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer private-xxxxxx" \
--data '{
"query": {
"more_like_this": {
"fields": [
"title",
"description"
],
"like": [
{
"_id": "park_sequoia"
}
],
"min_term_freq": 1,
"max_query_terms": 12
}
}
}'
Response:
{
"took": 9,
"timed_out": false,
"_shards": {
"total": 2,
"successful": 2,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 24,
"relation": "eq"
},
"max_score": 8.750309,
"hits": [
{
"_index": ".ent-search-engine-documents-national-parks-demo",
"_id": "park_lassen-volcanic",
"_score": 8.750309,
"_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": "Lassen Peak, the largest plug dome volcano in the world, is joined by all three other types of volcanoes in this park: shield, cinder dome, and composite. Though Lassen itself last erupted in 1915, most of the rest of the park is continuously active. Numerous hydrothermal features, including fumaroles, boiling pools, and bubbling mud pots, are heated by molten rock from beneath the peak.",
"nps_link": "https://www.nps.gov/lavo/index.htm",
"states": [
"California"
],
"title": "Lassen Volcanic",
"visitors": "536068",
"world_heritage_site": "false",
"location": "40.49,-121.51",
"acres": "106589.02",
"square_km": "431.4",
"date_established": "1916-08-09T05:00:00Z",
"id": "park_lassen-volcanic"
}
},
{
"_index": ".ent-search-engine-documents-national-parks-demo",
"_id": "park_acadia",
"_score": 8.54769,
"_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"
}
},
{
"_index": ".ent-search-engine-documents-national-parks-demo",
"_id": "park_mount-rainier",
"_score": 8.32178,
"_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": "Mount Rainier, an active stratovolcano, is the most prominent peak in the Cascades and is covered by 26 named glaciers including Carbon Glacier and Emmons Glacier, the largest in the contiguous United States. The mountain is popular for climbing, and more than half of the park is covered by subalpine and alpine forests and meadows seasonally in bloom with wildflowers. Paradise on the south slope is the snowiest place on Earth where snowfall is measured regularly. The Longmire visitor center is the start of the Wonderland Trail, which encircles the mountain.",
"nps_link": "https://www.nps.gov/mora/index.htm",
"states": [
"Washington"
],
"title": "Mount Rainier",
"visitors": "1356913",
"world_heritage_site": "false",
"location": "46.85,-121.75",
"acres": "236381.64",
"square_km": "956.6",
"date_established": "1899-03-02T06:00:00Z",
"id": "park_mount-rainier"
}
}
]
}
}
Use a custom function to calculate document scores
editThe following query calculates document scores as a function of park square footage and number of visitors:
curl --request POST \
--url "${ENTERPRISE_SEARCH_BASE_URL}/api/as/v0/engines/national-parks-demo/elasticsearch/_search?size=3" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer private-xxxxxx" \
--data '{
"query": {
"function_score": {
"script_score": {
"script": {
"source": "Math.log(doc['acres.float'].value * doc['acres.float'].value)"
}
}
}
}
}'
Response:
{
"took": 30,
"timed_out": false,
"_shards": {
"total": 2,
"successful": 2,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 59,
"relation": "eq"
},
"max_score": 31.869102,
"hits": [
{
"_index": ".ent-search-engine-documents-national-parks-demo",
"_id": "park_wrangell–st.-elias",
"_score": 31.869102,
"_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",
"states.date",
"square_km.date",
"date_established.float"
],
"_source": {
"description": "An over 8 million acres (32,375 km2) plot of mountainous country—the largest National Park in the system—protects the convergence of the Alaska, Chugach, and Wrangell-Saint Elias Ranges, which include many of the continent's tallest mountains and volcanoes, including the 18,008-foot Mount Saint Elias. More than a quarter of the park is covered with glaciers, including the tidewater Hubbard Glacier, piedmont Malaspina Glacier, and valley Nabesna Glacier.",
"nps_link": "https://www.nps.gov/wrst/index.htm",
"states": [
"Alaska"
],
"title": "Wrangell–St. Elias",
"visitors": "79047",
"world_heritage_site": "true",
"location": "61,-142",
"acres": "8323146.48",
"square_km": "33682.6",
"date_established": "1980-12-02T06:00:00Z",
"id": "park_wrangell–st.-elias"
}
},
{
"_index": ".ent-search-engine-documents-national-parks-demo",
"_id": "park_gates-of-the-arctic",
"_score": 31.66719,
"_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": "The country's northernmost park protects an expanse of pure wilderness in Alaska's Brooks Range and has no park facilities. The land is home to Alaska Natives who have relied on the land and caribou for 11,000 years.",
"nps_link": "https://www.nps.gov/gaar/index.htm",
"states": [
"Alaska"
],
"title": "Gates of the Arctic",
"visitors": "10047",
"world_heritage_site": "false",
"location": "67.78,-153.3",
"acres": "7523897.45",
"square_km": "30448.1",
"date_established": "1980-12-02T06:00:00Z",
"id": "park_gates-of-the-arctic"
}
},
{
"_index": ".ent-search-engine-documents-national-parks-demo",
"_id": "park_denali",
"_score": 30.74348,
"_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": "Centered on Denali, the tallest mountain in North America, Denali is serviced by a single road leading to Wonder Lake. Denali and other peaks of the Alaska Range are covered with long glaciers and boreal forest. Wildlife includes grizzly bears, Dall sheep, caribou, and gray wolves.",
"nps_link": "https://www.nps.gov/dena/index.htm",
"states": [
"Alaska"
],
"title": "Denali",
"visitors": "587412",
"world_heritage_site": "false",
"location": "63.33,-150.5",
"acres": "4740911.16",
"square_km": "19185.8",
"date_established": "1917-02-26T06:00:00Z",
"id": "park_denali"
}
}
]
}
}
Retrieve a subset of documents without applying any scoring or grouping
editSometimes, scoring and / or grouping is not useful, and it does create an overhead for Elasticsearch, which can affect performance. To avoid that, use filters.
The following query selects all national parks in California within 300 miles of San Francisco International airport:
curl --request POST \
--url "${ENTERPRISE_SEARCH_BASE_URL}/api/as/v0/engines/national-parks-demo/elasticsearch/_search?size=3" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer private-xxxxxx" \
--data '{
"query": {
"bool": {
"filter": [
{
"geo_distance": {
"distance": "300mi",
"location.location": {
"lat": 37.62126189231072,
"lon": -122.3790626898805
}
}
},
{
"term": {
"states.enum": "California"
}
}
]
}
}
}'
Response:
{
"took": 53,
"timed_out": false,
"_shards": {
"total": 2,
"successful": 2,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 7,
"relation": "eq"
},
"max_score": 0.0,
"hits": [
{
"_index": ".ent-search-engine-documents-national-parks-demo",
"_id": "park_kings-canyon",
"_score": 0.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": "Home to several giant sequoia groves and the General Grant Tree, the world's second largest measured tree, this park also features part of the Kings River, sculptor of the dramatic granite canyon that is its namesake, and the San Joaquin River, as well as Boyden Cave.",
"nps_link": "https://www.nps.gov/seki/index.htm",
"states": [
"California"
],
"title": "Kings Canyon",
"visitors": "607479",
"world_heritage_site": "false",
"location": "36.8,-118.55",
"acres": "461901.2",
"square_km": "1869.2",
"date_established": "1940-03-04T06:00:00Z",
"id": "park_kings-canyon"
}
},
{
"_index": ".ent-search-engine-documents-national-parks-demo",
"_id": "park_pinnacles",
"_score": 0.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": "Named for the eroded leftovers of a portion of an extinct volcano, the park's massive black and gold monoliths of andesite and rhyolite are a popular destination for rock climbers. Hikers have access to trails crossing the Coast Range wilderness. The park is home to the endangered California condor (Gymnogyps californianus) and one of the few locations in the world where these extremely rare birds can be seen in the wild. Pinnacles also supports a dense population of prairie falcons, and more than 13 species of bat which populate its talus caves.",
"nps_link": "https://www.nps.gov/pinn/index.htm",
"states": [
"California"
],
"title": "Pinnacles",
"visitors": "215555",
"world_heritage_site": "false",
"location": "36.48,-121.16",
"acres": "26685.73",
"square_km": "108.0",
"date_established": "2013-01-10T06:00:00Z",
"id": "park_pinnacles"
}
},
{
"_index": ".ent-search-engine-documents-national-parks-demo",
"_id": "park_channel-islands",
"_score": 0.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": "Five of the eight Channel Islands are protected, and half of the park's area is underwater. The islands have a unique Mediterranean ecosystem originally settled by the Chumash people. They are home to over 2,000 species of land plants and animals, and 145 are unique to them, including the island fox. Ferry services offer transportation to the islands from the mainland.",
"nps_link": "https://www.nps.gov/chis/index.htm",
"states": [
"California"
],
"title": "Channel Islands",
"visitors": "364807",
"world_heritage_site": "false",
"location": "34.01,-119.42",
"acres": "249561.0",
"square_km": "1009.9",
"date_established": "1980-03-05T06:00:00Z",
"id": "park_channel-islands"
}
},
{
"_index": ".ent-search-engine-documents-national-parks-demo",
"_id": "park_lassen-volcanic",
"_score": 0.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": "Lassen Peak, the largest plug dome volcano in the world, is joined by all three other types of volcanoes in this park: shield, cinder dome, and composite. Though Lassen itself last erupted in 1915, most of the rest of the park is continuously active. Numerous hydrothermal features, including fumaroles, boiling pools, and bubbling mud pots, are heated by molten rock from beneath the peak.",
"nps_link": "https://www.nps.gov/lavo/index.htm",
"states": [
"California"
],
"title": "Lassen Volcanic",
"visitors": "536068",
"world_heritage_site": "false",
"location": "40.49,-121.51",
"acres": "106589.02",
"square_km": "431.4",
"date_established": "1916-08-09T05:00:00Z",
"id": "park_lassen-volcanic"
}
},
{
"_index": ".ent-search-engine-documents-national-parks-demo",
"_id": "park_redwood",
"_score": 0.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",
"states.date",
"square_km.date",
"date_established.float"
],
"_source": {
"description": "This park and the co-managed state parks protect almost half of all remaining coastal redwoods, the tallest trees on earth. There are three large river systems in this very seismically active area, and 37 miles (60 km) of protected coastline reveal tide pools and seastacks. The prairie, estuary, coast, river, and forest ecosystems contain a wide variety of animal and plant species.",
"nps_link": "https://www.nps.gov/redw/index.htm",
"states": [
"California"
],
"title": "Redwood",
"visitors": "536297",
"world_heritage_site": "true",
"location": "41.3,-124",
"acres": "138999.37",
"square_km": "562.5",
"date_established": "1968-10-02T05:00:00Z",
"id": "park_redwood"
}
},
{
"_index": ".ent-search-engine-documents-national-parks-demo",
"_id": "park_sequoia",
"_score": 0.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": "This park protects the Giant Forest, which boasts some of the world's largest trees, the General Sherman being the largest measured tree in the park. Other features include over 240 caves, a long segment of the Sierra Nevada including the tallest mountain in the contiguous United States, and Moro Rock, a large granite dome.",
"nps_link": "https://www.nps.gov/seki/index.htm",
"states": [
"California"
],
"title": "Sequoia",
"visitors": "1254688",
"world_heritage_site": "false",
"location": "36.43,-118.68",
"acres": "404062.63",
"square_km": "1635.2",
"date_established": "1890-09-25T05:00:00Z",
"id": "park_sequoia"
}
},
{
"_index": ".ent-search-engine-documents-national-parks-demo",
"_id": "park_yosemite",
"_score": 0.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",
"states.date",
"square_km.date",
"date_established.float"
],
"_source": {
"description": "Yosemite features sheer granite cliffs, exceptionally tall waterfalls, and old-growth forests at a unique intersection of geology and hydrology. Half Dome and El Capitan rise from the park's centerpiece, the glacier-carved Yosemite Valley, and from its vertical walls drop Yosemite Falls, one of North America's tallest waterfalls at 2,425 feet (739 m) high. Three giant sequoia groves, along with a pristine wilderness in the heart of the Sierra Nevada, are home to a wide variety of rare plant and animal species.",
"nps_link": "https://www.nps.gov/yose/index.htm",
"states": [
"California"
],
"title": "Yosemite",
"visitors": "5028868",
"world_heritage_site": "true",
"location": "37.83,-119.5",
"acres": "761747.5",
"square_km": "3082.7",
"date_established": "1890-10-01T05:00:00Z",
"id": "park_yosemite"
}
}
]
}
}
Filtering the Elasticsearch response
editYou might have noticed that every item in response includes ignored fields. You can filter those out with filter_path.
Request:
curl --request POST \
--url "${ENTERPRISE_SEARCH_BASE_URL}/api/as/v0/engines/national-parks-demo/elasticsearch/_search?size=1&filter_path=hits.hits._source,hits.hits._score,hits.hits._id,hits.hits._index" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer private-xxxxxx" \
--data '{"query": {"match_all": {}}}'
Response:
{
"hits": {
"hits": [
{
"_index": ".ent-search-engine-documents-national-parks-demo",
"_id": "park_acadia",
"_score": 1.0,
"_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"
}
}
]
}
}
Recording analytics
editTo record analytics for queries submitted to this endpoint, provide the headers X-Enterprise-Search-Analytics and X-Enterprise-Search-Analytics-Tags.
Request:
curl --request POST \
--url "${ENTERPRISE_SEARCH_BASE_URL}/api/as/v0/engines/national-parks-demo/elasticsearch/_search?size=1" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer private-xxxxxx" \
--header "X-Enterprise-Search-Analytics: mountains" \
--header "X-Enterprise-Search-Analytics-Tags: mountains" \
--data '{"query": {"multi_match": {"query": "mountains", "fields": ["title^2", "description"]}}}'
Response:
{
"took": 11,
"timed_out": false,
"_shards": {
"total": 2,
"successful": 2,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 15,
"relation": "eq"
},
"max_score": 5.4646873,
"hits": [
{
"_index": ".ent-search-engine-documents-national-parks-demo",
"_id": "park_guadalupe-mountains",
"_score": 5.4646873,
"_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": "This park contains Guadalupe Peak, the highest point in Texas, as well as the scenic McKittrick Canyon filled with bigtooth maples, a corner of the arid Chihuahuan Desert, and a fossilized coral reef from the Permian era.",
"nps_link": "https://www.nps.gov/gumo/index.htm",
"states": [
"Texas"
],
"title": "Guadalupe Mountains",
"visitors": "181839",
"world_heritage_site": "false",
"location": "31.92,-104.87",
"acres": "86367.1",
"square_km": "349.5",
"date_established": "1966-10-15T05:00:00Z",
"id": "park_guadalupe-mountains"
}
}
]
}
}
Further reading
edit- First, take a good look at Elasticsearch’s guide on searching, and the related Search API.
- Then, read up on the Elasticsearch Query DSL.
- Finally, learn how App Search builds its search queries, using the Search Explain API.