Search in facets

Search for facet values within a given facet.

Use this to build autocomplete or refinement UIs for facet filters.

POST /indexes/{indexUid}/facet-search

cURL

cURL

curl \
  -X POST 'MEILISEARCH_URL/indexes/books/facet-search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "facetQuery": "fiction",
    "facetName": "genres",
    "filter": "rating > 3"
  }'

200

{
  "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": 2,
  "estimatedTotalHits": 976,
  "processingTimeMs": 35,
  "query": "american "
}

Authorizations

Authorization · string · header · required

An API key is a token that you provide when making API calls. Read more about how to secure your project.

Include the API key to the Authorization header, for instance:

-H 'Authorization: Bearer 6436fc5237b0d6e0d64253fbaac21d135012ecf1'

If you use a SDK, ensure you instantiate the client with the API key, for instance with JS SDK:

const client = new MeiliSearch({
  host: 'MEILISEARCH_URL',
  apiKey: '6436fc5237b0d6e0d64253fbaac21d135012ecf1'
});

Path Parameters

indexUid · string · required

Unique identifier of the index.

Body

application/json

Request body for searching facet values

facet_name · string · required

Name of the facet to search

facet_query · string | null

Query string to search for facet values

q · string | null

Query string to filter documents before facet search

vector · number<float>[] | null

Custom query vector for semantic search

media · any

Multimodal content for AI-powered search

hybrid · object

Hybrid search configuration that combines keyword search with semantic (vector) search. Set semanticRatio to balance between keyword matching (0.0) and semantic similarity (1.0). Requires an embedder to be configured in the index settings.

Show child attributes

filter · any

Filter expression to apply before facet search

matching_strategy · enum<string>

Strategy used to match query terms

Available options: last, all, frequency

attributes_to_search_on · string[] | null

Restrict search to specified attributes

ranking_score_threshold · number<double> | null

Minimum ranking score threshold (0.0 to 1.0) that documents must achieve to be considered when computing facet counts. Documents with scores below this threshold are excluded from facet value counts.

locales · enum<string>[] | null

Languages to use for query processing

Available options: af, ak, am, ar, az, be, bn, bg, ca, cs, da, de, el, en, eo, et, fi, fr, gu, he, hi, hr, hu, hy, id, it, jv, ja, kn, ka, km, ko, la, lv, lt, ml, mr, mk, my, ne, nl, nb, or, pa, fa, pl, pt, ro, ru, si, sk, sl, sn, es, sr, sv, ta, te, tl, th, tk, tr, uk, ur, uz, vi, yi, zh, zu, afr, aka, amh, ara, aze, bel, ben, bul, cat, ces, dan, deu, ell, eng, epo, est, fin, fra, guj, heb, hin, hrv, hun, hye, ind, ita, jav, jpn, kan, kat, khm, kor, lat, lav, lit, mal, mar, mkd, mya, nep, nld, nob, ori, pan, pes, pol, por, ron, rus, sin, slk, slv, sna, spa, srp, swe, tam, tel, tgl, tha, tuk, tur, ukr, urd, uzb, vie, yid, zho, zul, cmn

exhaustive_facet_count · boolean | null

Return exhaustive facet count instead of an estimate

Response

200

application/json

The documents are returned.

Option 1

Option 2

Search response containing matching documents and metadata

hitsPerPage · integer · required

Number of results on each page

Required range: x >= 0

page · integer · required

Current search results page

Required range: x >= 0

totalPages · integer · required

Exhaustive total number of search result pages

Required range: x >= 0

totalHits · integer · required

Exhaustive total number of matches

Required range: x >= 0

hits · object[] · required

Results of the query

Show child attributes

query · string · required

Query originating the response

processingTimeMs · integer · required

Processing time of the query in milliseconds

Required range: x >= 0

queryVector · number<float>[] | null

Vector representation of the query

facetDistribution · object

Distribution of the given facets

Show child attributes

facetStats · object

The numeric min and max values per facet

Show child attributes

requestUid · string<uuid> | null

A UUID v7 identifying the search request

metadata · object

Metadata about the search query

Show child attributes

performanceDetails · any

Performance details of the search query

remoteErrors · object

Show child attributes

semanticHitCount · integer<u-int32> | null

Exhaustive number of semantic search matches (only present in AI-powered searches)

Required range: x >= 0