sort

The sort parameter orders returned results by properties or value expressions.

sort can be specified as either a single value (a property name), an array of values (when sorting by multiple properties), or an object.

By default, results will be ordered in ascending order (lowest to highest). The order can be specified using the object variant.

A sort object specifies exactly one of key (a property name) or expression (a value expression from the constraint grammar), plus optional order. Expression sorting supports text scores and arithmetic, with no implicit relevance ordering. Output aliases from results.expressions are not property references. Expression sorting cannot accompany results.group. Sorting applies before offset and limit. Complete ties use ascending object ID. With group_by_source and per_group, sorting and pagination apply independently to each source group.

Sort object fields

Field	Type / required	Behavior
key	string / conditional	Required unless expression is set; selects a property. Cannot accompany expression.
expression	value expression / conditional	Required unless key is set; uses the constraint value-expression grammar. Cannot accompany key.
order	string / optional	Default ascending; accepts ascending or descending.
sequence	array of scalar values / optional	Omitted: ordinary value order. When supplied, ranks listed null/boolean/number/string/date values first in the given order; arbitrary JSON objects and nested arrays are rejected.

Sort by one property

Sort by one property in ascending order:

[{
    "FindEntity": {
        "with_class": "Person",
        "sort": "name",
        "results": {
            "list": ["name"]
        }
    }
}]

Specify the order

The results can be sorted by a value in the specified order:

[{
    "FindEntity": {
        "with_class": "Person",
        "sort": {
            "key": "name",
            "order": "descending"
        },
        "results": {
            "list": ["name"]
        }
    }
}]

Sort by multiple properties

The results can be sorted by the value of multiple properties, in the specified order:

[{
    "FindEntity": {
        "with_class": "Person",
        "sort": [{
            "key": "name",
            "order": "descending"
        }, {
            "key": "age",
            "order": "ascending"
        }],
        "results": {
            "list": ["name"]
        }
    }
}]

Sort by an expression

Descending order ranks text search scores from highest to lowest. Returning a score through results.expressions does not sort by it; the expression must also appear in sort.

[{
    "FindEntity": {
        "with_class": "Person",
        "constraints": [{"isimilarity": ["$name", "alen"]}, ">", 0],
        "sort": {
            "expression": {"isimilarity": ["$name", "alen"]},
            "order": "descending"
        },
        "results": {"list": ["name"]}
    }
}]

Sorting by an array element

A single expression such as {"at": ["$values", 0]} can use an array index that covers the constant position and has type_postings enabled. Field-free expressions may supply the position. The source must contain only native Array or missing values; computed and JSON sources retain ordinary expression sorting.

This optimization is most useful for small pages with a finite limit. Null elements, out-of-range positions, and missing properties sort as null; complete ties use ascending object ID. Query counts cover all filtered matches.

Multi-key sorts, broad pages, or disabling type_postings may reduce the performance benefit. Sort order and returned results remain the same.

Image examples

Single property

[{
    "FindImage": {
        "constraints": ["$year_captured", ">=", 1870],
        "blobs": false,
        "sort": "year_captured",
        "results": {
            "list": ["artist", "year_captured", "event"]
        }
    }
}]

Response:

[{
    "FindImage": {
        "entities": [{
            "artist": "Alice",
            "event": "April Festival",
            "year_captured": 1874
        }, {
            "artist": "Alice",
            "event": "April Festival",
            "year_captured": 1875
        }, {
            "artist": "Bob",
            "event": "June Festival",
            "year_captured": 1875
        }, {
            "artist": "Alice",
            "event": "April Festival",
            "year_captured": 1875
        }, {
            "artist": "Bob",
            "event": "April Festival",
            "year_captured": 1876
        }, {
            "artist": "Alice",
            "event": "June Festival",
            "year_captured": 1876
        }, {
            "artist": "Bob",
            "event": "April Festival",
            "year_captured": 1876
        }, {
            "artist": "Bob",
            "event": "April Festival",
            "year_captured": 1876
        }, {
            "artist": "Alice",
            "event": "June Festival",
            "year_captured": 1876
        }, {
            "artist": "Bob",
            "event": "April Festival",
            "year_captured": 1876
        }],
        "returned": 10,
        "status": 0
    }
}]

Single property in descending order

[{
    "FindImage": {
        "constraints": ["$year_captured", ">=", 1870],
        "blobs": false,
        "sort": {
            "key": "year_captured",
            "order": "descending"
        },
        "results": {
            "list": ["artist", "year_captured", "event"]
        }
    }
}]

Response:

[{
    "FindImage": {
        "entities": [{
            "artist": "Bob",
            "event": "April Festival",
            "year_captured": 1876
        }, {
            "artist": "Alice",
            "event": "June Festival",
            "year_captured": 1876
        }, {
            "artist": "Bob",
            "event": "April Festival",
            "year_captured": 1876
        }, {
            "artist": "Bob",
            "event": "April Festival",
            "year_captured": 1876
        }, {
            "artist": "Alice",
            "event": "June Festival",
            "year_captured": 1876
        }, {
            "artist": "Bob",
            "event": "April Festival",
            "year_captured": 1876
        }, {
            "artist": "Alice",
            "event": "April Festival",
            "year_captured": 1875
        }, {
            "artist": "Bob",
            "event": "June Festival",
            "year_captured": 1875
        }, {
            "artist": "Alice",
            "event": "April Festival",
            "year_captured": 1875
        }, {
            "artist": "Alice",
            "event": "April Festival",
            "year_captured": 1874
        }],
        "returned": 10,
        "status": 0
    }
}]

Sorting using multiple properties:

[{
    "FindImage": {
        "constraints": ["$year_captured", ">=", 1870],
        "blobs": false,
        "sort": [{
            "key": "year_captured",
            "order": "descending"
        }, {
            "key": "artist",
            "order": "ascending"
        }],
        "results": {
            "list": ["artist", "year_captured", "event"]
        }
    }
}]

Response:

[{
    "FindImage": {
        "entities": [{
            "artist": "Alice",
            "event": "June Festival",
            "year_captured": 1876
        }, {
            "artist": "Alice",
            "event": "June Festival",
            "year_captured": 1876
        }, {
            "artist": "Bob",
            "event": "April Festival",
            "year_captured": 1876
        }, {
            "artist": "Bob",
            "event": "April Festival",
            "year_captured": 1876
        }, {
            "artist": "Bob",
            "event": "April Festival",
            "year_captured": 1876
        }, {
            "artist": "Bob",
            "event": "April Festival",
            "year_captured": 1876
        }, {
            "artist": "Alice",
            "event": "April Festival",
            "year_captured": 1875
        }, {
            "artist": "Alice",
            "event": "April Festival",
            "year_captured": 1875
        }, {
            "artist": "Bob",
            "event": "June Festival",
            "year_captured": 1875
        }, {
            "artist": "Alice",
            "event": "April Festival",
            "year_captured": 1874
        }],
        "returned": 10,
        "status": 0
    }
}]