2018-09-11 14:11:24 +03:00
|
|
|
Sort query results
|
|
|
|
==================
|
2018-12-03 15:12:24 +03:00
|
|
|
|
|
|
|
.. contents:: Table of contents
|
|
|
|
:backlinks: none
|
2019-09-05 17:53:50 +03:00
|
|
|
:depth: 2
|
2018-12-03 15:12:24 +03:00
|
|
|
:local:
|
|
|
|
|
2019-02-06 09:39:36 +03:00
|
|
|
Results from your query can be sorted by using the ``order_by`` argument. The argument can be used to sort nested
|
2018-09-11 14:11:24 +03:00
|
|
|
objects too.
|
|
|
|
|
2019-09-11 10:17:14 +03:00
|
|
|
The sort order (ascending vs. descending) is set by specifying the ``asc`` or ``desc``
|
|
|
|
enum value for the column name in the ``order_by`` input object, e.g. ``{name: desc}``.
|
2018-09-11 14:11:24 +03:00
|
|
|
|
2019-02-06 09:39:36 +03:00
|
|
|
By default, for ascending ordering ``null`` values are returned at the end of the results and for descending
|
|
|
|
ordering ``null`` values are returned at the start of the results. ``null`` values can be fetched first on
|
|
|
|
ascending ordering by specifying ``asc_nulls_first`` and last on descending ordering by specifying
|
|
|
|
``desc_nulls_last`` enum value e.g. ``{name: desc_nulls_last}``.
|
2018-09-11 14:11:24 +03:00
|
|
|
|
2018-10-26 14:57:33 +03:00
|
|
|
The ``order_by`` argument takes an array of objects to allow sorting by multiple columns.
|
|
|
|
|
2019-03-13 13:04:40 +03:00
|
|
|
You can also use nested objects' fields to sort the results. Only **columns from object relationships** and
|
|
|
|
**aggregates from array relationships** can be used for sorting.
|
2018-10-26 14:57:33 +03:00
|
|
|
|
2019-02-06 09:39:36 +03:00
|
|
|
You can see the complete specification of the ``order_by`` argument in the :ref:`API reference <OrderByExp>`.
|
2018-09-11 14:11:24 +03:00
|
|
|
|
|
|
|
The following are example queries for different sorting use cases:
|
|
|
|
|
2018-12-03 15:12:24 +03:00
|
|
|
Sorting objects
|
|
|
|
---------------
|
|
|
|
|
2019-09-11 10:17:14 +03:00
|
|
|
**Example:** Fetch a list of authors sorted by their names in an ascending order:
|
2018-09-11 14:11:24 +03:00
|
|
|
|
|
|
|
.. graphiql::
|
|
|
|
:view_only:
|
|
|
|
:query:
|
|
|
|
query {
|
2019-02-06 09:39:36 +03:00
|
|
|
author (
|
2018-10-26 14:57:33 +03:00
|
|
|
order_by: {name: asc}
|
2018-09-11 14:11:24 +03:00
|
|
|
) {
|
|
|
|
id
|
|
|
|
name
|
|
|
|
}
|
|
|
|
}
|
|
|
|
:response:
|
|
|
|
{
|
|
|
|
"data": {
|
|
|
|
"author": [
|
|
|
|
{
|
|
|
|
"id": 5,
|
|
|
|
"name": "Amii"
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 4,
|
|
|
|
"name": "Anjela"
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 8,
|
|
|
|
"name": "April"
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 2,
|
|
|
|
"name": "Beltran"
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 7,
|
|
|
|
"name": "Berti"
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 6,
|
|
|
|
"name": "Corny"
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2019-04-19 13:48:18 +03:00
|
|
|
.. _nested_sort:
|
|
|
|
|
2018-12-03 15:12:24 +03:00
|
|
|
Sorting nested objects
|
|
|
|
----------------------
|
2019-03-13 13:04:40 +03:00
|
|
|
**Example:** Fetch a list of authors sorted by their names with a list of their articles that is sorted by
|
|
|
|
their rating:
|
2018-09-11 14:11:24 +03:00
|
|
|
|
|
|
|
.. graphiql::
|
|
|
|
:view_only:
|
|
|
|
:query:
|
|
|
|
query {
|
2019-02-06 09:39:36 +03:00
|
|
|
author (order_by: {name: asc}) {
|
2018-09-11 14:11:24 +03:00
|
|
|
id
|
|
|
|
name
|
2018-10-26 14:57:33 +03:00
|
|
|
articles(order_by: {rating: desc}) {
|
2018-09-11 14:11:24 +03:00
|
|
|
id
|
|
|
|
title
|
|
|
|
rating
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
:response:
|
|
|
|
{
|
|
|
|
"data": {
|
|
|
|
"author": [
|
|
|
|
{
|
|
|
|
"id": 5,
|
|
|
|
"name": "Amii",
|
|
|
|
"articles": [
|
|
|
|
{
|
|
|
|
"rating": 5,
|
|
|
|
"id": 17,
|
|
|
|
"title": "montes nascetur ridiculus"
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"rating": 3,
|
|
|
|
"id": 12,
|
|
|
|
"title": "volutpat quam pede"
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"rating": 2,
|
|
|
|
"id": 4,
|
|
|
|
"title": "vestibulum ac est"
|
|
|
|
}
|
|
|
|
]
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 4,
|
|
|
|
"name": "Anjela",
|
|
|
|
"articles": [
|
|
|
|
{
|
|
|
|
"rating": 4,
|
|
|
|
"id": 3,
|
|
|
|
"title": "amet justo morbi"
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"rating": 1,
|
|
|
|
"id": 1,
|
|
|
|
"title": "sit amet"
|
|
|
|
}
|
|
|
|
]
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 8,
|
|
|
|
"name": "April",
|
|
|
|
"articles": [
|
|
|
|
{
|
|
|
|
"rating": 4,
|
|
|
|
"id": 13,
|
|
|
|
"title": "vulputate elementum"
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"rating": 2,
|
|
|
|
"id": 20,
|
|
|
|
"title": "eu nibh"
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2019-02-06 09:39:36 +03:00
|
|
|
Sorting based on nested object's fields
|
|
|
|
---------------------------------------
|
2019-03-13 13:04:40 +03:00
|
|
|
Only **columns from object relationships** and **aggregates from array relationships** can be used for sorting.
|
2019-02-06 09:39:36 +03:00
|
|
|
|
2019-09-11 10:17:14 +03:00
|
|
|
For object relationships
|
2019-03-13 13:04:40 +03:00
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
For object relationships only columns can be used for sorting.
|
|
|
|
|
2019-09-11 10:17:14 +03:00
|
|
|
**Example:** Fetch a list of articles that are sorted by their author's ids in descending order:
|
2018-10-26 14:57:33 +03:00
|
|
|
|
|
|
|
.. graphiql::
|
|
|
|
:view_only:
|
|
|
|
:query:
|
|
|
|
query {
|
2019-02-06 09:39:36 +03:00
|
|
|
article (
|
2018-10-26 14:57:33 +03:00
|
|
|
order_by: {author: {id: desc}}
|
|
|
|
) {
|
|
|
|
id
|
|
|
|
rating
|
|
|
|
published_on
|
|
|
|
author {
|
|
|
|
id
|
|
|
|
name
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
:response:
|
|
|
|
{
|
|
|
|
"data": {
|
|
|
|
"article": [
|
|
|
|
{
|
|
|
|
"id": 3,
|
|
|
|
"title": "Article 3",
|
|
|
|
"content": "Sample article content 3",
|
|
|
|
"author": {
|
|
|
|
"id": 2,
|
|
|
|
"name": "Author 2"
|
|
|
|
}
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 1,
|
|
|
|
"title": "Article 1",
|
|
|
|
"content": "Sample article content 1",
|
|
|
|
"author": {
|
|
|
|
"id": 1,
|
|
|
|
"name": "Author 1"
|
|
|
|
}
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 2,
|
|
|
|
"title": "Article 2",
|
|
|
|
"content": "Sample article content 2",
|
|
|
|
"author": {
|
|
|
|
"id": 1,
|
|
|
|
"name": "Author 1"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2019-09-11 10:17:14 +03:00
|
|
|
For array relationships
|
2019-03-13 13:04:40 +03:00
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
For array relationships only aggregates can be used for sorting.
|
2019-02-06 09:39:36 +03:00
|
|
|
|
2019-03-13 13:04:40 +03:00
|
|
|
**Example:** Fetch a list of authors sorted in descending order of their article count:
|
2018-12-12 15:58:39 +03:00
|
|
|
|
|
|
|
.. graphiql::
|
|
|
|
:view_only:
|
|
|
|
:query:
|
|
|
|
query {
|
2019-02-06 09:39:36 +03:00
|
|
|
author (
|
2019-03-13 13:04:40 +03:00
|
|
|
order_by: {
|
|
|
|
articles_aggregate: {count: desc}
|
|
|
|
}
|
2019-02-06 09:39:36 +03:00
|
|
|
) {
|
2018-12-12 15:58:39 +03:00
|
|
|
id
|
|
|
|
name
|
|
|
|
articles_aggregate {
|
|
|
|
aggregate{
|
|
|
|
count
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
:response:
|
|
|
|
{
|
|
|
|
"data": {
|
|
|
|
"author": [
|
|
|
|
{
|
|
|
|
"id": 5,
|
|
|
|
"name": "Amii",
|
|
|
|
"articles_aggregate":{
|
|
|
|
"aggregate": {
|
|
|
|
"count": 3
|
|
|
|
}
|
|
|
|
}
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 4,
|
|
|
|
"name": "Anjela",
|
|
|
|
"articles_aggregate":{
|
|
|
|
"aggregate": {
|
|
|
|
"count": 2
|
|
|
|
}
|
|
|
|
}
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 8,
|
|
|
|
"name": "April",
|
|
|
|
"articles_aggregate":{
|
|
|
|
"aggregate": {
|
|
|
|
"count": 2
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2019-03-13 13:04:40 +03:00
|
|
|
**Example:** Fetch a list of authors sorted in increasing order of their highest article rating:
|
|
|
|
|
|
|
|
.. graphiql::
|
|
|
|
:view_only:
|
|
|
|
:query:
|
|
|
|
query {
|
|
|
|
author(
|
|
|
|
order_by: {
|
|
|
|
articles_aggregate: {
|
|
|
|
max: {rating: asc_nulls_last}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
) {
|
|
|
|
id
|
|
|
|
name
|
|
|
|
articles_aggregate {
|
|
|
|
aggregate{
|
|
|
|
max {rating}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
:response:
|
|
|
|
{
|
|
|
|
"data": {
|
|
|
|
"author": [
|
|
|
|
{
|
|
|
|
"id": 7,
|
|
|
|
"name": "Berti",
|
|
|
|
"articles_aggregate": {
|
|
|
|
"aggregate": {
|
|
|
|
"max": {
|
|
|
|
"rating": 2
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 2,
|
|
|
|
"name": "Beltran",
|
|
|
|
"articles_aggregate": {
|
|
|
|
"aggregate": {
|
|
|
|
"max": {
|
|
|
|
"rating": 3
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 8,
|
|
|
|
"name": "April",
|
|
|
|
"articles_aggregate": {
|
|
|
|
"aggregate": {
|
|
|
|
"max": {
|
|
|
|
"rating": 4
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 3,
|
|
|
|
"name": "Sidney",
|
|
|
|
"articles_aggregate": {
|
|
|
|
"aggregate": {
|
|
|
|
"max": {
|
|
|
|
"rating": 4
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 5,
|
|
|
|
"name": "Amii",
|
|
|
|
"articles_aggregate": {
|
|
|
|
"aggregate": {
|
|
|
|
"max": {
|
|
|
|
"rating": 5
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 9,
|
|
|
|
"name": "Ninnetta",
|
|
|
|
"articles_aggregate": {
|
|
|
|
"aggregate": {
|
|
|
|
"max": {
|
|
|
|
"rating": null
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2018-12-12 15:58:39 +03:00
|
|
|
|
2018-09-11 14:11:24 +03:00
|
|
|
Sorting by multiple fields
|
|
|
|
--------------------------
|
2019-03-13 13:04:40 +03:00
|
|
|
**Example:** Fetch a list of articles that is sorted by their rating (descending) and then on their published
|
|
|
|
date (ascending with nulls first):
|
2018-09-11 14:11:24 +03:00
|
|
|
|
|
|
|
.. graphiql::
|
|
|
|
:view_only:
|
|
|
|
:query:
|
|
|
|
query {
|
2019-02-06 09:39:36 +03:00
|
|
|
article (
|
|
|
|
order_by: [
|
|
|
|
{rating: desc},
|
|
|
|
{published_on: asc_nulls_first}
|
|
|
|
]
|
2018-09-11 14:11:24 +03:00
|
|
|
) {
|
|
|
|
id
|
|
|
|
rating
|
|
|
|
published_on
|
|
|
|
}
|
|
|
|
}
|
|
|
|
:response:
|
|
|
|
{
|
|
|
|
"data": {
|
|
|
|
"article": [
|
|
|
|
{
|
|
|
|
"id": 17,
|
|
|
|
"rating": 5,
|
|
|
|
"published_on": null
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 14,
|
|
|
|
"rating": 4,
|
|
|
|
"published_on": null
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 7,
|
|
|
|
"rating": 4,
|
|
|
|
"published_on": "2016-07-09"
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"id": 3,
|
|
|
|
"rating": 4,
|
|
|
|
"published_on": "2017-05-26"
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
2018-10-26 14:57:33 +03:00
|
|
|
}
|