Debug search performance

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:

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:

{
  "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. Duration depends on your embedder provider and network latency.
`search > evaluate filter`	Evaluating filter expressions 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). 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.
`search > personalization`	Applying search personalization 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.
`search > format`	Formatting results: highlighting, cropping, 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.
`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 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:

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:

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" }
    ]
  }'

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 expressions or too many filterable attributes. Use granular filterable attributes 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, 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, or lower maxTotalHits.
High search > embed query: your embedder is slow. Consider switching to a faster model, using a local embedder for search with 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.

Performance tuning

Optimize search speed and relevancy for large datasets

Ranking pipeline

Understand how Meilisearch ranks search results

Configure search cutoff

Set time limits to guarantee consistent response times

Search API reference

Full API reference for the search endpoint

Capabilities

Full-text search

Hybrid and semantic search

Geo search

Conversational search

Multi-search

Filtering, sorting, and faceting

Personalization

Analytics

Security and tenant tokens

Search rules

Platform

Indexing

How it works

Basic usage

Understanding performance stages

Top-level stages

Search sub-stages

Federated search stages

Multi-search

Federated search

Similar documents

Practical tips

Identify the bottleneck

Compare before and after

Disable in production

Performance tuning

Ranking pipeline

Configure search cutoff

Search API reference

​How it works

​Basic usage

​Understanding performance stages

​Top-level stages

​Search sub-stages

​Federated search stages

​Multi-search

​Federated search

​Similar documents

​Practical tips

​Identify the bottleneck

​Compare before and after

​Disable in production

Performance tuning

Ranking pipeline

Configure search cutoff

Search API reference

How it works

Basic usage

Understanding performance stages

Top-level stages

Search sub-stages

Federated search stages

Multi-search

Federated search

Similar documents

Practical tips

Identify the bottleneck

Compare before and after

Disable in production