Queries
A GraphQL query is used for fetching data. This can be useful for verifying which data is stored for a given object class, or for a third party to export data from your solution.
Simple queries
The simplest query you can run is to specify the object class (known as an object type in GraphQL). For example, if you wanted to list all Projects in the database, you could write:
{
project
}
Note that the name of the object class is specified under Endpoint Name in the object class properties in Appfarm Create.
Click the Play button (or Cmd/Ctrl + Enter) to execute the query. The response will be displayed to the right.
The query editor will also edit your query to contain all the properties (fields in GraphQL) that are available to query:
{
project {
_id
title
description
createdDate
createdBy
status
projectNumber
projectDisplayName
af_createdDate
af_updatedDate
}
}
You can use these fields in your query to customize the response that you receive. For example, the following query will only return the id and title properties of each project:
{
project {
_id
title
}
}
To further refine your query you can include arguments, see advanced queries.
Reference objects
If a queried object references another object, or is referenced by another object, you can extract details about the other object.
For example, if you have projects with tasks, you might like to list out the tasks for a project, or obtain the project details for a given task.
// Return all projects, with their ID, title, and an array of associated tasks with each task's ID and title
{project {
_id
title
taskList {
_id
title
}
}}
// Return all tasks with their ID, title, and an object containing the title and description of the associated project
{task {
_id
title
project_reference {
title
description
}
}}
Advanced queries
More advanced query operators can be used to further customize the response. In the following examples, Book is queried in different ways.
Limit
Restrict the response to contain only n
objects.
// Return a maximum of 2 books, and only return the title
{
Book(limit: 2){
title
}
}
Skip
Skip the first n
objects in the response.
// Return every book after the first 2, and only return the title
{
Book(skip: 2){
title
}
}
Sort
Sort the response in ascending (ASC) or descending (DESC) order.
// Return all books, sorted in ascending order by number of pages
{
Book(sort: {pages: ASC}){
title
pages
}
}
Filter
Combine operators to filter the response.
// Return all books with more than 500 pages
{
Book(filter: {
pages: {gt: 500}
}){
title
pages
}
}
// Return all books with more than 500 pages, sorted by title
{
Book(
filter: {pages: {gt: 500}},
sort: {title: ASC}
){
title
pages
}
}
// Return all books with more than 500 pages but less than or equal to 1000 pages
{
Book(filter: {
and: [{pages: {gt: 500}}, {pages: {lte: 1000}}]
}){
title
pages
}
}
// Return all books with more than 500 pages but less than or equal to 1000 pages and with the title "Jane Eyre"
{
Book(filter: {
or: [
{and: [{pages: {gt: 500}}, {pages: {lte: 1000}}]},
{title: {eq: "Jane Eyre"}}
]
}){
title
pages
}
}
// Return all books with the title "Jane Eyre" or "Wuthering Heights"
{
Book(filter: {
title: {in: ["Jane Eyre","Wuthering Heights"]}
}){
title
pages
}
}
The supported filter operators are and
, or
, not
, nor
, eq
, ne
, in
, nin
, gt
, gte
, lt
, lte
. Each filter operator will be explained by example:
and
Example:
{
Book(filter: {
and: [{pages: {gt: 500}}, {pages: {lte: 1000}}]
}){
title
pages
}
}
This query will return all books where
the
pages
field is greater than500
and thepages
field is less than or equal1000
or
Example:
{
Book(filter: {
or: [
{and: [{pages: {gt: 500}}, {pages: {lte: 1000}}]},
{title: {eq: "Jane Eyre"}}
]
}){
title
pages
}
}
This query will return all books where
the
pages
field is greater than500
and thepages
field is less than or equal1000
or
the
title
field equalsJane Eyre
not
Example:
{
Book(filter: {
pages: {not: {gt: 500}}
}){
title
pages
}
}
This query will return all books where
the
pages
field is not greater than500
(in other words, 499 or less)
nor ("not or")
Example:
{
Book(filter: {
nor: [{price: {eq: 1.99}}, {sale: {eq: true}}]
}){
title
price
sale
}
}
This query will return all books that
contain the
price
field whose value is not equal to1.99
and contain thesale
field whose value is not equal totrue
orcontain the
price
field whose value is not equal to1.99
but do not contain thesale
field ordo not contain the
price
field but contain thesale
field whose value is not equal totrue
ordo not contain the
price
field and do not contain thesale
field
eq ("equals")
This operator is used for comparison. Example:
{
Book(filter: {
title: {eq: "Jane Eyre"}
}){
title
pages
}
}
This query will return all books where
the
title
field equalsJane Eyre
ne ("not equals")
This operator is used for comparison. Example:
{
Book(filter: {
title: {ne: "Jane Eyre"}
}){
title
pages
}
}
This query will return all books where
the
title
field not equalsJane Eyre
in ("in the set" / "is any of")
This operator is used for comparison. Example:
{
Book(filter: {
title: {in: ["Jane Eyre","Wuthering Heights"]}
}){
title
pages
}
}
This query will return all books where
the
title
field is any ofJane Eyre
orWuthering Heights
(or rephrased: the value of thetitle
field is in the set of the valuesJane Eyre
andWuthering Heights
)
nin ("not in the set" / "none of")
This operator is used for comparison. Example:
{
Book(filter: {
title: {nin: ["Jane Eyre","Wuthering Heights"]}
}){
title
pages
}
}
This query will return all books where
the
title
field is none ofJane Eyre
orWuthering Heights
(or rephrased: the value of thetitle
field is not in the set of the valuesJane Eyre
andWuthering Heights
)
gt ("greater than")
This operator is used for comparison. Example:
{
Book(filter: {
pages: {gt: 500}
}){
title
pages
}
}
This query will return all books where
the
pages
field is greater than500
(i.e. 501 pages or more)
gte ("greater than or equal")
This operator is used for comparison. Example:
{
Book(filter: {
pages: {gte: 500}
}){
title
pages
}
}
This query will return all books where
the
pages
field is greater than or equal500
(i.e. 500 pages or more)
lt ("less than")
This operator is used for comparison. Example:
{
Book(filter: {
pages: {lt: 500}
}){
title
pages
}
}
This query will return all books where
the
pages
field is less than500
(i.e. 499 pages or less)
lte ("less than or equal")
This operator is used for comparison. Example:
{
Book(filter: {
pages: {lte: 500}
}){
title
pages
}
}
This query will return all books where
the
pages
field is less than or equal500
(i.e. 500 pages or less)
Count
You can query the total number of objects in a response by using the Count query type. This needs to be enabled per object class by selecting Enable Aggregate and granting the Aggregate permission to the appropriate role.
When enabled, a new query type is added to your available queries. Using the object class Order as an example, we would get access to countOrder. This is separate to the order query type for reading data.
// Return a count of all orders
{
countOrder {
count
}
}
// Return a count of all orders made on or after the 1st of September 2022
{
countOrder(filter: {orderDate: {gte: "2022-09-01"}}){
count
}
}
Aggregate and grouping
You can summarize or find average, min/max or standard deviation using GraphQL aggregates. You may also group the records. For example, you may find the total order amount from OrderLines per Product:
{aggregateOrderLine(
filter: {product: {ne: null}},
sort: {productNumber:DESC},
group: product,
) {
product
productNumber
sum: amount_sum
_count
}
}
Given the above example with an OrderLine object class, you may perform the following:
Filter, Sort or Group on any property (optional)
In the list of properties to be returned, you may select the first or last entry. For example, we might return
customer_first
orcustomer_last
for in the above expression for returning the first or last customer of the grouped list of order lines.In the list of properties to be returned, we may select the following aggregates of numbers (with
amount
as example):amount_sum
(sum of the amount of orderLines)amount_avg
(average of the amount of orderLines)amount_max
(maximum of the amount of orderLines)amount_min
(minimum of the amount of orderLines)amount_stdDevPop
(standard deviation of the amount of all orderLines / the whole population)amount_stdDevSamp
(standard deviation of the amount of orderLines in the returned sample)amount_first
(amount of the first orderLine)amount_last
(amount of the last orderLine)
You may select to return an alias for a property, as in the above example
sum: amount_sum
(sum
is an alias foramount_sum
)
As with Count, this needs to be enabled per object class by selecting Enable Aggregate and granting the Aggregate permission to the appropriate role.
Group by multiple properties
Following the example above, records can also be grouped by multiple properties. For instance, finding the total order amount from OrderLines per product and size. This will return one aggregation per unique pair of values for product and size:
{aggregateOrderLine(
filter: {product: {ne: null}},
sort: {productNumber:DESC},
groupList: [product, size]
) {
product
size
productNumber
sum: amount_sum
_count
}
}
Run GraphQL Queries from Appfarm
GraphQL aggregations may be handy in applications with large amounts of data. With aggregation in GraphQL you may aggregate data on database level before it is returned to the client.
It is pretty straight forward.
Create an API Key in Appfarm Create. Go to Service Accounts in Appfarm Create, and locate (or create) a Service Account that is member of a Role with
Read
andAggregate
Permissions to the Object Classes to be queried in GraphQLUse the Web Request to run the Query:
URL:
https://<HOSTNAME>/api/graphql
Query Parameters: 1 parameter named
query
. Paste the query itself (e.g.{aggregateOrderLine(filter: ...)}
as valueResult mapping: Map the properties returned from the GraphQL aggregation
Example setup, with mapping of the Sum
to existing Product objects

Last updated
Was this helpful?