curl \
-X POST 'MEILISEARCH_URL/indexes/books/facet-search' \
-H 'Content-Type: application/json' \
--data-binary '{
"facetQuery": "fiction",
"facetName": "genres",
"filter": "rating > 3"
}'import requests
url = "http://localhost:7700/indexes/{index_uid}/facet-search"
payload = {
"facetName": "<string>",
"facetQuery": "<string>",
"q": "<string>",
"vector": [123],
"media": "<unknown>",
"hybrid": {
"embedder": "default",
"semanticRatio": 0.5
},
"filter": "<unknown>",
"attributesToSearchOn": ["<string>"],
"rankingScoreThreshold": 123,
"locales": [],
"exhaustiveFacetCount": True,
"useNetwork": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
facetName: '<string>',
facetQuery: '<string>',
q: '<string>',
vector: [123],
media: '<unknown>',
hybrid: {embedder: 'default', semanticRatio: 0.5},
filter: '<unknown>',
attributesToSearchOn: ['<string>'],
rankingScoreThreshold: 123,
locales: [],
exhaustiveFacetCount: true,
useNetwork: true
})
};
fetch('http://localhost:7700/indexes/{index_uid}/facet-search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "7700",
CURLOPT_URL => "http://localhost:7700/indexes/{index_uid}/facet-search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'facetName' => '<string>',
'facetQuery' => '<string>',
'q' => '<string>',
'vector' => [
123
],
'media' => '<unknown>',
'hybrid' => [
'embedder' => 'default',
'semanticRatio' => 0.5
],
'filter' => '<unknown>',
'attributesToSearchOn' => [
'<string>'
],
'rankingScoreThreshold' => 123,
'locales' => [
],
'exhaustiveFacetCount' => true,
'useNetwork' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://localhost:7700/indexes/{index_uid}/facet-search"
payload := strings.NewReader("{\n \"facetName\": \"<string>\",\n \"facetQuery\": \"<string>\",\n \"q\": \"<string>\",\n \"vector\": [\n 123\n ],\n \"media\": \"<unknown>\",\n \"hybrid\": {\n \"embedder\": \"default\",\n \"semanticRatio\": 0.5\n },\n \"filter\": \"<unknown>\",\n \"attributesToSearchOn\": [\n \"<string>\"\n ],\n \"rankingScoreThreshold\": 123,\n \"locales\": [],\n \"exhaustiveFacetCount\": true,\n \"useNetwork\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://localhost:7700/indexes/{index_uid}/facet-search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"facetName\": \"<string>\",\n \"facetQuery\": \"<string>\",\n \"q\": \"<string>\",\n \"vector\": [\n 123\n ],\n \"media\": \"<unknown>\",\n \"hybrid\": {\n \"embedder\": \"default\",\n \"semanticRatio\": 0.5\n },\n \"filter\": \"<unknown>\",\n \"attributesToSearchOn\": [\n \"<string>\"\n ],\n \"rankingScoreThreshold\": 123,\n \"locales\": [],\n \"exhaustiveFacetCount\": true,\n \"useNetwork\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:7700/indexes/{index_uid}/facet-search")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"facetName\": \"<string>\",\n \"facetQuery\": \"<string>\",\n \"q\": \"<string>\",\n \"vector\": [\n 123\n ],\n \"media\": \"<unknown>\",\n \"hybrid\": {\n \"embedder\": \"default\",\n \"semanticRatio\": 0.5\n },\n \"filter\": \"<unknown>\",\n \"attributesToSearchOn\": [\n \"<string>\"\n ],\n \"rankingScoreThreshold\": 123,\n \"locales\": [],\n \"exhaustiveFacetCount\": true,\n \"useNetwork\": true\n}"
response = http.request(request)
puts response.read_body{
"facetHits": [
{
"value": "action",
"count": 273
},
{
"value": "animated",
"count": 15
}
],
"facetQuery": "ac",
"processingTimeMs": 0
}{
"message": "The Authorization header is missing. It must use the bearer authorization method.",
"code": "missing_authorization_header",
"type": "auth",
"link": "https://docs.meilisearch.com/errors#missing_authorization_header"
}{
"message": "Index `movies` not found.",
"code": "index_not_found",
"type": "invalid_request",
"link": "https://docs.meilisearch.com/errors#index_not_found"
}Search for facet values
Search for facet values matching a query within a given facet attribute. Use this to build autocomplete or dropdown UIs for facet filters.
Prerequisite: The facetName attribute must be in the index’s filterableAttributes list.
Facet search will not work without this configuration.
Note: Facet search only considers the first word of facetQuery. Searching for Jane
returns Jane Austen, but searching for Austen does not.
Note: Numeric facet values are not searchable. Convert numbers to strings if you need to search them as facets.
curl \
-X POST 'MEILISEARCH_URL/indexes/books/facet-search' \
-H 'Content-Type: application/json' \
--data-binary '{
"facetQuery": "fiction",
"facetName": "genres",
"filter": "rating > 3"
}'import requests
url = "http://localhost:7700/indexes/{index_uid}/facet-search"
payload = {
"facetName": "<string>",
"facetQuery": "<string>",
"q": "<string>",
"vector": [123],
"media": "<unknown>",
"hybrid": {
"embedder": "default",
"semanticRatio": 0.5
},
"filter": "<unknown>",
"attributesToSearchOn": ["<string>"],
"rankingScoreThreshold": 123,
"locales": [],
"exhaustiveFacetCount": True,
"useNetwork": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
facetName: '<string>',
facetQuery: '<string>',
q: '<string>',
vector: [123],
media: '<unknown>',
hybrid: {embedder: 'default', semanticRatio: 0.5},
filter: '<unknown>',
attributesToSearchOn: ['<string>'],
rankingScoreThreshold: 123,
locales: [],
exhaustiveFacetCount: true,
useNetwork: true
})
};
fetch('http://localhost:7700/indexes/{index_uid}/facet-search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "7700",
CURLOPT_URL => "http://localhost:7700/indexes/{index_uid}/facet-search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'facetName' => '<string>',
'facetQuery' => '<string>',
'q' => '<string>',
'vector' => [
123
],
'media' => '<unknown>',
'hybrid' => [
'embedder' => 'default',
'semanticRatio' => 0.5
],
'filter' => '<unknown>',
'attributesToSearchOn' => [
'<string>'
],
'rankingScoreThreshold' => 123,
'locales' => [
],
'exhaustiveFacetCount' => true,
'useNetwork' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://localhost:7700/indexes/{index_uid}/facet-search"
payload := strings.NewReader("{\n \"facetName\": \"<string>\",\n \"facetQuery\": \"<string>\",\n \"q\": \"<string>\",\n \"vector\": [\n 123\n ],\n \"media\": \"<unknown>\",\n \"hybrid\": {\n \"embedder\": \"default\",\n \"semanticRatio\": 0.5\n },\n \"filter\": \"<unknown>\",\n \"attributesToSearchOn\": [\n \"<string>\"\n ],\n \"rankingScoreThreshold\": 123,\n \"locales\": [],\n \"exhaustiveFacetCount\": true,\n \"useNetwork\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://localhost:7700/indexes/{index_uid}/facet-search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"facetName\": \"<string>\",\n \"facetQuery\": \"<string>\",\n \"q\": \"<string>\",\n \"vector\": [\n 123\n ],\n \"media\": \"<unknown>\",\n \"hybrid\": {\n \"embedder\": \"default\",\n \"semanticRatio\": 0.5\n },\n \"filter\": \"<unknown>\",\n \"attributesToSearchOn\": [\n \"<string>\"\n ],\n \"rankingScoreThreshold\": 123,\n \"locales\": [],\n \"exhaustiveFacetCount\": true,\n \"useNetwork\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:7700/indexes/{index_uid}/facet-search")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"facetName\": \"<string>\",\n \"facetQuery\": \"<string>\",\n \"q\": \"<string>\",\n \"vector\": [\n 123\n ],\n \"media\": \"<unknown>\",\n \"hybrid\": {\n \"embedder\": \"default\",\n \"semanticRatio\": 0.5\n },\n \"filter\": \"<unknown>\",\n \"attributesToSearchOn\": [\n \"<string>\"\n ],\n \"rankingScoreThreshold\": 123,\n \"locales\": [],\n \"exhaustiveFacetCount\": true,\n \"useNetwork\": true\n}"
response = http.request(request)
puts response.read_body{
"facetHits": [
{
"value": "action",
"count": 273
},
{
"value": "animated",
"count": 15
}
],
"facetQuery": "ac",
"processingTimeMs": 0
}{
"message": "The Authorization header is missing. It must use the bearer authorization method.",
"code": "missing_authorization_header",
"type": "auth",
"link": "https://docs.meilisearch.com/errors#missing_authorization_header"
}{
"message": "Index `movies` not found.",
"code": "index_not_found",
"type": "invalid_request",
"link": "https://docs.meilisearch.com/errors#index_not_found"
}Authorizations
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
Unique identifier of the index.
Body
Request body for searching facet values
Name of the facet attribute to search. Must be present in the index's filterableAttributes list.
Query string to search for matching facet values. If not specified, Meilisearch returns all facet values for the facetName, limited to 100 results. Note: only the first word is used for matching.
Query string to filter the underlying documents before computing facet values. This affects which facet values appear and their counts, but does not filter the facet values themselves.
Custom query vector for semantic search
Multimodal content for AI-powered search
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
Show child attributes
Filter expression to restrict which documents are considered when computing facet values. Attributes must be in filterableAttributes before they can be used in filters.
Strategy used to match query terms
last, all, frequency Restrict search to specified attributes
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.
Languages to use for query processing
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 Return exhaustive facet count instead of an estimate
When true, runs the query on the whole network (all shards covered exactly once).
When false, the query runs locally.
When omitted or null, the default value depends on whether the sharding is enabled for the instance:
- If the instance has sharding enabled (has a leader), defaults to
true. - Otherwise defaults to
false.
It also requires the network experimental feature.
Values: true = use the whole network; false = local, default = see above.
When using the network, the index must exist with compatible settings on all remotes.
Response
Facet values matching the query are returned.
Result of a facet search operation.
Array of matching facet values with their document counts, sorted lexicographically
in ascending order (or by count if sortFacetValuesBy is set to "count").
Show child attributes
Show child attributes
Time in milliseconds Meilisearch took to process the request.
x >= 0The original facetQuery from the request. null if no query was provided.
Errors from remote shards. Only present in federated search when some remotes failed.
Show child attributes
Show child attributes
Was this page helpful?