# Search

Meilisearch exposes 2 routes to perform searches:

  • A POST route: this is the preferred route when using API authentication, as it allows preflight request (opens new window) caching and better performances.
  • A GET route: the usage of this route is discouraged, unless you have good reason to do otherwise (specific caching abilities for example).

Other than the differences mentioned above, the two routes are strictly equivalent. You may find exhaustive descriptions of the parameters accepted by the two routes at the end of this article.

# Search in an index with POST route

POST
/indexes/{index_uid}/search

Search for documents matching a specific query in the given index. The index uid is required.

NOTE

This endpoint has a non-customizable limit of 1000 results. If you want to scrape your database, use the get documents endpoint instead.

This is the preferred route to perform search when an API key is required, as it allows for preflight requests (opens new window) to be cached. Caching preflight requests considerably improves search speed.

# Body

Query Parameter Description Default Value
q Query string ""
offset Number of documents to skip 0
limit Maximum number of documents returned 20
filter Filter queries by an attribute's value null
facetsDistribution Display the count of matches per facet null
attributesToRetrieve Attributes to display in the returned documents ["*"]
attributesToCrop Attributes whose values have to be cropped null
cropLength Maximum length of cropped value in words 10
cropMarker String marking crop boundaries "…"
attributesToHighlight Highlight matching terms contained in an attribute null
highlightPreTag String inserted at the start of a highlighted term "<em>"
highlightPostTag String inserted at the end of a highlighted term "</em>"
matches Return matching terms location false
sort Sort search results by an attribute's value null

Learn more about how to use each search parameter.

Placeholder search is a search with an empty q parameter. Since there is no query term, the built-in ranking rules do not apply. Only sort and custom ranking rules are taken into account.

If the index has no sort or custom ranking rules, the results are returned in the order of their internal database position.

Query terms enclosed in double quotes are treated as phrase searches.

# Response

field Description type
hits Results of the query array of objects
offset Number of documents skipped number
limit Number of documents to take number
nbHits Total number of matches number
exhaustiveNbHits Whether nbHits is exhaustive boolean
facetsDistribution Distribution of the given facets object
exhaustiveFacetsCount Whether facetsDistribution is exhaustive boolean
processingTimeMs Processing time of the query number
query Query originating the response string

# Example

curl \
  -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{ "q": "american ninja" }'

# Response: 200 Ok

{
  "hits": [
    {
      "id": 2770,
      "title": "American Pie 2",
      "poster": "https://image.tmdb.org/t/p/w1280/q4LNgUnRfltxzp3gf1MAGiK5LhV.jpg",
      "overview": "The whole gang are back and as close as ever. They decide to get even closer by spending the summer together at a beach house. They decide to hold the biggest…",
      "release_date": 997405200
    },
    {
      "id": 190859,
      "title": "American Sniper",
      "poster": "https://image.tmdb.org/t/p/w1280/svPHnYE7N5NAGO49dBmRhq0vDQ3.jpg",
      "overview": "U.S. Navy SEAL Chris Kyle takes his sole mission—protect his comrades—to heart and becomes one of the most lethal snipers in American history. His pinpoint accuracy not only saves countless lives but also makes him a prime…",
      "release_date": 1418256000
    },],
  "offset": 0,
  "limit": 20,
  "nbHits": 976,
  "exhaustiveNbHits": false,
  "processingTimeMs": 35,
  "query": "american "
}

# Search in an index with GET route

GET
/indexes/{index_uid}/search

Search for documents matching a specific query in the given index. The index uid is required.

NOTE

This endpoint has a non-customizable limit of 1000 results. If you want to scrape your database, you can use the get documents endpoint instead.

This route should only be used when no API key is required. If an API key is required, use the POST route instead.

# Query parameters

Query Parameter Description Default Value
q Query string ""
offset Number of documents to skip 0
limit Maximum number of documents returned 20
filter Filter queries by an attribute's value null
facetsDistribution Display the count of matches per facet null
attributesToRetrieve Attributes to display in the returned documents ["*"]
attributesToCrop Attributes whose values have to be cropped null
cropLength Maximum length of cropped value in words 10
cropMarker String marking crop boundaries "…"
attributesToHighlight Highlight matching terms contained in an attribute null
highlightPreTag String inserted at the start of a highlighted term "<em>"
highlightPostTag String inserted at the end of a highlighted term "</em>"
matches Return matching terms location false
sort Sort search results by an attribute's value null

Learn more about how to use each search parameter.

# Placeholder search

When no search query is specified, a placeholder search is run instead.

# Phrase search

Query terms enclosed in double quotes are treated as phrase searches.

# Response

field Description type
hits Results of the query array of objects
offset Number of documents skipped number
limit Number of documents to take number
nbHits Total number of matches number
exhaustiveNbHits Whether nbHits is exhaustive boolean
facetsDistribution Distribution of the given facets object
exhaustiveFacetsCount Whether facetsDistribution is exhaustive boolean
processingTimeMs Processing time of the query number
query Query originating the response string

# Example

curl \
  -X GET 'http://localhost:7700/indexes/movies/search?q=american%20ninja'

# Response: 200 Ok

{
  "hits": [
    {
      "id": 2770,
      "title": "American Pie 2",
      "poster": "https://image.tmdb.org/t/p/w1280/q4LNgUnRfltxzp3gf1MAGiK5LhV.jpg",
      "overview": "The whole gang are back and as close as ever. They decide to get even closer by spending the summer together at a beach house. They decide to hold the biggest…",
      "release_date": 997405200
    },
    {
      "id": 190859,
      "title": "American Sniper",
      "poster": "https://image.tmdb.org/t/p/w1280/svPHnYE7N5NAGO49dBmRhq0vDQ3.jpg",
      "overview": "U.S. Navy SEAL Chris Kyle takes his sole mission—protect his comrades—to heart and becomes one of the most lethal snipers in American history. His pinpoint accuracy not only saves countless lives but also makes him a prime…",
      "release_date": 1418256000
    },],
  "offset": 0,
  "limit": 20,
  "nbHits": 976,
  "exhaustiveNbHits": false,
  "processingTimeMs": 35,
  "query": "american "
}

# Search parameters

Here follows an exhaustive description of each search parameter currently available when using the search endpoint. Unless otherwise noted, all parameters are valid for both GET and POST routes.

WARNING

If using the GET route to perform a search, all parameters must be URL-encoded.

This is not necessary when using the POST route or one of our SDKs.

# Overview

Query Parameter Description Default Value
q Query string ""
offset Number of documents to skip 0
limit Maximum number of documents returned 20
filter Filter queries by an attribute's value null
facetsDistribution Display the count of matches per facet null
attributesToRetrieve Attributes to display in the returned documents ["*"]
attributesToCrop Attributes whose values have to be cropped null
cropLength Maximum length of cropped value in words 10
cropMarker String marking crop boundaries "…"
attributesToHighlight Highlight matching terms contained in an attribute null
highlightPreTag String inserted at the start of a highlighted term "<em>"
highlightPostTag String inserted at the end of a highlighted term "</em>"
matches Return matching terms location false
sort Sort search results by an attribute's value null

# Query (q)

Parameter: q
Expected value: any string
Default value: null

Sets the search terms.

WARNING

Meilisearch only considers the first ten words of any given search query. This is necessary in order to deliver a fast search-as-you-type experience.

Additionally, keep in mind queries go through a normalization process that strips accents and diacritics, as well as making all terms lowercase.

# Placeholder search

When q isn't specified, Meilisearch performs a placeholder search. A placeholder search returns all searchable documents in an index, modified by any search parameters used and sorted by that index's custom ranking rules. Since there is no query term, the built-in ranking rules do not apply.

If the index has no sort or custom ranking rules, the results are returned in the order of their internal database position.

TIP

Placeholder search is particularly useful when building a faceted search UI, as it allows users to view the catalog and alter sorting rules without entering a query.

# Example

You can search for films mentioning shifu by setting the q parameter:

curl \
  -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{ "q": "shifu" }'

This will give you a list of documents that contain your query terms in at least one attribute.

{
  "hits": [
    {
      "id": 50393,
      "title": "Kung Fu Panda Holiday",
      "poster": "https://image.tmdb.org/t/p/w500/rV77WxY35LuYLOuQvBeD1nyWMuI.jpg",
      "overview": "The Winter Feast is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers.",
      "release_date": 1290729600,
      "genres": [
        "Animation",
        "Family",
        "TV Movie"
      ]
    }
  ],
  "query": "shifu"
}

# Phrase search

If you enclose search terms in double quotes ("), Meilisearch will only return documents containing those terms in the order they were given. This is called a phrase search.

Phrase searches are case-insensitive and ignore soft separators such as -, ,, and :. Using a hard separator within a phrase search effectively splits it into multiple separate phrase searches: "Octavia.Butler" will return the same results as "Octavia" "Butler".

You can combine phrase search and normal queries in a single search request. In this case, Meilisearch will first fetch all documents with exact matches to the given phrase(s), and then proceed with its default behavior.

# Example
curl \
  -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
--data-binary '{ "q": "\"african american\" horror" }'

# Offset

Parameter: offset
Expected value: any positive integer
Default value: 0

Sets the starting point in the search results, effectively skipping over a given number of documents.

TIP

This parameter can be used together with limit in order to paginate results.

# Example

If you want to skip the first result in a query, set offset to 1:

curl \
  -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "shifu",
    "offset": 1
  }'

# Limit

Parameter: limit
Expected value: any positive integer
Default value: 20

Sets the maximum number of documents returned by a single query.

TIP

This parameter is often used together with offset in order to paginate results.

# Example

If you want your query to return only two documents, set limit to 2:

curl \
  -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "shifu",
    "limit": 2
  }'

# Filter

Parameter: filter
Expected value: a filter expression written as a string or an array of strings
Default value: []

Uses filter expressions to refine search results. Attributes used as filter criteria must be added to the filterableAttributes list.

Read our guide on filtering, faceted search and filter expressions.

# Example

You can write a filter expression in string syntax using logical connectives:

"(genres = horror OR genres = mystery) AND director = 'Jordan Peele'"

You can write the same filter as an array:

[["genres = horror", "genres = mystery"], "director = 'Jordan Peele']

You can then use the filter in a search query:

curl \
  -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "thriller",
    "filter": [
      [
        "genres = Horror",
        "genres = Mystery"],
        "director = \"Jordan Peele\""
      ]
  }'

# Filtering results _geoRadius

If your documents contain _geo data, you can use the _geoRadius built-in filter rule to filter results according to their geographic position.

_geoRadius establishes a circular area based on a central point and a radius. Results beyond this area will be excluded from your search. This filter rule requires three parameters: lat, lng and distance_in_meters.

_geoRadius(lat, lng, distance_in_meters)

lat and lng should be geographic coordinates expressed as floating point numbers. distance_in_meters indicates the radius of the area within which you want your results and should be an integer.

curl \
  -X POST 'http://localhost:7700/indexes/restaurants/search' \
  -H 'Content-type:application/json' \
  --data-binary '{ "filter": "_geoRadius(45.472735, 9.184019, 2000)" }'

# Facets distribution

Parameter: facetsDistribution
Expected value: an array of attributes or ["*"]
Default value: null

Returns the number of documents matching the current search query for each given facet.

This parameter can take two values:

  • An array of attributes: facetsDistribution=["attributeA", "attributeB", …]
  • An asterisk—this will return a count for all facets present in filterableAttributes

NOTE

If an attribute used on facetsDistribution has not been added to the filterableAttributes list, it will be ignored.

# Returned fields

When facetsDistribution is set, the search results object contains two additional fields:

  • facetsDistribution: The number of remaining candidates for each specified facet
  • exhaustiveFacetsCount: A true or false value indicating whether the count is exact (true) or approximate (false)

exhaustiveFacetsCount is false when the search matches contain too many different values for the given facetNames. In this case, Meilisearch stops the distribution count to prevent slowing down the request.

WARNING

exhaustiveFacetsCount is not currently implemented and will always return false.

Learn more about facet distribution in the filtering and faceted search guide.

# Example

Given a movie database, suppose that you want to know the number of Batman movies per genre:

curl \
  -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "Batman",
    "facetsDistribution": ["genres"]
  }'

You would get the following response:

{"nbHits": 1684,
  "query": "Batman",
  "exhaustiveFacetsCount": false,
  "facetsDistribution": {
    "genres": {
      "action": 273,
      "animation": 118,
      "adventure": 132,
      "fantasy": 67,
      "comedy": 475,
      "mystery": 70,
      "thriller": 217
    }
  }
}

# Attributes to retrieve

Parameter: attributesToRetrieve
Expected value: an array of attributes or ["*"]
Default value: ["*"]

Configures which attributes will be retrieved in the returned documents.

If no value is specified, attributesToRetrieve uses the displayedAttributes list, which by default contains all attributes found in the documents.

NOTE

If an attribute has been removed from displayedAttributes, attributesToRetrieve will silently ignore it and the field will not appear in your returned documents.

# Example

To get only the overview and title fields, set attributesToRetrieve to ["overview", "title"].

curl \
  -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "shifu",
    "attributesToRetrieve": [
      "overview",
      "title"
    ]
  }'

# Attributes to crop

Parameter: attributesToCrop
Expected value: an array of attributes or ["*"]
Default value: null

Crops the selected fields in the returned results to the length indicated by the cropLength parameter. When attributesToCrop is set, each returned document contains an extra field called _formatted. This object contains the cropped version of the selected attributes.

By default, crop boundaries are marked by the ellipsis character (). You can change this by using the cropMarker search parameter.

Optionally, you can indicate a custom crop length for any attributes given to attributesToCrop: attributesToCrop=["attributeNameA:5", "attributeNameB:9"]. If configured, these values have priority over cropLength.

Instead of supplying individual attributes, you can provide ["*"] as a wildcard: attributesToCrop=["*"]. This causes _formatted to include the cropped values of all attributes present in attributesToRetrieve.

Meilisearch crops around the first occurrence of any one of the terms present in the search query. If Meilisearch does not find any query terms in a field, cropping begins at the first word in that field.

# Example

If you use shifu as a search query and set the value of the cropLength parameter to 5:

curl \
  -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "shifu",
    "attributesToCrop": ["overview"],
    "cropLength": 5 
  }'

You will get the following response with the cropped text in the _formatted object:

{
  "id": 50393,
  "title": "Kung Fu Panda Holiday",
  "poster": "https://image.tmdb.org/t/p/w1280/gp18R42TbSUlw9VnXFqyecm52lq.jpg",
  "overview": "The Winter Feast is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal Winter Feast at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between Shifu and Mr. Ping.",
  "release_date": 1290729600,
  "_formatted": {
    "id": 50393,
    "title": "Kung Fu Panda Holiday",
    "poster": "https://image.tmdb.org/t/p/w1280/gp18R42TbSUlw9VnXFqyecm52lq.jpg",
    "overview": "…this year Shifu informs Po…",
    "release_date": 1290729600
  }
}

# Crop length

Parameter: cropLength
Expected value: a positive integer
Default value: 10

Configures the total number of words to appear in the cropped value when using attributesToCrop. If attributesToCrop is not configured, cropLength has no effect on the returned results.

Query terms are counted as part of the cropped value length. If cropLength is set to 2 and you search for one term (e.g., shifu), the cropped field will contain two words in total (e.g., "…Shifu informs…").

Stop words are also counted against this number. If cropLength is set to 2 and you search for one term (e.g., grinch), the cropped result may contain a stop word (e.g., "…the Grinch…").

If attributesToCrop uses the attributeName:number syntax to specify a custom crop length for an attribute, that value has priority over cropLength.

# Crop marker

Parameter: cropMarker
Expected value: a string
Default value: "…"

Sets a string to mark crop boundaries when using the attributesToCrop parameter. The crop marker will be inserted on both sides of the crop. If attributesToCrop is not configured, cropMarker has no effect on the returned search results.

If cropMarker is set to null or an empty string, no markers will be included in the returned results.

Crop markers are only added where content has been removed. For example, if the cropped text includes the first word of the field value, the crop marker will not be added to the beginning of the cropped result.

# Example

When searching for shifu, you can use cropMarker to change the default :

curl \
  -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "shifu",
    "cropMarker": "[…]",
    "attributesToCrop": ["overview"]
  }'
{
  "id": 50393,
  "title": "Kung Fu Panda Holiday",
  "poster": "https://image.tmdb.org/t/p/w1280/gp18R42TbSUlw9VnXFqyecm52lq.jpg",
  "overview": "The Winter Feast is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal Winter Feast at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between Shifu and Mr. Ping.",
  "release_date": 1290729600,
  "_formatted": {
    "id": 50393,
    "title": "Kung Fu Panda Holiday",
    "poster": "https://image.tmdb.org/t/p/w1280/gp18R42TbSUlw9VnXFqyecm52lq.jpg",
    "overview": "[…]villager. But this year Shifu informs Po that as Dragon[…]",
    "release_date": 1290729600
  }
}

# Attributes to highlight

Parameter: attributesToHighlight
Expected value: an array of attributes or ["*"]
Default value: null

Highlights matching query terms in the specified attributes. attributesToHighlight only works on values of the following types: string, number, array, object.

When this parameter is set, returned documents include a _formatted object containing the highlighted terms.

Instead of a list of attributes, you can use ["*"]: attributesToHighlight=["*"]. In this case, all the attributes present in attributesToRetrieve will be assigned to attributesToHighlight.

By default highlighted elements are enclosed in <em> and </em> tags. You may change this by using the highlightPreTag and highlightPostTag search parameters.

NOTE

attributesToHighlight also highlights terms configured as synonyms and stop words.

# Example

The following query highlights matches present in the overview attribute:

curl \
  -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{ 
    "q": "winter feast",
    "attributesToHighlight": ["overview"]
  }'

The highlighted version of the text would then be found in the _formatted object included in each returned document:

{
  "id": 50393,
  "title": "Kung Fu Panda Holiday",
  "poster": "https://image.tmdb.org/t/p/w1280/gp18R42TbSUlw9VnXFqyecm52lq.jpg",
  "overview": "The Winter Feast is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal Winter Feast at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between Shifu and Mr. Ping.",
  "release_date": 1290729600,
  "_formatted": {
    "id": 50393,
    "title": "Kung Fu Panda Holiday",
    "poster": "https://image.tmdb.org/t/p/w1280/gp18R42TbSUlw9VnXFqyecm52lq.jpg",
    "overview": "The <em>Winter Feast</em> is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal <em>Winter Feast</em> at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between Shifu and Mr. Ping.",
    "release_date": 1290729600
  }
}

# Highlight tags

Parameters: highlightPreTag and highlightPostTag
Expected value: a string
Default value: "<em>" and "</em>" respectively

highlightPreTag and highlightPostTag configure, respectively, the strings to be inserted before and after a word highlighted by attributesToHighlight. If attributesToHighlight has not been configured, highlightPreTag and highlightPostTag have no effect on the returned search results.

It is possible to use highlightPreTag and highlightPostTag to enclose terms between any string of text, not only HTML tags: "<em>", "<strong>", "*", and "__" are all equally supported values.

If highlightPreTag or highlightPostTag are set to null or an empty string, nothing will be inserted respectively at the beginning or the end of a highlighted term.

# Example

The following query encloses highlighted matches in <span> tags with a class attribute:

curl \
  -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "winter feast",
    "attributesToHighlight": ["overview"],
    "highlightPreTag": "<span class=\"highlight\">",
    "highlightPostTag": "</span>"
  }'

You can find the highlighted query terms inside the _formatted property:

{
  "id": 50393,
  "title": "Kung Fu Panda Holiday",
  "poster": "https://image.tmdb.org/t/p/w1280/gp18R42TbSUlw9VnXFqyecm52lq.jpg",
  "overview": "The Winter Feast is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal Winter Feast at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between Shifu and Mr. Ping.",
  "release_date": 1290729600,
  "_formatted": {
    "id": 50393,
    "title": "Kung Fu Panda Holiday",
    "poster": "https://image.tmdb.org/t/p/w1280/gp18R42TbSUlw9VnXFqyecm52lq.jpg",
    "overview": "The <span class=\"highlight\">Winter Feast</span> is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal <span class=\"highlight\">Winter Feast</span> at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between Shifu and Mr. Ping.",
    "release_date": 1290729600
  }
}

WARNING

Though it is not necessary to use highlightPreTag and highlightPostTag in conjunction, be careful to ensure tags are correctly matched. In the above example, not setting highlightPostTag would result in malformed HTML: <span>Winter Feast</em>.

# Matches

Parameter: matches
Expected value: true or false
Default value: false

Adds a _matchesInfo object to the search response that contains the location of each occurrence of queried terms across all fields. This is useful when you need more control than offered by our built-in highlighting. matches only works for strings, numbers, and arrays of strings and numbers.

The beginning of a matching term within a field is indicated by start, and its length by length.

WARNING

start and length are measured in bytes and not the number of characters. For example, ü represents two bytes but one character.

# Example

If you set matches to true and search for winter feast:

curl \
  -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "winter feast",
    "matches": true
  }'

You would get the following response with information about the matches in the _matchesInfo object. Note how Meilisearch searches for winter and feast separately because of the whitespace:

{
  "id": 50393,
  "title": "Kung Fu Panda Holiday",
  "poster": "https://image.tmdb.org/t/p/w500/rV77WxY35LuYLOuQvBeD1nyWMuI.jpg",
  "overview": "The Winter Feast is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal Winter Feast at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between Shifu and Mr. Ping.",
  "release_date": 1290729600,
  "_matchesInfo": {
    "overview": [
      {
        "start": 4,
        "length": 6
      },
      {
        "start": 11,
        "length": 5
      },
      {
        "start": 234,
        "length": 6
      },
      {
        "start": 241,
        "length": 5
      }
    ]
  }
}

# Sort

Parameter: sort
Expected value: a list of attributes written as an array or as a comma-separated string
Default value: null

Sorts search results at query time according to the specified attributes and indicated order.

Each attribute in the list must be followed by a colon (:) and the preferred sorting order: either ascending (asc) or descending (desc).

NOTE

Attribute order is meaningful. The first attributes in a list will be given precedence over those that come later.

For example, sort="price:asc,author:desc will prioritize price over author when sorting results.

When using the POST route, sort expects an array of strings.

When using the GET route, sort expects the list as a comma-separated string.

Read more about sorting search results in our dedicated guide.

# Example

You can search for science fiction books ordered from cheapest to most expensive:

curl \
  -X POST 'http://localhost:7700/indexes/books/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "science fiction",
    "sort": ["price:asc"]
  }'

# Sorting results with _geoPoint

When dealing with documents containing geolocation data, you can use _geoPoint to sort results based on their distance from a specific geographic location.

_geoPoint is a sorting function that requires two floating point numbers indicating a location's latitude and longitude. You must also specify whether the sort should be ascending (asc) or descending (desc):

curl \
  -X POST 'http://localhost:7700/indexes/restaurants/search' \
  -H 'Content-type:application/json' \
  --data-binary '{ "sort": ["_geoPoint(48.8561446,2.2978204):asc"] }'

Queries using _geoPoint will always include a geoDistance field containing the distance in meters between the document location and the _geoPoint:

[
  {
    "id": 1,
    "name": "Nàpiz' Milano",
    "_geo": {
      "lat": 45.4777599,
      "lng": 9.1967508
    },
    "_geoDistance": 1532
  }
]

You can read more about location-based sorting in our dedicated guide.