Using GraphQL
In this tutorial we will show you how you can use the powerful GraphQL API to access historical and current device data with Datacake.

GraphQL Requests

HTTP

You can use a cURL Command to call the GraphQL Library directly.
1
curl \
2
-X GET \
3
-H "Content-Type: application/json" \
4
-H "Authorization: Token 1234567yourtoken1234567" \
5
--data '{"query": "query { allDevices(inWorkspace:\"dc578994-your-workspace-84221d0\") { currentMeasurements(allActiveFields: true) { value field { verboseFieldName fieldName } } } }"}' \
6
https://api.datacake.co/graphql/
Copied!

Libraries

iOS

You can use the Apollo GraphQL Library in your iOS / Swift Applications:
GitHub - apollographql/apollo-ios: 📱  A strongly-typed, caching GraphQL client for iOS, written in Swift.
GitHub

Node-RED

You can use a function node in Node-RED and create a custom GraphlQL query that forwards data directly into Node-RED as a parsed JSON-Object.
1
// Datacake API Token and Workspace
2
var token = "123456mytoken123456";
3
var workspace = "1234myworkspace1234";
4
5
// GraphQL API URL
6
msg.url = "https://api.datacake.co/graphql";
7
8
// GraphQL Header
9
msg.headers = {
10
"Authorization": "Token "+token,
11
"Content-Type": "application/json"
12
};
13
14
// GraphQL Query
15
var query = `query {
16
allDevices(inWorkspace:${workspace}) {
17
id
18
serialNumber
19
verboseName
20
currentMeasurements(allActiveFields: true) {
21
field {
22
fieldName
23
verboseFieldName
24
}
25
value
26
}
27
}
28
}`;
29
30
msg.payload = {"query": query};
31
msg.body = {"query": query};
32
33
return msg;
Copied!

Node-RED Flow Export

Copy the following Node-RED Flow of a working Datacake GraphQL Example and paste this into your Node-RED using "Import" function.

Workspaces

List of Workspaces

1
query {
2
allWorkspaces {
3
id
4
name
5
}
6
}
Copied!

List of Devices

1
query {
2
allDevices(inWorkspace:"f6331019-8978-4a86-b1bc-3522546f67d5") {
3
id
4
verboseName
5
}
6
}
Copied!

Current Measurements

All Devices in Workspace

You can use the currentMeasurements option to have all the last recorded measurements of one or more devices returned.
Use the allActiveFields option as follows to return only those fields that are active in the database.
1
query {
2
allDevices(inWorkspace:"f6331019-8978-4a86-b1bc-3522546f67d5") {
3
currentMeasurements(allActiveFields: true) {
4
value
5
modified
6
field {
7
verboseFieldName
8
fieldName
9
}
10
}
11
}
12
}
Copied!

Specific Fields only

1
query {
2
allDevices(inWorkspace:"f6331019-8978-4a86-b1bc-3522546f67d5") {
3
currentMeasurements(fieldNames:["BATTERY"]) {
4
value
5
modified
6
field {
7
verboseFieldName
8
fieldName
9
}
10
}
11
}
12
}
Copied!

Single Fields only

Instead of providing an Array of Field Identifiers you can use the currentMeasurement Option to Query a specific field only.
1
query {
2
allDevices(inWorkspace:"f6331019-8978-4a86-b1bc-3522546f67d5") {
3
currentMeasurement(fieldName:"BATTERY") {
4
value
5
modified
6
field {
7
verboseFieldName
8
fieldName
9
}
10
}
11
}
12
}
Copied!

Specific Device

The above examples are using the allDevices Option to query all devices in a given Workspace. If you just want to access data from a specific device only, you can use the device Option.
1
device(deviceId:"faf34567-5f13-4536-b3f3-a4a1e245ab2a")
Copied!
Use this as in the following example query:
1
query {
2
device(deviceId:"faf34567-5f13-4536-b3f3-a4a1e245ab2a") {
3
currentMeasurements(allActiveFields: true) {
4
value
5
modified
6
field {
7
verboseFieldName
8
fieldName
9
}
10
}
11
}
12
}
Copied!

Working with Strings

If your fields in database store a String-type value you have to add the valueString option to return the corresponding value.
1
query {
2
allDevices(inWorkspace:"f6331019-8978-4a86-b1bc-3522546f67d5") {
3
currentMeasurements(allActiveFields: true) {
4
valueString
5
modified
6
field {
7
verboseFieldName
8
fieldName
9
}
10
}
11
}
12
}
Copied!

Working with Maximum, Average

1
maximum(timeRangeStart:"2021-04-16T00:00", timeRangeEnd:"2021-04-17T00:00")
2
average(timeRangeStart:"2021-04-16T00:00", timeRangeEnd:"2021-04-17T00:00")
3
change(average(timeRangeStart:"2021-04-16T00:00", timeRangeEnd:"2021-04-17T00:00")
Copied!
1
query {
2
device(deviceId:"faf34567-5f13-4536-b3f3-a4a1e245ab2a") {
3
currentMeasurements(allActiveFields: true) {
4
value
5
maximum(timeRangeStart:"2021-04-16T00:00", timeRangeEnd:"2021-04-17T00:00")
6
field {
7
verboseFieldName
8
fieldName
9
}
10
}
11
}
12
}
Copied!
So will look like
1
{
2
"data": {
3
"device": {
4
"currentMeasurements": [
5
{
6
"value": 3.067,
7
"average": 3.06697222222223,
8
"maximum": 3.069,
9
"change": 0,
10
"modified": "2021-04-17T12:58:30.554976+00:00",
11
"field": {
12
"verboseFieldName": "Battery",
13
"fieldName": "BATTERY"
14
}
15
}
16
]
17
}
18
}
19
}
Copied!

Historical Data

From all Devices in Workspace

1
query {
2
allDevices(inWorkspace:"f6331019-8978-4a86-b1bc-3522546f67d5") {
3
history(
4
fields:["BATTERY"],
5
timerangestart:"2021-04-16T00:00",
6
timerangeend:"2021-04-17T00:00",
7
resolution:"120 Minutes"
8
)
9
}
10
}
Copied!

From a Specific Device

1
query {
2
device(deviceId:"faf34567-5f13-4536-b3f3-a4a1e245ab2a") {
3
history(fields:["BATTERY"], timerangestart:"2021-04-16T00:00", timerangeend:"2021-04-17T00:00", resolution:"raw")
4
}
5
}
Copied!
Fields have to be Identifier
1
fields:["BATTERY"]
Copied!

Working with Resolution

One of the options for the history settings is an option called resolution. This gives you two options:
  • raw - Raw Data Export. Data will be exported as stored in the database
  • X Minutes - Quantisation in X Minutes - Data will be combined into timerange-chunks of given value.
The operation for Quantisation is an average. You cannot change this right now.

Raw Data Export

1
query {
2
device(deviceId:"faf34567-5f13-4536-b3f3-a4a1e245ab2a") {
3
history(
4
fields:["BATTERY"],
5
timerangestart:"2021-04-16T00:00",
6
timerangeend:"2021-04-17T00:00",
7
resolution:"raw"
8
)
9
}
10
}
Copied!

Quantisation

1
query {
2
device(deviceId:"faf34567-5f13-4536-b3f3-a4a1e245ab2a") {
3
history(
4
fields:["BATTERY"],
5
timerangestart:"2021-04-16T00:00",
6
timerangeend:"2021-04-17T00:00",
7
resolution:"120 Minutes"
8
)
9
}
10
}
Copied!

Devices

Metadata

The following snippet works for both allDevices and specific device Options.
1
query {
2
allDevices(inWorkspace:"f6331019-8978-4a86-b1bc-3522546f67d5") {
3
location
4
lastHeard
5
claimed
6
claimCode
7
tags
8
serialNumber
9
}
10
}
Copied!
Last modified 8mo ago