Sort query results¶

The order_by argument¶

Results from your query can be sorted by using the order_by argument. The argument can be used to sort nested objects too.

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

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

The order_by argument takes an array of objects to allow sorting by multiple columns.

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.

You can see the complete specification of the order_by argument in the API reference.

The following are example queries for different sorting use cases:

Sorting objects¶

Example: Fetch a list of authors sorted by their names in an ascending order:

query {
  authors (
    order_by: {name: asc}
  ) {
    id
    name
  }
}

Sorting nested objects¶

Example: Fetch a list of authors sorted by their names with a list of their articles that is sorted by their rating:

query {
  authors (order_by: {name: asc}) {
    id
    name
    articles(order_by: {rating: desc}) {
      id
      title
      rating
    }
  }
}

Sorting based on nested object’s fields¶

Only columns from object relationships and aggregates from array relationships can be used for sorting.

query {
  articles (
    order_by: {author: {id: desc}}
  ) {
    id
    rating
    published_on
    author {
      id
      name
    }
  }
}

query {
  authors (
    order_by: {
      articles_aggregate: {count: desc}
    }
  ) {
    id
    name
    articles_aggregate {
      aggregate{
        count
      }
    }
  }
}

query {
  authors(
    order_by: {
      articles_aggregate: {
        max: {rating: asc_nulls_last}
      }
    }
  ) {
    id
    name
    articles_aggregate {
      aggregate{
        max {rating}
      }
    }
  }
}

Sorting by multiple fields¶

Example: Fetch a list of articles that is sorted by their rating (descending) and then on their published date (ascending with nulls first):

query {
  articles (
    order_by: [
      {rating: desc},
      {published_on: asc_nulls_first}
    ]
  ) {
    id
    rating
    published_on
  }
}