Search
editSearch
editWant to start with the concepts? Explore the Search guide.
Search, facet, filter, and curate your documents.
Change the default search behaviour using the Search Settings API or the Result Settings UI in the dashboard.
See the sidebar for further reference on deeper search parameters.
Before You Search...
editBefore you send a query, it helps to know:
- Are there any Search Settings configured?
- Are there any Result Settings configured?
By default a search result will include all fields as raw, unlimited values. But you can choose to add character limits or return snippet field values.
The Search Settings API and the Result Settings feature can change these defaults.
You can also change it per API call with the Result Fields API.
It’s good to experiment to see how the Result Field parameters impact your results.
After you perform some basic queries with result fields, check out the other API Reference documentation to get even deeper:
Search Queries
editThe search endpoint responds to GET and POST requests.
There are two different endpoints that you can query:
They are similar, except multi_search allows up to 10 queries in a single API call.
-
query(required) - A string or number used to find related documents. To match all documents, use an empty string "". You may also apply the following Lucene Query Syntax functions: double quoted strings, + and -, AND, OR, and NOT. View Example
-
page(optional) - Provides optional keys of size and current. Specifies the number of results per page and which page the API should return. View Example
Performing a Single Search Query
editPOST /api/as/v1/engines/{ENGINE_NAME}/search
GET /api/as/v1/engines/{ENGINE_NAME}/search
Example - Performing a single query search.
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
"query": "everglade"
}'
Example Response
{
"meta": {
"warnings": [],
"request_id": "2992570ab570b581ac6c457bddf68835",
"page": {
"total_pages": 1,
"size": 10,
"current": 1,
"total_results": 3
},
"alerts": []
},
"results": [
{
"world_heritage_site": {
"raw": "true"
},
"states": {
"raw": [
"Florida"
]
},
"location": {
"raw": "25.32,-80.93"
},
"nps_link": {
"raw": "https://www.nps.gov/ever/index.htm"
},
"acres": {
"raw": 1508968.1
},
"date_established": {
"raw": "1934-05-30T05:00:00+00:00"
},
"title": {
"raw": "Everglades"
},
"visitors": {
"raw": 930907
},
"square_km": {
"raw": 6106.6
},
"description": {
"raw": "The Everglades are the largest tropical wilderness in the United States. This mangrove and tropical rainforest ecosystem and marine estuary is home to 36 protected species, including the Florida panther, American crocodile, and West Indian manatee. Some areas have been drained and developed; restoration projects aim to restore the ecology."
},
"_meta": {
"score": 1396363.1
},
"id": {
"raw": "park_everglades"
}
},
# ... More documents (truncated)
]
}
Performing a Single Search Query with Lucene Query Syntax
editExample - Performing a single query search using Lucene Query Syntax.
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
"query": "wyoming AND montana OR california NOT washington"
}'
Performing a Multiple Search Query
editYou can add multiple queries to a single search request.
Note that the multi_search queries have a fixed limit of 10 queries per request.
Note: Each query inside of a multi_search is counted as a separate analytic event. For example, issuing a multi_search with 4 queries will increase the analytics query count by 4.
POST /api/as/v1/engines/{ENGINE_NAME}/multi_search
GET /api/as/v1/engines/{ENGINE_NAME}/multi_search
Example - Performing a multiple query search.
curl -X POST 'http://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/multi_search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
"queries": [
{"query": "california"},
{"query": "florida"}
]
}'
Example Response
[
# First query result
{
"meta": {
"alerts": [],
"warnings": [],
"page": {
"current": 1,
"size": 10,
"total_pages": 1,
"total_results": 4
}
},
"results": [
{
"nps_link": {
"raw": "https://www.nps.gov/yose/index.htm"
},
"id": {
"raw": "park_yosemite"
},
"visitors": {
"raw": 5028868
},
"title": {
"raw": "Yosemite"
},
"date_established": {
"raw": "1890-10-01T05:00:00+00:00"
},
"world_heritage_site": {
"raw": "true"
},
"_meta": {
"score": 7543316
},
"description": {
"raw": "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."
},
"states": {
"raw": [
"California"
]
},
"acres": {
"raw": 761747.5
},
"location": {
"raw": "37.83,-119.5"
},
"square_km": {
"raw": 3082.7
}
},
# ... More documents (truncated)
]
},
# ... Second query result (truncated)
]
Page
editPaginate results.
-
size(optional) -
Number of results per page.
Must be greater than or equal to
1and less than or equal to1000.Defaults to
10. -
current(optional) -
Page number to return.
Must be greater than or equal to
1and less than or equal to100.Defaults to
1.
Example - Getting the second page of results with a page size of 5. The API will return documents #5 through #10 by document score in the response.
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
"query": "park",
"page": {
"size": 5,
"current": 2
}
}'
Limit on results per query
editAs described in Page, App Search limits page.size to 1000 and page.current to 100.
This implies a limit of one hundred thousand results per search query (1000×100).
But App Search is further constrained by the default result window in Elasticsearch.
Therefore, App Search effectively limits each search query to ten thousand (10000) results.
When you query for more than 10000 results, App Search returns a successful response. However, the response is empty.
For example, consider a query for 10 pages of 1000 results each. App Search returns a successful response with 10000 results:
"page": {
"current": 10,
"size": 1000
}
# 200 OK
{
"meta": {
"page": {
"current": 10,
"total_pages": 10,
"total_results": 10000,
"size": 1000
},
},
"results": [
…
]
}
However, increasing page.current to 11 exceeds the effective limit of 10000 results.
App Search still returns a successful response, but the response is empty.
"page": {
"current": 11,
"size": 1000
}
# 200 OK
{
"meta": {
"page": {
"current": 11,
"total_pages": 0,
"total_results": 0,
"size": 1000
},
},
"results": []
}
Work around this limitation by requesting fewer documents. Divide a large set of documents into smaller sets by filtering, perhaps by category, date range, or other fields. Choose filters that create sets smaller than 10000.
Common issues
editWhen constructing search API requests, some common issues are:
-
The
queryparameter is omitted. -
The value of
queryis not a string or a number. -
The value of
pageis not a JSON object. -
The value of
page.sizeis not greater than or equal to1and less than or equal to1000. -
The value of
page.currentis not greater than or equal to1and less than or equal to100. - The query requests more than 10000 results, returning an empty response.