OrderBy Expressions

Introduction

Hasura provides powerful tools to control sorting and ordering data. OrderByExpression types let you define customizable sorting rules for a type.

How OrderByExpressions work

There are two types of OrderByExpressions:

Type	Description
Scalar	This specifies how a user is able to order a scalar field.
Object	This specifies how fields of a type can be ordered.

Examples

Scalar

This specifies how a user is able to order a scalar field. For instance, you might want to say that a user can only sort a String type in ascending order instead of both ascending and descending order. You can do that with the following metadata:

kind: OrderByExpression
version: v1
definition:
  name: String_orderby_exp_asc
  operand:
    scalar:
      orderedType: String
      enableOrderByDirections:
        enableSpecific:
          - Asc
  graphql:
    expressionTypeName: StringOrderByExp

Object

An object OrderByExpression is used to define how fields of a type can be ordered. You can specify which OrderByExpression is used to order each field or relationship, and then defer the mappings of individual scalar types to those OrderByExpressions.

kind: OrderByExpression
version: v1
definition:
  name: Album_orderby_exp
  operand:
    object:
      orderedType: Album
      orderableFields:
        - fieldName: AlbumId
          orderByExpression: Int_orderby_exp
        - fieldName: ArtistId
          orderByExpression: Int_orderby_exp_asc
        - fieldName: Address
          orderByExpression: Address_orderby_exp
      orderableRelationships:
        - relationshipName: artist
          orderByExpression: Artist_orderby_exp
        - relationshipName: genre
  graphql:
    expressionTypeName: Album_orderby_Exp

Note here that we can specify different orderBy operators for AlbumId and ArtistId by using different OrderByExpressions for them. We are also able to define ordering on nested objects such as Address.

---

Metadata structure

OrderByExpression

Definition of an order by expression on an OpenDD type.

Key	Value	Required	Description
kind	OrderByExpression	true
version	v1	true
definition	OrderByExpressionV1	true	Definition of a type representing an order by expression on an OpenDD type.

Examples:

kind: OrderByExpression
version: v1
definition:
  name: Album_order_by_exp
  operand:
    object:
      orderedType: Album
      orderableFields:
        - fieldName: AlbumId
          orderByExpression: Int_order_by_exp
        - fieldName: ArtistId
          orderByExpression: Int_order_by_exp
        - fieldName: Address
          orderByExpression: Address_order_by_default_exp
      orderableRelationships:
        - relationshipName: artist
          orderByExpression: Artist_order_by_default_exp
  graphql:
    expressionTypeName: App_Album_order_by_exp
  description: Order by expression for Albums

kind: OrderByExpression
version: v1
definition:
  name: Int_order_by_exp
  operand:
    scalar:
      orderedType: Int
      enableOrderByDirections:
        enableAll: true
  graphql:
    expressionTypeName: App_Int_order_by_exp
  description: Order by expression for Int

OrderByExpressionV1

Definition of a type representing an order by expression on an OpenDD type.

Key	Value	Required	Description
name	OrderByExpressionName	true	The name used to refer to this expression. This name is unique only in the context of the orderedType
operand	OrderByExpressionOperand	true	The type that this expression applies to.
graphql	OrderByExpressionGraphQlConfiguration / null	false	Configuration for how this order by expression should appear in the GraphQL schema.
description	string / null	false	The description of the order by expression.

OrderByExpressionGraphQlConfiguration

GraphQL configuration settings for a type representing an order by expression on an OpenDD type.

Key	Value	Required	Description
expressionTypeName	GraphQlTypeName	true	The name of a GraphQL type.

GraphQlTypeName

The name of a GraphQL type.

Value: string

OrderByExpressionOperand

Configuration for object or scalar order by expression

Must have exactly one of the following fields:

Key	Value	Required	Description
object	OrderByExpressionObjectOperand	false	Definition of an type representing an order by expression on an OpenDD object type.
scalar	OrderByExpressionScalarOperand	false	Definition of a type representing an order by expression on an OpenDD scalar type.

OrderByExpressionScalarOperand

Definition of a type representing an order by expression on an OpenDD scalar type.

Key	Value	Required	Description
orderedType	TypeName	true	The type that this expression applies to.
enableOrderByDirections	EnableAllOrSpecific	true	Order by directions supported by this scalar type.

EnableAllOrSpecific

Enable all or specific values.

Must have exactly one of the following fields:

Key	Value	Required	Description
enableAll	boolean	false
enableSpecific	[OrderByDirection]	false

OrderByDirection

Value: Asc / Desc

TypeName

The type that this expression applies to.

One of the following values:

Value	Description
InbuiltType	An inbuilt primitive OpenDD type.
CustomTypeName

InbuiltType

An inbuilt primitive OpenDD type.

Value: ID / Int / Float / Boolean / String

OrderByExpressionObjectOperand

Definition of an type representing an order by expression on an OpenDD object type.

Key	Value	Required	Description
orderedType	CustomTypeName	true	The type that this expression applies to.
orderableFields	[OrderByExpressionOrderableField]	true	Orderable fields of the orderedType
orderableRelationships	[OrderByExpressionOrderableRelationship]	true	Orderable relationships

OrderByExpressionOrderableRelationship

Definition of a relationship in a type representing an order by expression on an OpenDD type.

Key	Value	Required	Description
relationshipName	RelationshipName	true	The name of the relationship.
orderByExpression	OrderByExpressionName / null	false	The OrderByExpression to use for this relationship. This is optional for model relationships. If not specified we use the model's OrderByExpression configuration. For local command relationships this is required.

RelationshipName

The name of the GraphQL relationship field.

Value: string

OrderByExpressionOrderableField

Definition of a field in a type representing an order by expression on an OpenDD type.

Key	Value	Required	Description
fieldName	FieldName	true
orderByExpression	OrderByExpressionName	true	OrderByExpression to use for this field.

FieldName

The name of a field in a user-defined object type.

Value: string

CustomTypeName

The name of a user-defined type.

Value: string

OrderByExpressionName

The name of an order by expression.

Value: string