Singular queries
Let's start with fetching data for a single specific supplier. If your supplier has the id 222 for example, you can fetch it's label and supplier_id just like this:
query{
Supplier (id:222) {
label
supplier_id
}
}
- Supplier being here the name of the query (which, as you can guess, fetches a supplier entity).
- supplier_id and label are the resulting fields, the ids and labels of this specific supplier.
GraphQL is very flexible, meaning that you can add or remove the fields you want to tailor the query to your needs. Try removing a field, then adding the field phone to the query:
query{
Supplier (id:222) {
label
phone
}
}
If you want to see all fields available for suppliers, you can find them in the Suppliers entity page.
Plural queries
Let's say you don't have a specific supplier in mind, and you want to fetch results for all of them. You can do it like this:
query{
Suppliers{
edges{
node{
id
label
supplier_id
}
}
}
}
- Notice that the query Supplier became Suppliers when we decided to return multiple results. Almost every query has two forms: a singular form (which only returns a single result) and a plural form (which returns multiple results). For ease of use, these queries are simply the singular and plural version of the same word (ex: Supplier=>Suppliers, Currency=>Currencies, ... ) but if you need a reminder, you can find all the available queries in this documentation, on their respective entity's pages
- Edges and node are required sub-fields for queries that return multiple results at once. This is an industry standard, which allows for certain pagination features. Edges are mandatory on plural queries (like Suppliers) but forbidden on singular queries (like Supplier).
Just like a singular query, they are very flexible. Try replacing a field with another for example:
query{
Suppliers{
edges{
node{
id
phone
supplier_id
}
}
}
}
Singular sub-queries
Some fields require sub-queries to other entities. For example, to get the currency of a supplier, you need to do a sub-query, like this:
query{
Suppliers{
edges{
node{
label
currency{
id
iso
}
}
}
}
}
- currency is a sub-query on the Currency entity affiliated to each supplier. You can then fetch multiple multiple fields in this sub-query, like we do here for the id and iso of the currency.
- In some cases, these fields may also be sub-queries, who may also have sub-queries etc...
- Just because you call a sub-query doesn't mean you can't call normal fields at the same time, like we do here for the label.
These sub-queries behave like normal queries, meaning that they can also be completely tailored to your needs.
Try to replace the label field with id, and the iso field with sign and symbol_template for example:
query{
Suppliers{
edges{
node{
id
currency{
id
sign
symbol_template
}
}
}
}
}
Plural sub-queries
Some sub-queries return multiple results at once, like taxes for example. You need to call them like this:
query{
Suppliers{
edges{
node{
id
currency{
id
}
taxes{
edges{
node{
id
}
}
}
}
}
}
}
- When a query or sub-query returns multiple results at once, you need to use the edges structure.
- Each supplier only has a single currency and the sub-query will therefore only return a single result, so we don't use the edges and node sub-fields.
Sending multiple queries
To avoid spamming the API, and for convenience, it is possible to send multiple queries at once, just like this:
query{
Suppliers{
edges{
node{
id
label
supplier_id
}
}
}
Taxes{
edges{
node{
id
}
}
}
}
Both queries will be fetched and their results returned in a single result package:
{
"data": {
"Suppliers": {
"edges": {
"node": [
{
"id": 175302,
"label": "Bob",
"supplier_id": "S0000022"
},
{
"id": 175307,
"label": "Bob",
"supplier_id": "S0000023"
}
]
}
},
"Taxes": {
"edges": {
"node": [
{
"id": 125700
},
{
"id": 125701
}
]
}
}
}
}
This will also count as a single query towards the rate limiter.