# Placeholder Search

Placeholder search is a search request where the query string `q` is empty or missing. Instead of returning no results, Meilisearch returns documents from the index, respecting all other search parameters such as [filters](/content/docs/capabilities/filtering_sorting_faceting/getting_started/index.html), [sorting](/content/docs/capabilities/filtering_sorting_faceting/how_to/sort_results/index.html), and [facets](/content/docs/capabilities/filtering_sorting_faceting/how_to/filter_with_facets/index.html). This is useful when you want to display default content on a landing page, show trending items, or let users browse results before they start typing.

## How it works

When Meilisearch receives a search request with an empty query, it skips the text-matching phase entirely. Documents are returned in the order determined by the active [ranking rules](/content/docs/capabilities/full_text_search/relevancy/ranking_rules/index.html), with [custom ranking rules](/content/docs/capabilities/full_text_search/relevancy/custom_ranking_rules/index.html) and the `sort` parameter playing the most significant role. Since no query terms are involved, text-based ranking rules like `words`, `typo`, `proximity`, and `exactness` have no effect. Only `sort` and custom ranking rules influence the order of results.

## Basic example

Send a search request with an empty query string:

```bash
curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  --data-binary '{
    "q": ""
  }'
```

Meilisearch returns documents from the `movies` index in the default order.

## Placeholder search with filters and sorting

Placeholder search becomes more powerful when combined with filters and sorting. For example, you can show the highest-rated movies in a specific genre:

```bash
curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  --data-binary '{
    "q": "",
    "filter": "genres = Action",
    "sort": ["rating:desc"]
  }'
```

This returns all action movies sorted by rating, without requiring the user to type anything.

## Placeholder search with facets

You can also request facet distributions alongside a placeholder search to build category navigation:

```bash
curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  --data-binary '{
    "q": "",
    "facets": ["genres", "release_year"]
  }'
```

The response includes a `facetDistribution` object showing the count of documents for each facet value.

## Common use cases

- **Landing pages**: Show popular or recent items when a user first visits your search page
- **Category browsing**: Combine an empty query with filters to let users explore content by category
- **Default recommendations**: Sort by a custom ranking attribute like `popularity` to surface trending content
- **Faceted navigation**: Display facet counts to help users narrow down results before searching

## Pagination

Placeholder search supports the same pagination parameters as regular search. Use `offset` and `limit` (or `page` and `hitsPerPage`) to paginate through results:

```bash
curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  --data-binary '{
    "q": "",
    "limit": 20,
    "offset": 40
  }'
```

For a complete list of search parameters, see the [search API reference](/content/docs/reference/api/search/search-with-post/index.html).