.. _sort: 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 :ref:`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-fields: Sort object fields ++++++++++++++++++ .. list-table:: :header-rows: 1 :widths: 22 22 56 * - 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: .. TESTED_EXAMPLE: sort_1 .. code-block:: json [{ "FindEntity": { "with_class": "Person", "sort": "name", "results": { "list": ["name"] } } }] Specify the order +++++++++++++++++ The results can be sorted by a value in the specified order: .. TESTED_EXAMPLE: sort_2 .. code-block:: json [{ "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: .. TESTED_EXAMPLE: sort_3 .. code-block:: json [{ "FindEntity": { "with_class": "Person", "sort": [{ "key": "name", "order": "descending" }, { "key": "age", "order": "ascending" }], "results": { "list": ["name"] } } }] Sort by an expression +++++++++++++++++++++ Descending order ranks :ref:`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**. .. code-block:: json [{ "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 .. TESTED_EXAMPLE: sort_4 .. code-block:: json [{ "FindImage": { "constraints": ["$year_captured", ">=", 1870], "blobs": false, "sort": "year_captured", "results": { "list": ["artist", "year_captured", "event"] } } }] Response: .. TESTED_EXAMPLE: sort_4_response .. code-block:: json [{ "FindImage": { "entities": [{ "_class": "Images", "artist": "Alice", "event": "April Festival", "year_captured": 1874 }, { "_class": "Images", "artist": "Alice", "event": "April Festival", "year_captured": 1875 }, { "_class": "Images", "artist": "Bob", "event": "June Festival", "year_captured": 1875 }, { "_class": "Images", "artist": "Alice", "event": "April Festival", "year_captured": 1875 }, { "_class": "Images", "artist": "Bob", "event": "April Festival", "year_captured": 1876 }, { "_class": "Images", "artist": "Alice", "event": "June Festival", "year_captured": 1876 }, { "_class": "Images", "artist": "Bob", "event": "April Festival", "year_captured": 1876 }, { "_class": "Images", "artist": "Bob", "event": "April Festival", "year_captured": 1876 }, { "_class": "Images", "artist": "Alice", "event": "June Festival", "year_captured": 1876 }, { "_class": "Images", "artist": "Bob", "event": "April Festival", "year_captured": 1876 }], "returned": 10, "status": 0 } }] Single property in descending order .. TESTED_EXAMPLE: sort_5 .. code-block:: json [{ "FindImage": { "constraints": ["$year_captured", ">=", 1870], "blobs": false, "sort": { "key": "year_captured", "order": "descending" }, "results": { "list": ["artist", "year_captured", "event"] } } }] Response: .. TESTED_EXAMPLE: sort_5_response .. code-block:: json [{ "FindImage": { "entities": [{ "_class": "Images", "artist": "Bob", "event": "April Festival", "year_captured": 1876 }, { "_class": "Images", "artist": "Alice", "event": "June Festival", "year_captured": 1876 }, { "_class": "Images", "artist": "Bob", "event": "April Festival", "year_captured": 1876 }, { "_class": "Images", "artist": "Bob", "event": "April Festival", "year_captured": 1876 }, { "_class": "Images", "artist": "Alice", "event": "June Festival", "year_captured": 1876 }, { "_class": "Images", "artist": "Bob", "event": "April Festival", "year_captured": 1876 }, { "_class": "Images", "artist": "Alice", "event": "April Festival", "year_captured": 1875 }, { "_class": "Images", "artist": "Bob", "event": "June Festival", "year_captured": 1875 }, { "_class": "Images", "artist": "Alice", "event": "April Festival", "year_captured": 1875 }, { "_class": "Images", "artist": "Alice", "event": "April Festival", "year_captured": 1874 }], "returned": 10, "status": 0 } }] Sorting using multiple properties: .. TESTED_EXAMPLE: sort_6 .. code-block:: json [{ "FindImage": { "constraints": ["$year_captured", ">=", 1870], "blobs": false, "sort": [{ "key": "year_captured", "order": "descending" }, { "key": "artist", "order": "ascending" }], "results": { "list": ["artist", "year_captured", "event"] } } }] Response: .. TESTED_EXAMPLE: sort_6_response .. code-block:: json [{ "FindImage": { "entities": [{ "_class": "Images", "artist": "Alice", "event": "June Festival", "year_captured": 1876 }, { "_class": "Images", "artist": "Alice", "event": "June Festival", "year_captured": 1876 }, { "_class": "Images", "artist": "Bob", "event": "April Festival", "year_captured": 1876 }, { "_class": "Images", "artist": "Bob", "event": "April Festival", "year_captured": 1876 }, { "_class": "Images", "artist": "Bob", "event": "April Festival", "year_captured": 1876 }, { "_class": "Images", "artist": "Bob", "event": "April Festival", "year_captured": 1876 }, { "_class": "Images", "artist": "Alice", "event": "April Festival", "year_captured": 1875 }, { "_class": "Images", "artist": "Alice", "event": "April Festival", "year_captured": 1875 }, { "_class": "Images", "artist": "Bob", "event": "June Festival", "year_captured": 1875 }, { "_class": "Images", "artist": "Alice", "event": "April Festival", "year_captured": 1874 }], "returned": 10, "status": 0 } }]