Version: next

Queries

Graphback provides two query types for every model in the schema.

  • find<Type>s: fetch all or a subset of items through optional filtering, pagination and sorting.
  • get<Type>: fetch a single item by its unique ID.

Find

The find operation allows the client to fetch multiple items from the database, with optional filtering, pagination and ordering of the data allowing you to specify exactly the data you need.

The query follows the naming format find<Type>s:

type Query {
findNotes(filter: NoteFilter, page: PageRequest, orderBy: OrderByInput): NoteResultList!
}

Arguments:

  • filter: filter object to query specific data.
  • page: enables pagination of the data.
  • orderBy: sorts the data in ascending or descending order.

The items fetched by findNote are returned in a container type NoteResultList created by Graphback:

type NoteResultList {
# The notes are returned in the items field
items: [Note]!
# Offset specified in query
offset: Int
# Offset specified in query
limit: Int
# total count of notes in the database
count: Int
}

Example of a simple query to retrieve all notes:

query {
findNotes {
items {
id
title
likes
}
}
}

Filtering

Graphback generates all the appropriate schema elements from GraphQLCRUD and provides a mapping implementation for both PostgreSQL and MongoDB. This lets you perform simple or complex querying of your data directly from GraphQL queries.

Take an example Note model, which uses each of the built-in scalar types: ID, String, Boolean, Int, Float.

""" @model """
type Note {
id: ID!
title: String!
opened: Boolean
likes: Int
completedPercentage: Float
}

Graphback generates a filter input type for each model in the schema.

input NoteFilter {
id: IDInput
title: StringInput
opened: BooleanInput
likes: IntInput
completedPercentage: FloatInput
and: [NoteFilter!]
or: [NoteFilter!]
not: NoteFilter
}

So you can perform filtering of the data like this:

query {
findNotes(filter: {
title: {
contains: "emails"
},
opened: {
eq: false
},
likes: {
gt: 10
},
completedPercentage: {
between: [20, 40]
},
and: {
title: {
startsWith: "read"
}
},
or: {
likes: {
eq: 100
}
},
not: {
title: {
contains: "archived"
}
}
}) {
items {
id
title
likes
}
}
}

Operators

This is a list of all available filter operators.

OperatorMeaningScalars
eqEqual toAll
neNot equal toAll
ltLess thanAll
leLess than or equal toAll
gtGreater thanAll
gtGreater than or equal toAll
betweenBetween a range (of numbers)Int, Float
inIn a list of itemsAll
containsString containsString
startsWithString starts withString
endsWithString ends withString

Each field in the NoteFilter input maps to a generated scalar input. This specifies the operators available for that scalar.

input StringInput {
ne: String
eq: String
le: String
lt: String
ge: String
gt: String
in: [String!]
contains: String
startsWith: String
endsWith: String
}
input IDInput {
ne: ID
eq: ID
le: ID
lt: ID
ge: ID
gt: ID
in: [ID!]
}
input IntInput {
ne: Int
eq: Int
le: Int
lt: Int
ge: Int
gt: Int
in: [Int!]
between: [Int!]
}
input FloatInput {
ne: Float
eq: Float
le: Float
lt: Float
ge: Float
gt: Float
in: [Float!]
between: [Float!]
}
input BooleanInput {
ne: Boolean
eq: Boolean
}

Pagination

You can perform pagination with the page argument.

type PageRequest {
limit: Int
offset: Int
}
findNotes(page: {limit: 10, offset:4}) {
items {
id
}
}

Ordering

input OrderByInput {
field: String!
order: SortDirectionEnum = ASC
}
enum SortDirectionEnum {
DESC
ASC
}

To sort/order items by a certain field, use the orderBy argument.

findNotes(orderBy: {order: DESC, field: "likes"}) {
items {
id
}
}

Get

The get operation allows the client to fetch a single item from the database by its unique ID.

The query follows the naming format get<Type>:

type Query {
getNote(id: ID!): Note
}

Arguments:

  • id: The unique ID of the object. This will always be id: ID. The resolver will automatically map this to your primary key field.
"""
@model
"""
type User {
"""@id"""
email: String
name: String
}

Example of a query to retrieve a single user by their primary field (email):

getNote(id: "tommyshelby@gmail.com") {
id
email
name
}