Search

MeiliSearch exposes 2 routes to perform searches:

  • A POST route: this is the preferred route when using API authentication, as it allows preflight requestSearch - 图1 (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

  1. /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 requestsSearch - 图2 (opens new window) to be cached. Caching preflight requests improves considerably the speed of the search.

Path Variables

VariableDescription
index_uidThe index UID

Body

VariableTypeDescriptionDefault value
qStringQuery string _(mandatory)“”
offsetIntegerNumber of documents to skip0
limitIntegerMaximum number of documents returned20
filtersStringFilter queries by an attribute valuenull
facetFilters[Strings OR [Strings]]Facet names and values to filter onnull
facetsDistribution[Strings]Facets for which to retrieve the matching countnull
attributesToRetrieve[Strings]Attributes to display in the returned documents[“*”]
attributesToCrop[Strings]Attributes whose values have to be croppednull
cropLengthIntegerLength used to crop field values200
attributesToHighlight[Strings]Attributes whose values will contain highlighted matching termsnull
matchesBooleanDefines whether an object that contains information about the matches should be returned or notfalse

filters accept a query string. You can find more about the filter syntax on our dedicated page.
cropLength is automatically rounded to match word boundaries.

Learn more about how to use the search parameters.

Response

fieldDescriptiontype
hitsResults of the query[result]
offsetNumber of documents skippednumber
limitNumber of documents to takenumber
nbHitsTotal number of matchesnumber
exhaustiveNbHitsWhether nbHits is exhaustiveboolean
facetsDistributionDistribution of the given facetsobject
exhaustiveFacetsCountWhether facetsDistribution is exhaustiveboolean
processingTimeMsProcessing time of the querynumber
queryQuery originating the responsestring

Example

  1. curl \
  2. 'http://localhost:7700/indexes/movies/search' \
  3. --data '{ "q": "american ninja" }'
  1. client.index('movies').search('American ninja')
  1. client.index('movies').search('American ninja')
  1. // Do a search
  2. $searchResults = $client->index('movies')->search('american ninja');
  3. // Get results in an Array using a getter
  4. $hits = $searchResults->getHits();
  5. // Get the decoded response of MeiliSearch, see response below
  6. $response = $searchResults->getRaw();
  1. index.search('american ninja')
  1. client.Search("movies").Search(SearchRequest{
  2. Query: "American ninja",
  3. })
  1. let results: SearchResults<Movie> = movies
  2. .search()
  3. .with_query("American ninja")
  4. .execute()
  5. .await
  6. .unwrap();

Response: 200 Ok

  1. {
  2. "hits": [
  3. {
  4. "id": "2770",
  5. "title": "American Pie 2",
  6. "poster": "https://image.tmdb.org/t/p/w1280/q4LNgUnRfltxzp3gf1MAGiK5LhV.jpg",
  7. "overview": "The whole gang are back and as close as ever. They decide to
  8. get even closer by spending the summer together at a beach house. They
  9. decide to hold the biggest...",
  10. "release_date": 997405200
  11. },
  12. {
  13. "id": "190859",
  14. "title": "American Sniper",
  15. "poster": "https://image.tmdb.org/t/p/w1280/svPHnYE7N5NAGO49dBmRhq0vDQ3.jpg",
  16. "overview": "U.S. Navy SEAL Chris Kyle takes his sole mission—protect his
  17. comrades—to heart and becomes one of the most lethal snipers in American
  18. history. His pinpoint accuracy not only saves countless lives but also
  19. makes him a prime...",
  20. "release_date": 1418256000
  21. },
  22. ...
  23. ],
  24. "offset": 0,
  25. "limit": 20,
  26. "nbHits": 976,
  27. "exhaustiveNbHits": false,
  28. "processingTimeMs": 35,
  29. "query": "american "
  30. }

Search in an index with GET route

GET

  1. /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

VariableDescription
index_uidThe index UID

Query Parameters

Query ParameterDescriptionDefault Value
qQuery string“”
offsetNumber of documents to skip0
limitMaximum number of documents returned20
filtersFilter queries by an attribute valuenull
facetFiltersFacet names and values to filter onnull
facetsDistributionFacets for which to retrieve the matching countnull
attributesToRetrieveAttributes to display in the returned documents[“*”]
attributesToCropAttributes whose values have to be croppednull
cropLengthLength used to crop field values200
attributesToHighlightAttributes whose values will contain highlighted matching termsnull
matchesDefines whether an object that contains information about the matches should be returned or notfalse

filters accept a query string. You can find about the filter syntax on our dedicated page.
cropLength is automatically rounded to match word boundaries.

Learn more about how to use the search parameters.

Placeholder Search

When the q parameter is not specified, a placeholder search is run instead.

Response

fieldDescriptiontype
hitsResults of the query[result]
offsetNumber of documents skippednumber
limitNumber of documents to takenumber
nbHitsTotal number of matchesnumber
exhaustiveNbHitsWhether nbHits is exhaustiveboolean
facetsDistributionDistribution of the given facetsobject
exhaustiveFacetsCountWhether facetsDistribution is exhaustiveboolean
processingTimeMsProcessing time of the querynumber
queryQuery originating the responsestring

Example

  1. curl \
  2. 'http://localhost:7700/indexes/movies/search' \
  3. --data '{ "q": "american ninja" }'
  1. client.index('movies').search('American ninja')
  1. client.index('movies').search('American ninja')
  1. // Do a search
  2. $searchResults = $client->index('movies')->search('american ninja');
  3. // Get results in an Array using a getter
  4. $hits = $searchResults->getHits();
  5. // Get the decoded response of MeiliSearch, see response below
  6. $response = $searchResults->getRaw();
  1. index.search('american ninja')
  1. client.Search("movies").Search(SearchRequest{
  2. Query: "American ninja",
  3. })
  1. let results: SearchResults<Movie> = movies
  2. .search()
  3. .with_query("American ninja")
  4. .execute()
  5. .await
  6. .unwrap();

Response: 200 Ok

  1. {
  2. "hits": [
  3. {
  4. "id": "2770",
  5. "title": "American Pie 2",
  6. "poster": "https://image.tmdb.org/t/p/w1280/q4LNgUnRfltxzp3gf1MAGiK5LhV.jpg",
  7. "overview": "The whole gang are back and as close as ever. They decide to
  8. get even closer by spending the summer together at a beach house. They
  9. decide to hold the biggest...",
  10. "release_date": 997405200
  11. },
  12. {
  13. "id": "190859",
  14. "title": "American Sniper",
  15. "poster": "https://image.tmdb.org/t/p/w1280/svPHnYE7N5NAGO49dBmRhq0vDQ3.jpg",
  16. "overview": "U.S. Navy SEAL Chris Kyle takes his sole mission—protect his
  17. comrades—to heart and becomes one of the most lethal snipers in American
  18. history. His pinpoint accuracy not only saves countless lives but also
  19. makes him a prime...",
  20. "release_date": 1418256000
  21. },
  22. ...
  23. ],
  24. "offset": 0,
  25. "limit": 20,
  26. "nbHits": 976,
  27. "exhaustiveNbHits": false,
  28. "processingTimeMs": 35,
  29. "query": "american "
  30. }