Sorting

Control the order of search results using field values, text relevance, geographic distance, and decay functions. Multiple sort fields are applied in order as tiebreakers.

Basic Syntax

sort_by=field_name:asc|desc[,field_name:asc|desc,...]

Sort by Field

Sort by any numeric field with sort: true in the schema:

sort_by=price:asc
sort_by=price:desc,rating:desc

Sort by Text Relevance

Use the special _text_match field to sort by BM25F relevance score:

sort_by=_text_match:desc,price:asc

This is the default sort order when q is provided and sort_by is not specified.

Sort by Group Count

When using group_by, sort groups by the number of matching documents:

sort_by=_group_found:desc

Sort by Vector Distance

When using vector_query, sort results by vector similarity distance:

sort_by=_vector_distance:asc

Lower distance = more similar. This is useful as a tiebreaker when combining vector search with other criteria. Requires vector_query to be set.

Geo Distance Sort

Sort by distance from a geographic point (nearest first):

sort_by=location(40.7128, -74.0060):asc

The location field must be a geopoint type. Distance is calculated in kilometers. No sort: true needed on geopoint fields.

Decay Functions

Decay sorting assigns scores that decrease with distance from an origin value. This is useful for time-based relevance (boost recent documents) or distance-based scoring.

sort_by=field_name(origin:VALUE,func:FUNC,scale:VALUE[,decay:VALUE][,offset:VALUE]):asc|desc

Parameters

Parameter	Required	Description
`origin`	Yes	Reference point. Documents at this value get the maximum score.
`func`	Yes	Decay function: `gauss`, `linear`, `exp`, or `diff`.
`scale`	Yes	Distance scale factor. Determines how quickly the score decays.
`decay`	No	Base for exponential function (default: `0.5`).
`offset`	No	Decay starts after this distance from origin (default: `0`).

Decay Functions

Function	Formula	Description
`gauss`	exp(-d² / 2s²)	Gaussian (bell curve) decay from origin
`linear`	max(0, 1 - d/s)	Linear decay, reaching zero at scale distance
`exp`	decay^(d/s)	Exponential decay using the `decay` base
`diff`	1 / (1 + d)	Reciprocal decay (smooth, never reaches zero)

Example

Boost recently created documents using Gaussian decay on a Unix timestamp field:

sort_by=created_at(origin:1710000000,func:gauss,scale:86400):desc

This gives the highest score to documents created closest to the origin timestamp, with the score decaying over a scale of 86,400 seconds (one day).

Multiple Sort Fields

Chain multiple sort criteria as tiebreakers:

sort_by=_text_match:desc,price:asc,rating:desc

Documents are first sorted by text relevance, then by price (ascending) for ties, then by rating (descending) for further ties.

Sort Length Limits

The sort_by expression is limited to 2,048 characters.