Search

The search endpoint is the core of Skirre. It supports full-text search, filtering, sorting, faceting, and optional hybrid semantic ranking, all in a single request.


Filtering

Use the filter parameter to narrow results to documents matching specific criteria. Only fields declared as filterable_attributes in the index schema can be used.

See the Filtering guide for the full syntax reference, operators, and examples.

Sorting

Use the sort parameter with an array of field:direction strings. Only fields declared as sortable_attributes can be used.

text
{ "sort": ["price:asc", "title:desc"] }

Faceting

Request facet distributions by passing field names in the facets array. Skirre returns a count of documents per unique value for each faceted field.

Faceting works on filterable_attributes with no additional schema configuration needed.

Sparse Fields

Use attributes_to_retrieve to limit which fields are returned in each hit. This reduces response size and can improve performance.

text
{
  "q": "shoes",
  "attributes_to_retrieve": ["id", "title", "price"]
}

Ranking Score

Set show_ranking_score to true to include a _rankingScore field (0.0–1.0) in each hit. Useful for debugging relevance.

Tip
When hybrid search is enabled, the ranking score is a weighted combination of BM25 keyword score and embedding cosine similarity.

When document scoring is enabled, popularity signals from behavioral events are also blended into the final ranking. The ranking_weight setting controls how much popularity influences results relative to relevance.