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.
Search an index with full-text, filtered, or hybrid semantic queries.
Request body
| Parameter | Type | Description |
|---|---|---|
| q optional | string | Search query text. Empty string returns all documents (useful with filters). Default: "" |
| filter optional | string | Filter expression to narrow results. See the Filtering guide. |
| sort optional | string[] | Sort fields with direction, e.g. ["price:asc", "title:desc"]. |
| limit optional | number | Maximum number of hits to return. Default: 20 |
| offset optional | number | Number of hits to skip (for pagination). Default: 0 |
| facets optional | string[] | Fields to compute facet distributions for. |
| attributes_to_retrieve optional | string[] | Only return these fields in each hit (sparse fieldset). |
| show_ranking_score optional | boolean | Include a _rankingScore field in each hit. Default: false |
Example
curl -X POST https://search.example.com/v1/indices/products/search \ -H "Authorization: Bearer pk_search_live_..." \ -H "Content-Type: application/json" \ -d '{ "q": "running shoes", "filter": "brand = '\''Nike'\'' AND price < 15000", "sort": ["price:asc"], "facets": ["brand", "category"], "limit": 10 }'
SDK
const results = await idx.search('running shoes', { filter: "brand = 'Nike' AND price < 15000", sort: ['price:asc'], facets: ['brand', 'category'], limit: 10, });
Response 200 OK
{
"hits": [
{
"id": "1",
"title": "Nike Air Zoom",
"brand": "Nike",
"price": 12000
}
],
"facet_distribution": {
"brand": { "Nike": 42, "Adidas": 28 },
"category": { "Shoes": 60, "Apparel": 10 }
},
"total_hits": 42,
"processing_time_ms": 12,
"limit": 10,
"offset": 0,
"query": "running shoes",
"query_id": "qry_a1b2c3d4e5f6g7h8"
}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.
{ "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.
{
"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.
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.