Multi-Sort API Functionality

The API supports a multi-sort feature that enables sorting results by multiple fields, each with its own sort order and mode. This provides fine-grained control over how results are ordered, especially when dealing with complex or multi-valued fields.

Syntax for Multi-Sort Parameters#

To use multi-sort, specify the following query parameters:

sortBy: Comma-separated list of fields to sort by.
sortOrder: Comma-separated list of sort orders (asc for ascending, desc for descending), corresponding to each field in sortBy.
sortMode: Comma-separated list of modes for summarizing multi-valued fields. Supported modes are min, max, avg, median, and sum.

If you provide fewer sortOrder or sortMode values than fields in sortBy, the API reuses the last specified value for the remaining fields. If a value is not specified at all, it defaults to asc for order and max for mode. Each field in sortBy can also include a subset using a colon, e.g., attribute:subset for sorting by a specific summary or source statistic of an attribute.

Example#

To sort results first by assembly_level (ascending, using the maximum value), then by chromosome_number (descending, using the minimum value):

?sortBy=assembly_level,chromosome_number&sortOrder=asc,desc&sortMode=max,min

Supported Fields#

Sorting can be applied to a wide range of fields, including scientific_name, taxon_id, assembly_id, feature_id, taxonomic ranks (e.g., domain, kingdom), taxon names, attributes, and metadata fields. For attributes and metadata, you can use subset syntax (e.g., attribute:mean, attribute:max) to target specific summary statistics or sources.

Backend Processing#

When a request includes multi-sort parameters, the backend:

Parses the sortBy, sortOrder, and sortMode parameters, splitting comma-separated strings into arrays.
Validates each value: sortOrder must be asc or desc; sortMode must be one of min, max, avg, median, or sum. If an invalid value is found, the API returns an error with details about the allowed values.
For each field in sortBy, assigns the corresponding order and mode from the arrays. If there are fewer orders or modes than fields, the last specified value is reused, or the default is applied.
Constructs an array of sort instructions, each with by (field), order, and mode. For fields with subset syntax, the backend maps the subset to the appropriate summary statistic or source key.
Translates these instructions into the underlying query engine's sort clauses, including nested filters for complex fields like attributes or taxonomic ranks.

If only a single field is specified, the backend returns a single sort object with optional order and mode.

Examples#

Sort by a single field (default order and mode):

?sortBy=scientific_name

Sorts by scientific_name in ascending order, using the maximum value if the field is multi-valued.

Sort by two fields with different orders:

?sortBy=assembly_level,chromosome_number&sortOrder=asc,desc

Sorts first by assembly_level ascending, then by chromosome_number descending. Both use the default mode (max).

Sort by two fields with different modes:

?sortBy=attribute1,attribute2&sortMode=min,max

Sorts by attribute1 using the minimum value, then by attribute2 using the maximum value. Both use ascending order by default.

Sort by an attribute with a subset:

?sortBy=genome_size:mean

Sorts by the mean value of the genome_size attribute.

Sort by three fields, reusing the last order and mode:

?sortBy=a,b,c&sortOrder=asc,desc&sortMode=max

Sorts by a ascending (max), b descending (max), and c descending (max).

Error Handling and Defaults#