GraphQL Queries

For each entity you define there will be two query fields - one for fetching a single record by a unique field and one for fetching a list of records.

For following entity:

import { SchemaDefinition as def } from '@contember/schema-definition'

export class Post {
  title = def.stringColumn().notNull()
  publishedAt = def.dateTimeColumn()
}

GraphQL schema will be similar to this:

query {
  getPost(by: PostUniqueWhere!): Post
  listPost(filter: PostWhere, orderBy: [PostOrderBy!], offset: Int, limit: Int): [Post]
}
input PostUniqueWhere {
  id: UUID
}
input PostOrderBy {
  id: OrderDirection
  publishedAt: OrderDirection
}
input PostWhere {
  id: UUIDCondition
  publishedAt: DateTimeCondition
  and: [PostWhere!]
  or: [PostWhere!]
  not: PostWhere
}
enum OrderDirection {
  asc
  desc
}

(some types are omitted in the example)

Fetching a single record#

If you know a field, which uniquely identifies a record, you can fetch a single record using a "get" query. If you define an entity called Post, there will be a field getPost with a parameter by.

query {
  getPost(by: {id: "c4ae3a0f-d91b-42a8-ad3c-5ca6b9f407c2"}) {
    title
    publishedAt    
  }
}

Fetching a list of records#

This kind of query offers more possibilities like filtering using complex conditions, ordering the result or paging using limit and offset.

query {
  listPost(
    filter: {publishedAt: {lte: "2019-12-20"}, category: {name: {eq: "Graphql"}}}
    orderBy: [{publishedAt: asc}]
    limit: 10
  ) {
    title
    publishedAt  
  } 
}

Filters#

filter argument allows you to apply a filter on the result. On each ordinary column (which is not a relation) you can set following conditions:

input StringCondition {
  and: [StringCondition!]
  or: [StringCondition!]
  not: StringCondition
  eq: String
  isNull: Boolean
  notEq: String
  in: [String!]
  notIn: [String!]
  lt: String
  lte: String
  gt: String
  gte: String
}

It is not possible to combine multiple fields in a single object. You have to wrap using and or or fields. For example, you want to select posts published in a range, then you create following condition:

query {
  listPost(
    filter: {
      publishedAt: {
        and: [
          {gte: "2019-12-20"}, 
          {lte: "2019-12-30"}
        ]
      }
    }
  ) {
    id
    title
  }
}

You can also filter over relations (both "has one" and "has many"), for example you want to only select posts written by "John Doe" and published with a "graphql" tag

query {
  listPost(
    filter: {
      author: {name: {eq: "John Doe"}}
      tag: {caption: {eq: "graphql"}}
    }
  ) {
    id
    title
  }
}

Sorting result#

Result set can be sorted by setting an orderBy argument. This argument can contain multiple sort fields and can also contain relations.

query {
  listPost(orderBy: [
    {author: {name: asc}}, 
    {publishedAt: desc}
  ]) {
    id
    title
  }
}

Records pagination#

There is an alternative to a list queries with a similar structure - a "paginate" queries. This query aims to be Relay compatible in the future.

In addition to fields for fetching a list of records, there is a pageInfo object with totalCount field. Using this value you can calculate total number of pages etc.

query {
  paginatePost(
    skip: 1, 
    first: 2, 
    filter: {author: {name: {eq: "John Doe"}}}, 
    orderBy: [{publishedAt: asc}]
  ) {
   pageInfo {
    totalCount
   }
   edges {
    node {
     id
     title
     author {
      name
     }
    }
   }
  }
}

Syntax for filtering and sorting is the same you know from "list" query. Parameters for pagination (skip, first) follows Relay specification.

Cursor based pagination is currently not possible.

Nested objects#

In a single query you can traverse across all the relations of given record.

query {
  listPost {
    id
    title
    category {
      name
    }
    author {
      name
    }
  }
}

on "has many" relations, you can also set a filter, orderBy and limit with an offset.

Transactions#

A transaction is NOT automatically started for queries. This results in a better performance, but it may cause an inconsistency in a result.

To enable transactions, wrap queries into a transaction field:

query {
  transaction {
    listPost {
      title
    }
    listAuthor {
      name
    }
  }
}