.. _sorting:

=========
Sorting
=========


Sorting in ``qalx`` works using a double underscore (`__`) syntax to allow you
to sort using multiple values in your data


Basic Usage
-----------

To sort your data coming from ``qalx``, provide the ``sort`` keyword argument for the
data you wish to sort by to the ``find()`` method

.. code:: python

    qalx = QalxSession()
    qalx.item.add(data={"thickness": 5},)
    qalx.item.add(data={"thickness": 20},)

    qalx.item.find(sort="data__thickness")

To sort descending simply supply a ``-`` prefix

.. code:: python

    qalx = QalxSession()
    qalx.item.add(data={"thickness": 5},)
    qalx.item.add(data={"thickness": 20},)

    qalx.item.find(sort="-data__thickness")

Sorting by Created
------------------

As the created datetime isn't a nested field you can just supply that as a single
argument

.. code:: python

    qalx = QalxSession()

    qalx.item.find(sort="created")


Combining Sort Operators
------------------------

Just like with :ref:`searching` you can combine sort operators and use the
double underscore (``__``) syntax to sort by specific data values

.. code:: python

    qalx = QalxSession()
    qalx.item.add(data={"thickness": 5}, meta={'owner': {'name': 'Joe Bloggs'}})
    qalx.item.add(data={"thickness": 20}, meta={'owner': {'name': 'Fred Bloggs'}})

    qalx.item.find(sort=["meta__owner__name",
                         "-data__thickness",
                         "created"])


Available Sort Fields
-----------------------

The following field keyword arguments are available to sort by for each entity

Item
====
* data
* meta
* file
* created

Set
===
* meta
* created

Group
=====
* meta
* created

Bot
===
* config
* meta
* created

Queue
=====
* parameters
* meta
* created

Blueprint
=========
* schema
* entity_type
* meta
* created