Skip to main content

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.

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.

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​

Use descending order to rank text search scores from highest to lowest. Repeat the expression in sort when also returning it through results.expressions.

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

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
    }
}]