Request Sort
Use the sort_by parameter to order search results by specified fields with optional tie-breaking. You can sort by up to 3 fields — if the first field has the same values, the second field is used to break the tie, and so on.
To discover which fields support sorting, list indexed fields and use entries with sortable: true (enable sorting when you configure indexable fields if needed).
Where the Request Sort Ranks
The request sort is the request_sort criterion in the Ranking Order. In the default Ranking Order it ranks first, before boosts and text relevance.
- Each
sort_byfield takes one of the three sort positions. A two-fieldsort_byleaves one position for boosts or text relevance, and a three-fieldsort_byleaves none. - A search profile can rank attributes, boosts, or text relevance above the request sort. Then the request sort only orders products those criteria leave tied, and its later fields can be cut.
- When an attribute above the request sort names the same field, the attribute's direction is used.
Sort Order
Append :asc or :desc to each field:
| Suffix | Direction |
|---|---|
:asc | Ascending (A–Z, 0–9, low to high) |
:desc | Descending (Z–A, 9–0, high to low) |
Sortable Fields
Always sortable:
price.amount— product price as an integer amountprice.float_price— product price as a floatcreated_at— when the product was createdupdated_at— when the product was last updated- Any
integerorfloattype indexable field
Conditionally sortable:
- String fields can be enabled for sorting, but require additional indexing overhead.
- Date flow/extension fields (flow fields with a
datetype, for exampleextensions.products(inventory).last_updated) are sortable only when created withsortable: true.
Enabling sorting on long string fields (for example, description) or in large datasets can significantly increase memory usage.
Examples
Single field:
price.amount:asc
Cheapest products first.
extensions.products(Specification).rating:desc
Highest rated first.
Multi-field tie-breaking:
price.amount:asc,extensions.products(Specification).rating:desc
Sorts by price (low to high), then by rating (high to low) for products with the same price.
Sorting Null, Empty, or Missing Values
Default behavior:
| Field type | Default placement of null/missing values |
|---|---|
| Numeric fields | Always placed at the end, regardless of sort order |
| String fields (ascending sort) | Empty, null, or missing values placed at the end |
| String fields (descending sort) | Empty, null, or missing values placed at the beginning |
Overriding default behavior:
Use the missing_values parameter to control placement of null, empty, or missing values:
| Value | Behavior |
|---|---|
missing_values: first | Places null/empty/missing values at the beginning |
missing_values: last | Places null/empty/missing values at the end |
Examples:
sort_by=price.float_price(missing_values: first):asc
Products without a price appear first.
sort_by=price.float_price(missing_values: last):desc
Products without a price appear last.
Price Sorting in Segmented Catalogs
Products can have multiple prices across different price books. The price used for sorting depends on the catalog rule configuration:
| Catalog type | Price used for sorting |
|---|---|
| Non-segmented catalogs | Default catalog prices |
| Segmented catalogs with 0 rule price books | Default catalog prices |
| Segmented catalogs with 1 rule price book | The price book's prices by default. Set force_use_default_price_for_faceting_and_sorting to true in the search profile to use default catalog prices instead. |
| Segmented catalogs with >=2 rule price books | Default catalog prices |
Products in a segmented catalog can have prices defined across many price books. The above limitations only apply to price books referenced in catalog rules.
Assortment vs price segmentation. Price books on a catalog rule control which price is used for sorting and faceting (see the table above). A search profile on the same catalog rule controls which products appear in search — for example via profile default filters. These levers are independent: you can segment prices, searchable assortment, or both on one rule. See How a search profile is chosen and Price Segmentation.
Sales prices are not supported. Only base prices are used for sorting.