# 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.

# Search in an index with POST route

POST
/indexes/:index_uid/search

Search for documents matching a specific query in the given index.

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.

# Path variables

Variable Description
index_uid The index UID

# Body

Variable Type Description Default value
q String Query string _(mandatory) ""
offset Integer Number of documents to skip 0
limit Integer Maximum number of documents returned 20
filter String OR [Strings OR [Strings]] Filter queries by an attribute value null
facetsDistribution [Strings] Facets for which to retrieve the matching count null
attributesToRetrieve [Strings] Attributes to display in the returned documents ["*"]
attributesToCrop [Strings] Attributes whose values have to be cropped null
cropLength Integer Length used to crop field values 200
attributesToHighlight [Strings] Attributes whose values will contain highlighted matching terms null
matches Boolean Defines whether an object that contains information about the matches should be returned or not false
sort [Strings] Sort search results according to the attributes and sorting order (asc or desc) specified null

filter accepts a query string. You can find more about the filter syntax on our dedicated page.
cropLength is automatically rounded to match word boundaries.
sort requires attributes to be given as attribute:sorting_order. You can find more about the syntax on our dedicate page.

Learn more about how to use the search parameters.

Placeholder search is a search with an empty q parameter. Since there is no query term, the built-in ranking rules (opens new window) 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 [result]
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.

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

# Path variables

Variable Description
index_uid The index UID

# 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 value null
facetsDistribution Facets for which to retrieve the matching count null
attributesToRetrieve Attributes to display in the returned documents ["*"]
attributesToCrop Attributes whose values have to be cropped null
cropLength Length used to crop field values 200
attributesToHighlight Attributes whose values will contain highlighted matching terms null
matches Defines whether an object that contains information about the matches should be returned or not false
sort Sort search results according to the attributes and sorting order (asc or desc) specified null

filter accepts a query string. You can find about the filter syntax on our dedicated page.
cropLength is automatically rounded to match word boundaries.
sort requires attributes to be given as attribute:sorting_order. You can find more about the syntax on our dedicate page.

Learn more about how to use the search parameters.

# 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 [result]
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 "
}