> ## Documentation Index
> Fetch the complete documentation index at: https://www.meilisearch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Debug search performance
> Use the showPerformanceDetails parameter to get detailed timing breakdowns for each stage of a search query.
When a search query is slower than expected, it can be difficult to tell which part of the pipeline is responsible. The `showPerformanceDetails` parameter returns per-stage timing information so you can pinpoint bottlenecks without guesswork.
## How it works
Set `showPerformanceDetails` to `true` in any search request. Meilisearch will include a `performanceDetails` object in the response, breaking down how much time each stage of the search pipeline consumed.
This parameter is supported on all search routes:
* `POST /indexes/{indexUid}/search`
* `GET /indexes/{indexUid}/search`
* `POST /multi-search`
* `POST /indexes/{indexUid}/similar`
* `GET /indexes/{indexUid}/similar`
## Basic usage
Add `showPerformanceDetails` to a standard search request:
```bash theme={null}
curl \
-X POST 'MEILISEARCH_URL/indexes/movies/search' \
-H 'Content-Type: application/json' \
--data-binary '{
"q": "glass",
"showPerformanceDetails": true
}'
```
The response includes the usual search results along with a `performanceDetails` object:
```json theme={null}
{
"hits": [
{ "id": 1, "title": "Glass Onion" }
],
"query": "glass",
"processingTimeMs": 4,
"performanceDetails": {
"wait in queue": "295.29µs",
"search > tokenize query": "436.67µs",
"search > evaluate query": "649.00µs",
"search > keyword ranking": "515.71µs",
"search > format": "288.54µs",
"search": "3.56ms"
}
}
```
## Understanding performance stages
Each key in `performanceDetails` represents a stage of the search pipeline. Stage names are hierarchical, using `>` as a separator (e.g., `search > keyword ranking`).
### Top-level stages
| Stage | Description |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wait in queue` | Time waiting in search queue. Meilisearch limits concurrent searches, so a high value here means your instance is handling too many simultaneous queries. |
| `search` | Total time for the entire search operation, including all sub-stages below. |
| `similar` | Total time for a similar documents request (instead of `search`). |
### Search sub-stages
These appear as children of the `search` stage. Not all stages appear in every query; Meilisearch only reports stages that were actually executed.
| Stage | Description |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search > tokenize query` | Breaking the query string into individual tokens. Typically very fast unless the query is unusually long. |
| `search > embed query` | Generating vector embeddings for the query. Only appears when using [hybrid or semantic search](/capabilities/hybrid_search/overview). Duration depends on your embedder provider and network latency. |
| `search > evaluate filter` | Evaluating [filter expressions](/capabilities/filtering_sorting_faceting/advanced/filter_expression_syntax) to narrow the candidate set. Complex filters or many filterable attributes increase this time. |
| `search > evaluate query` | Retrieving the set of documents matching the query. This combines filter results with the full document set to establish which documents are eligible for ranking. |
| `search > keyword ranking` | Ranking candidates using the keyword ranking rules. Often the most significant stage for broad queries on large datasets. |
| `search > placeholder ranking` | Ranking candidates using the sort and the custom ranking rules ([placeholder search](/capabilities/full_text_search/getting_started/placeholder_search)). Appears instead of `keyword ranking` when `q` is empty or missing. |
| `search > semantic ranking` | Ranking candidates based on the vector similarity with the embedding. Only appears when using [hybrid or semantic search](/capabilities/hybrid_search/overview). |
| `search > personalization` | Applying [search personalization](/capabilities/personalization/overview) to re-rank results based on user context. Only appears when personalization is configured. |
| `search > facet distribution` | Computing facet value counts for the `facets` parameter. Cost scales with the number of faceted attributes and unique values. See [maxValuesPerFacet](/capabilities/full_text_search/advanced/performance_tuning#lower-max-values-per-facet). |
| `search > format` | Formatting results: [highlighting, cropping](/capabilities/full_text_search/how_to/highlight_search_results), building the response payload. Cost scales with the number of attributes to highlight/crop and the size of document fields. |
### Federated search stages
When using `showPerformanceDetails` at the `federation` level, you see these stages instead:
| Stage | Description |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `federating results > partition queries` | Organizing queries by index and remote host. |
| `federating results > start remote search` | Initiating search requests to remote Meilisearch instances. Only appears when using [network search](/resources/self_hosting/sharding/overview). |
| `federating results > execute local search` | Executing queries against local indexes. |
| `federating results > wait for remote results` | Waiting for remote instances to respond. High values indicate network latency or slow remote instances. |
| `federating results > merge results` | Merging and deduplicating results from all sources into a single ranked list. |
| `federating results > hydrate documents` | Fetching full document data, including [linked index](/capabilities/indexing/how_to/document_relations) joins. |
| `federating results > merge facets` | Combining facet distributions from all sources. |
Multiple occurrences of the same stage (e.g., multiple `search > keyword ranking` in a federated query) are automatically accumulated into a single total duration.
## Multi-search
In multi-search requests, set `showPerformanceDetails` on each individual query that you want to profile:
```bash theme={null}
curl \
-X POST 'MEILISEARCH_URL/multi-search' \
-H 'Content-Type: application/json' \
--data-binary '{
"queries": [
{
"indexUid": "movies",
"q": "glass",
"showPerformanceDetails": true
},
{
"indexUid": "actors",
"q": "samuel",
"showPerformanceDetails": true
}
]
}'
```
Each result in the response includes its own `performanceDetails`, letting you compare timing across indexes and queries.
## Federated search
For federated multi-search, set `showPerformanceDetails` in the `federation` object to get timing details for the combined search:
```bash theme={null}
curl \
-X POST 'MEILISEARCH_URL/multi-search' \
-H 'Content-Type: application/json' \
--data-binary '{
"federation": {
"showPerformanceDetails": true
},
"queries": [
{ "indexUid": "movies", "q": "glass" },
{ "indexUid": "books", "q": "glass" }
]
}'
```
## Similar documents
The similar documents endpoint also supports `showPerformanceDetails`:
```bash theme={null}
curl \
-X POST 'MEILISEARCH_URL/indexes/movies/similar' \
-H 'Content-Type: application/json' \
--data-binary '{
"id": "143",
"showPerformanceDetails": true
}'
```
## Practical tips
### Identify the bottleneck
Look for the stage with the highest duration. Common patterns:
* **High `wait in queue`**: your instance is overloaded with concurrent searches. Scale your hardware or reduce query volume.
* **High `search > evaluate filter`**: complex [filters](/capabilities/filtering_sorting_faceting/getting_started) expressions or too many filterable attributes. Use [granular filterable attributes](/capabilities/filtering_sorting_faceting/how_to/configure_granular_filters) to disable unused filter features.
* **High `search > evaluate query`**: complex query containing a lot of words or matching a lot of synonyms, generating a complex query tree that is expensive to evaluate. Add [stop words](/capabilities/full_text_search/how_to/configure_stop_words), reduce synonyms cardinality.
* **High `search > keyword ranking`**: the query necessitates a lot of iterations in the ranking rules to retrieve the requested amount of documents, reduce the offset and limit parameters, limit [searchable attributes](/capabilities/full_text_search/how_to/configure_searchable_attributes), or lower [`maxTotalHits`](/capabilities/full_text_search/advanced/performance_tuning#lower-max-total-hits).
* **High `search > embed query`**: your embedder is slow. Consider switching to a faster model, using a local embedder for search with [composite embedders](/capabilities/hybrid_search/advanced/composite_embedders), or caching embeddings.
* **High `search > facet distribution`**: too many faceted attributes or high `maxValuesPerFacet`. Lower it to the number of facet values you actually display.
* **High `search > format`**: large `attributesToRetrieve`, `attributesToHighlight`, or `attributesToCrop`. Reduce to only the fields your UI needs.
* **High `federating results > wait for remote results`**: network latency to remote instances. Check network connectivity or colocate instances.
### Compare before and after
Use `showPerformanceDetails` before and after configuration changes (adding stop words, adjusting searchable attributes, modifying the search cutoff) to measure the impact of each optimization.
### Disable in production
Collecting performance details adds a small amount of overhead to each search request. Use this parameter for debugging and profiling, then remove it from production queries.
Optimize search speed and relevancy for large datasets
Understand how Meilisearch ranks search results
Set time limits to guarantee consistent response times
Full API reference for the search endpoint