Search

Full-text search with support for filters, faceted search, sorting, highlighting, and hybrid vector search.

Search endpoint

POST/v1/search

Search an index.

Auth: admin or search key
Returns: 200

Request body

{
  "index": "products",
  "q": "macbook",
  "limit": 10,
  "offset": 0,
  "filter": "price < 2000",
  "sort": ["price:asc"],
  "facets": ["category"],
  "attributesToHighlight": ["title"],
  "attributesToRetrieve": [
    "id",
    "title",
    "price"
  ]
}

Response

{
  "hits": [
    {
      "id": 1,
      "title": "MacBook Pro",
      "price": 1999,
      "_formatted": {
        "title": "<em>MacBook</em> Pro"
      }
    }
  ],
  "query": "macbook",
  "processingTimeMs": 2,
  "estimatedTotalHits": 42,
  "facetDistribution": {
    "category": {
      "laptops": 12,
      "phones": 30
    }
  }
}

Parameters

Parameter	Type	Default	Description
`index` · string	string	Required	The index uid to search.
`q` · string	string	""	The search query string. Empty string returns all documents.
`limit` · number	number	20	Maximum number of hits to return. Above what the engine returns at once, it is lowered and the answer says so (Paging and totals, below).
`offset` · number	number	0	Number of hits to skip (for pagination).
`page, hitsPerPage` · number	number	1, 20	Page mode, on every engine: send either one instead of limit and offset. page starts at 1. The answer then has page, hitsPerPage, totalHits and totalPages.
`filter` · string	string	""	Filter expression, e.g. "price < 2000 AND category = laptops".
`sort` · string[]	string[]	[]	Sort order, e.g. ["price:asc", "title:desc"].
`facets` · string[]	string[]	[]	Attributes to compute facet distributions for.
`attributesToHighlight` · string[]	string[]	[]	Attributes to wrap matches with <em> tags, in each hit's _formatted. ["*"] highlights every attribute.
`attributesToRetrieve` · string[]	string[]	["*"]	Attributes to include in each hit. Defaults to all.
`attributesToCrop` · string[]	string[]	[]	Attributes whose values will be cropped around matches.
`cropLength` · number	number	10	Number of words around a match when cropping. Typesense crops to at most this many words with its own snippet, and a per-attribute length ("overview:20") takes this one. Elasticsearch crops to this many words around the first match. Visor's default is 20, and it takes at most 1024.
`cropMarker` · string	string	"…"	Marks where a crop cut the text. Meilisearch, Typesense, Elasticsearch and Visor apply it.
`highlightPreTag` · string	string	"<em>"	Markup before each highlighted match. Meilisearch, Typesense, Elasticsearch and Visor apply it.
`highlightPostTag` · string	string	"</em>"	Markup after each highlighted match. Meilisearch, Typesense, Elasticsearch and Visor apply it.
`showMatchesPosition` · boolean	boolean	false	Include match position information in each hit. Visor has no match positions and refuses true with 400 feature_not_supported.
`showRankingScore` · boolean	boolean	false	Include the ranking score in each hit.
`matchingStrategy` · string	string	"last"	"last", "all", or "frequency". Meilisearch and Visor (instant mode only): see Matching every word below. Typesense and Elasticsearch ignore it.
`hybrid` · object	object	null	Enable hybrid search. Example: { semanticRatio: 0.5, embedder: "default" }.
`vector` · number[]	number[]	null	Vector for nearest-neighbor search (used with hybrid or standalone).
`mode` · string	string	"instant"	Visor only: "instant" (typo-tolerant, as-you-type) or "retrieval" (BM25F, for longer queries), on the same index. Other engines ignore it. Visor refuses hybrid and vector with 400 feature_not_supported.
`typo` · object	object	null	Visor only: { "enabled": false } turns typos off for this search. Other engines ignore it.
`typoTokensThreshold` · number	number	0	Visor only, instant mode: match with no typos first, then one, then the full budget, while fewer than this many hits match. 0 turns it off. Other engines ignore it.
`experimentKey, variant` · string	string	none	Tag this search with an A/B test variant, for Analytics > Experiments. Send both or neither. See A/B test engines.
`sessionId` · string	string	none	An anonymous visitor or session id, stored with the search for experiment results.

A search key returns every field of each hit unless you ask for fewer. Anyone with the key can ask for all of them, so do not index private fields. See What a search key can read. To search several indexes in one call, see Multi-search.

Each search that answers counts as one search on your plan. Searches you run from the dashboard's Search tab are not counted or billed, though they still show in Analytics.

Matching every word

On Meilisearch, a query of several words does not need every word to match. The default, "last", drops words from the end until enough documents match, and typo tolerance then applies to what is left. The best matches still come first, but the total and the later pages fill up with weaker ones. On a test index, "beats headphones" matched 5 documents with the default: the two Beats headphones, a Beats speaker, "Vacuum belts" and "Coffee beans". With "all" it matched only the two headphones.

request

{
  "index": "products",
  "q": "beats headphones",
  "matchingStrategy": "all"
}

Use "all" for product and catalog search, where a shopper means every word. "frequency" drops the most common words first.

Paging and totals

Each engine stops somewhere. The answer tells you where, with fields that appear only when they apply.

Field	When it appears	What it means
`limitCapped`	Your limit or hitsPerPage was more than the engine returns at once	true. The answer also has the limit (or hitsPerPage) actually used: 250 on Typesense, 10,000 on Elasticsearch, and the index's pagination.maxTotalHits on Meilisearch and Visor (1000 by default).
`maxTotalHits`	The total is more than paging can reach	The hits paging stops at: the index's pagination.maxTotalHits on Meilisearch and Visor, 10,000 on Elasticsearch. Pages past it come back empty.
`totalHitsExact`	The total is a lower bound	false. Elasticsearch stops counting at 10,000, so the true total may be higher.
`page, hitsPerPage, totalHits, totalPages`	You sent page or hitsPerPage	The page you got and its size. totalPages counts only pages that can be fetched, so every page it counts has hits.

request, then the answer on Meilisearch with 10,002 matches

{
  "index": "products",
  "q": "",
  "page": 3,
  "hitsPerPage": 20
}

{
  "hits": [ ... ],
  "page": 3,
  "hitsPerPage": 20,
  "totalHits": 10002,
  "totalPages": 50,
  "maxTotalHits": 1000
}

Build page links from totalPages, not from the total. On Meilisearch you can raise the limit with the pagination.maxTotalHits setting. To read every document, use the cursor on GET /v1/documents with an admin key.

Search errors

A search the engine cannot run answers 400 with a code, and a message that names the field and the fix. Index names in messages are your index uid, never the engine's internal name.

Status and code	Cause
400 invalid_search_filter	A filter on a field that is not filterable. On Elasticsearch, a filter on a field the index has no document with.
400 invalid_search_facets	A facet on a field that is not filterable. On Elasticsearch, a facet on a text field: facet on <field>.keyword.
400 invalid_search_sort	A sort on a field that is not sortable. On Elasticsearch, a sort on a text field (sort on <field>.keyword) or on a field the index does not have.
400 invalid_search_offset	Elasticsearch: offset plus limit is past 10,000. Narrow the search, or list documents with a cursor.
400 invalid_search_page	page is not a whole number of 1 or more.
400 invalid_search_hits_per_page	hitsPerPage is not a whole number of 0 or more.
400 index_required	The body has no index.
400 invalid_json	The body is not valid JSON.
404 index_not_found	No index with that uid is visible to the key.

response

{
  "error": "Can't facet on `category`: …",
  "code": "invalid_search_facets"
}

In multi-search, a query that fails gets the same error and code in its own place in results, and the other queries still answer. All codes are on the Errors page.

Filters

Filter expressions let you narrow search results. Attributes must be listed in filterableAttributes in your index settings before they can be used in filters. That is the rule on Meilisearch and Visor. Typesense and Elasticsearch filter on every field without it, but on Elasticsearch an exact match on a text field needs <field>.keyword. See Index into more than one engine.

filter syntax

// Simple comparison
"price < 2000"

// Equality
"category = laptops"

// Combined with AND / OR
"price < 2000 AND category = laptops"
"category = laptops OR category = tv"

// IN operator
"category IN [laptops, phones, tablets]"

// Negation
"NOT category = accessories"

// Nested with parentheses
"(price < 500 OR price > 2000)" +
  " AND category = laptops"

A filter can also be an array of expressions, and every engine ANDs its items. Each item stays a whole clause: on Typesense, Elasticsearch and Visor each item is read on its own in the portable syntax (comparisons, IN, EXISTS, AND, OR and parentheses), and an item that does not parse is refused with 400. Meilisearch reads each item itself. To use an engine's own syntax, such as NOT on Visor or Typesense's filter_by, send one string.

filter array

"filter": [
  "tenant_id = 42",
  "category = laptops OR category = tv"
]

Facets

Pass attribute names in the facets array to receive a distribution of values for each attribute. Useful for building filter UIs with counts.

response

"facetDistribution": {
  "category": {
    "laptops": 12,
    "phones": 30,
    "tablets": 8
  }
}

A number facet also comes back in facetStats with its lowest and highest value among the hits, for a price slider. Every engine returns it. On Typesense the field must be in filterableAttributes, as every facet must.

response

"facetStats": {
  "price": { "min": 12.5, "max": 1999 }
}

Sorting

Sort results by one or more attributes. Attributes must be listed in sortableAttributes. Use the format attribute:direction where direction is asc or desc.

example

"sort": ["price:asc", "title:desc"]

Geo search

Find documents near a point, inside a box or inside a polygon, and sort them by distance. Send geo with /v1/search or with any query of /v1/multi-search. It works with your own filter and sort: the geo filter is added to yours, and the distance sort comes first.

request

{
  "index": "stores",
  "q": "",
  "geo": {
    "around": {
      "lat": 48.8606,
      "lng": 2.3376,
      "radius": 5000
    },
    "sort": "asc"
  }
}

response

"hits": [
  { "id": "louvre", "_geoDistance": 0 },
  { "id": "notre-dame", "_geoDistance": 1234 }
]

Parameter	Type	Default	Description
`geo.around` · { lat, lng, radius? }	{ lat, lng, radius? }	–	A point. With radius, in meters, only documents within it. Also the origin of geo.sort.
`geo.boundingBox` · { topRight, bottomLeft }	{ topRight, bottomLeft }	–	Only documents inside the box. Each corner is { lat, lng }.
`geo.polygon` · [{ lat, lng }, ...]	[{ lat, lng }, ...]	–	Only documents inside the polygon, 3 points or more. Typesense and Elasticsearch.
`geo.sort` · "asc" or "desc"	"asc" or "desc"	–	Nearest first or farthest first from geo.around. Each hit then carries _geoDistance in meters. Not on Visor.

Each document keeps its point in a _geo field, in the shape its engine reads. Put _geo in filterableAttributes, and on Meilisearch in sortableAttributes too to sort by distance.

Engine	_geo in a document	What it supports
Meilisearch	{ "lat": 48.86, "lng": 2.34 }	Radius, box, sort by distance. No polygon on a _geo point.
Typesense	[48.86, 2.34]	Radius, box, polygon, sort by distance. Listing _geo declares it a geopoint.
Elasticsearch	{ "lat": 48.86, "lon": 2.34 }	Radius, box, polygon, sort by distance. Listing _geo maps it as a geo_point.
Visor	{ "lat": 48.86, "lng": 2.34 }	Radius and box. No polygon or distance sort yet.

Declare _geo on Typesense and Elasticsearch before you send documents when you can. On Typesense, declaring it over documents that already hold [lat, lng] converts the field in place, with no reindex; any other shape is refused and nothing changes. On Elasticsearch, a field that documents have already typed cannot change: the settings call answers 400 reindex_required, and you need a new index with _geo declared before its first document.

A bad value answers 400 invalid_geo on every engine. A part the engine cannot run, such as a polygon on Meilisearch or a distance sort on Visor, answers 400 feature_not_supported.

Highlighting

Request highlighted versions of attributes to show which parts of the text matched the query. Matched text is wrapped in <em> tags, or in highlightPreTag and highlightPostTag where the engine applies them. Each hit then carries _formatted: its fields, with the highlighted ones marked and the cropped ones cut to a snippet. A field with no match keeps its value.

response

"_formatted": {
  "title": "<em>MacBook</em> Pro 16-inch",
  "description": "…the new <em>MacBook</em> Pro with a 16-inch…"
}