Ordering results in GraphQL (orderBy)

Ordering defines the sequence of returned records and underpins stable pagination. In GraphQL, Data API builder (DAB) uses the orderBy argument to sort results before applying first or after. If you omit orderBy, DAB defaults to sorting by the primary key (ascending).

Go to the REST version of this document.

Overview

Usage pattern

query {
  books(orderBy: { year: DESC, title: ASC }, first: 5) {
    items {
      id
      title
      year
    }
  }
}

Conceptual SQL

SELECT TOP (5)
  id,
  sku_title AS title,
  year
FROM dbo.books
ORDER BY year DESC, sku_title ASC, id ASC;

Sample response

{
  "data": {
    "books": {
      "items": [
        { "id": 7, "title": "Dune Messiah", "year": 1969 },
        { "id": 6, "title": "Dune", "year": 1965 },
        { "id": 3, "title": "Foundation", "year": 1951 },
        { "id": 1, "title": "I, Robot", "year": 1950 },
        { "id": 8, "title": "The Martian Chronicles", "year": 1950 }
      ]
    }
  }
}

Field behavior

Example ignoring a field

query {
  books(orderBy: { title: null, id: DESC }) {
    items { id title }
  }
}

Invalid structures

GraphQL forbids logical operators (and, or) inside orderBy. For example, the following produces a validation error:

books(orderBy: { or: { id: ASC } })

Example using a variable

query ($dir: OrderBy) {
  books(orderBy: { id: $dir }, first: 4) {
    items { id title }
  }
}

Variables

{ "dir": "DESC" }

Relevant configuration

{
  "entities": {
    "Book": {
      "source": {
        "object": "dbo.books",
        "type": "table"
      },
      "mappings": {
        "sku_title": "title"
      }
    }
  }
}

Example configuration

{
  "runtime": {
    "pagination": {
      "default-page-size": 100,
      "max-page-size": 100000
    }
  },
  "entities": {
    "Book": {
      "source": {
        "type": "table",
        "object": "dbo.books"
      },
      "mappings": {
        "sku_title": "title",
        "sku_price": "price"
      },
      "relationships": {
        "book_category": {
          "cardinality": "one",
          "target.entity": "Category",
          "source.fields": [ "category_id" ],
          "target.fields": [ "id" ]
        }
      }
    },
    "Category": {
      "source": {
        "type": "table",
        "object": "dbo.categories"
      },
      "relationships": {
        "category_books": {
          "cardinality": "many",
          "target.entity": "Book",
          "source.fields": [ "id" ],
          "target.fields": [ "category_id" ]
        }
      }
    }
  }
}

See also