Query data by GraphQL API

Query data in GraphQL API, query criteria accept 5 parameters bellow, can be used together as needed.

  • filters: text or array
  • fields: array
  • top: number
  • skip: number
  • sort: text

They are enclosed in brackets after the object name like the following.

leads(filters:[["status", "=", "Qualified"]], top:1, sort:"name desc")

When somebody access the GraphQL API on Steedos, they can see only the data they have permission to see, see About data permissions for more information.

Filters

You can add the query filters after the object name, the filters expression may be an array as a Steedos Filters like [["status", "=", "Qualified"]] or a text as a standard OData filtering string like "status eq 'Qualified'".

query{
leads(filters:[["status", "=", "Qualified"]]){
name,
title,
status
}
}

or

query{
leads(filters:"status eq 'Qualified'"){
name,
title,
status
}
}

Field Structure Detail

In a GraphQL query, you must define the field structure detail at the end of the object name and brackets.

Thanks to this feature, you can extend the field indefinitely to query the relevant field value just like the following example.

Request all lead records, along with extended fields information belonging to the relevant objects:

query{
leads{
name,
title,
status,
converted_account {
name,
rating
},
converted_contact {
name,
account{
name
}
},
converted
}
}

Get predictable results:

{
"data": {
"leads": [
{
"name": "Lead A",
"title": "GM",
"status": "Qualified",
"converted_account": {
"name": "Account B",
"rating": "Hot"
},
"converted_contact": {
"name": "Contact M",
"account": {
"name": "Account N"
}
},
"converted": true
},
{
"name": "Lead B",
"title": "purchasing manager",
"status": "New",
"converted_account": null,
"converted_contact": null,
"converted": null
}
]
}
}

Suffix __label

If the GraqhQL script has some field that return Date, DateTime, Boolean, Select, etc., and you want to display them directly to your customers, you need to add the __label suffix after the field name to indicate that you want to format the field value, otherwise it will return the content of the field stored in the database directly.

Date/DateTime

For example, the created field indicates the creation time, it will return a non-semantic value such as 1608621469293, but created__label will return formatted like 2020-12-22 15:17 with a good reading experience result.

If the created field is a empty value, then it will return null and created__label will return a empty string "".

Boolean

For example, the converted field indicates whether it is a converted record, it will return a character like true or false, but the converted__label will return a result with a good reading experience like "Yes" or "No".

If the converted field is a empty value, then it will return null and converted__label will return a string "No".

Select

For example, the salutation field indicates a person is 'Male' or 'Female', it may return a character like 1 or 0, but the salutation__label will return a result with a good reading experience like "Male" or "Female".

If the salutation field is a empty value, then it will return null and salutation__label will return a empty string "".

Request all lead records, with some __label suffix fields in it:

query{
leads{
name,
title,
converted,
converted__label,
created,
created__label,
salutation,
salutation__label
}
}

Get predictable results:

{
"data": {
"leads": [
{
"name": "Lead A",
"title": "GM",
"converted": true,
"converted__label": "Yes",
"created": "1597979950012",
"created__label": "2020-08-21 11:19",
"salutation": "1",
"salutation__label": "Male"
},
{
"name": "Lead B",
"title": "purchasing manager",
"converted": false,
"converted__label": "No",
"created": "1597988499634",
"created__label": "2020-08-21 13:41",
"salutation": "0",
"salutation__label": "Female"
},
{
"name": "Lead C",
"title": "CMO",
"converted": null,
"converted__label": "No",
"created": null,
"created__label": "",
"salutation": null,
"salutation__label": ""
}
]
}
}
Note

If you use GraphQL API to fetch data and show them in the Steedos Page, you shouldn't to add the __label suffix after the field name, because the Steedos Page will format them auto.

Only when you want to display the field value directly to your customers, you will need to add the __label suffix after the field name.

Prefix related__

If you want each record in the list returned by the GraphQL API interface to carry the associated sub-object records information, you can use related__ as a prefix to splice the name of the associated sub-object to achieve the goal.

What is sub-object? That means you have two object associated by a Master Detail relationship field, One is Master Object, another is Detail Object, and the sub-object is exactly the Detail Object.

Request all lead records, with some related__ prefix fields to fetch the sub-object records for every records:

query{
leads{
name,
title,
related__tasks{
name,
assignees{
name
},
due_date,
due_date__label
}
}
}

Get predictable results:

{
"data": {
"leads": [
{
"name": "Lead A",
"title": "GM",
"related__tasks": [
{
"name": "Task 1",
"assignees": [
{
"name": "Litant"
}
],
"due_date": "1611964800000",
"due_date__label": "2021-01-30"
}
]
},
{
"name": "Lead B",
"title": "purchasing manager",
"related__tasks": [
{
"name": "Task 2",
"assignees": [
{
"name": "John"
}
],
"due_date": "1611964800000",
"due_date__label": "2021-01-30"
}
]
}
]
}
}
Note

The field name related__tasks in the example above based on there is a object named 'tasks' who has a master-detail field associated to the Master Object leads.

Top and Skip

You can define how many records you want to skip with a skip word, and how many record you want to return with a top word.

The query bellow will only return the second record.

query{
leads(fields:["name"], top:1, skip:1){
name,
title
}
}

Sort

You can define how you want to sort the results with the sort word.

A key word named 'desc' represents descending order, and a key word named ‘asc’ represents ascending order.

The query bellow will sort in descending order by field name to return the results.

query{
leads(fields:["name"], sort:"name desc"){
name,
title
}
}

Fields

You can add the query fields after the object name, that represents the which fields on the object you want to fetch.

This property is always omitted, because you must define the field structure detail at the end of the object name and brackets, so we recommend you to omit this property.

query{
leads(fields:["name"]){
name,
title
}
}

The results is like bellow:

{
"data": {
"leads": [
{
"name": "T1",
"title": null
},
{
"name": "T2",
"title": null
}
]
}
}
Note

As you see, if there are some fields in the field structure detail that are not defined in the fields property, these missed fields will be ignored and a null value is returned.

Have questions about Steedos??
Contact Steedos and our technical expert will answer your questions.

Our technical experts have more than 10 years of experience in management software development, and they are always ready to help you with any questions you may have about the functionality, pricing, implementation or any other aspect of Steedos.

Steedos

Steedos is a new generation of low code platform, based on business intelligence and model driven, it can easily and easily create intelligent, mobile and personalized applications according to the needs of business departments.

Copyright © 2020 Steedos, Inc.