Search in facets

cURL

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

{
  "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 "
}

POST

indexes

{index_uid}

facet-search

cURL

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

{
  "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

index_uid

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

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

The documents are returned.

Option 1
Option 2

Search response containing matching documents and metadata.

hitsPerPage

integer

required

Number of results per page.

Required range: x >= 0

page

integer

required

Current page index (1-based).

Required range: x >= 0

totalPages

integer

required

Exhaustive total number of result pages.

Required range: x >= 0

totalHits

integer

required

Exhaustive total number of matching documents.

Required range: x >= 0

hits

object[]

required

Matching documents.

Each hit contains document fields and, when requested, _formatted, _matchesPosition, _rankingScore, _rankingScoreDetails, _geoDistance.

Show child attributes

query

string

required

Query string that produced this response.

processingTimeMs

integer

required

Time taken to process the query, in milliseconds.

Required range: x >= 0

queryVector

number<float>[] | null

Query embedding used for the search.

Present when vector or hybrid search was used.

facetDistribution

object

Count of matching documents per facet value for each requested facet.

Present when facets was set.

Show child attributes

facetStats

object

Minimum and maximum numeric values per facet.

Present for numeric facets when facets was set.

Show child attributes

requestUid

string<uuid> | null

UUID v7 identifying this search request.

metadata

object

Query and index metadata.

Present when requested via the Meili-Include-Metadata header.

Show child attributes

performanceDetails

any

Timing breakdown per processing step.

Present when showPerformanceDetails was true.

remoteErrors

object

Errors from remote shards. Federated search only.

Show child attributes

semanticHitCount

integer<u-int32> | null

Exhaustive number of semantic search matches.

AI-powered (hybrid/semantic) searches only.

Required range: x >= 0

Perform a multi-search Get similar documents with POST

Overview

API Routes

Errors

Authorizations

Path Parameters

Body

Response