Queries

GraphQL queries for devices, measurements, spaces, and assets

Overview

The Service API provides GraphQL queries for retrieving devices, measurements, spaces, and assets. Queries support filtering, pagination, and field selection.

Devices

Device Search

Search devices by various criteria:

query DevicesByTextSearch($limit: Int = 25, $searchText: String) {
  devices(
    limit: $limit,
    where: {
      _or: [
        {identifiers: {customerLabelId: {_ilike: $searchText}}}
        {identifiers: {vendorSerial: {_ilike: $searchText}}}
        {name: {_ilike: $searchText}}
      ]
    }
  ) {
    id
    name
    connectorProtocol
    organizationId
    lastSeen
    availableMeasurements
    availableMessages
    identifiers {
      wirepasNodeId
      wirepasNetworkId
      wifiMac
      vendorSerial
      tuid
      lanMac
      imei
      customerLabelId
      bleMac
    }
    deviceType {
      make
      model
      productName
    }
    keywords {
      keyword
    }
    createdAt
    updatedAt
  }
}

Key Device Properties

availableMeasurements - List of measurement types the device supports. Use this to dynamically determine what data to query.
identifiers - Various static device identifiers (serial number, Wirepas node ID, MAC addresses, label ID).
lastSeen - Last communication timestamp.

Measurements

Measurements are sensor data values stored in a time-series database, optimized for time-based queries.

Measurement Types

The system supports various measurement types:

batteryVoltage - Battery voltage levels
batteryPercentage - Battery percentage
ambientTemperature - Environmental temperature
systemTemperature - Internal device temperature
occupancyStatus - Room/space occupancy
occupantsCount - Number of occupants
CO2 - Carbon dioxide concentration
TVOC - Total Volatile Organic Compounds
position - Device location
distance - Distance measurements

Latest Measurement

Query the latest known measurement for a device:

query MeasurementLastPosition {
  measurementLastPosition(where: {deviceId: {_eq: "6e5f8ac6-a099-44e5-bb28-25fd3d1f47a6"}}) {
    deviceId
    isStatic
    measuredAt
    position
    spaceId
  }
}

Note

The device ID 6e5f8ac6-a099-44e5-bb28-25fd3d1f47a6 is an example value. Replace it with your own device UUID.

Response:

{
  "data": {
    "measurementLastPosition": [{
      "deviceId": "6e5f8ac6-a099-44e5-bb28-25fd3d1f47a6",
      "isStatic": true,
      "measuredAt": "2023-10-21T01:09:42.491+00:00",
      "position": {
        "type": "Point",
        "coordinates": [17, 35.4]
      },
      "spaceId": "55a0a3d0-84b6-4ace-b131-0b2420053e91"
    }]
  }
}

Position Geometry

The position value is a 2D point geometry in GeoJSON format:

Origin is the bottom-left corner of the assigned floorplan
Coordinates use meters as the unit

Historical Measurements

Query measurements for a time period:

query MeasurementTemperature {
  measurementAmbientTemperature(
    where: {
      deviceId: {_eq: "6e5f8ac6-a099-44e5-bb28-25fd3d1f47a6"},
      measuredAt: {_gte: "2024-01-01T00:00:00+00:00", _lte: "2024-01-31T23:59:59+00:00"}
    },
    order_by: {measuredAt: desc}
  ) {
    deviceId
    measuredAt
    ambientTemperature
  }
}

Replace these example values

6e5f8ac6-a099-44e5-bb28-25fd3d1f47a6 — your device UUID
2024-01-01T00:00:00+00:00 — start of your time range (ISO 8601)
2024-01-31T23:59:59+00:00 — end of your time range (ISO 8601)

Low Battery Query

Find devices with low battery:

query MeasurementLastBatteryPercentageDevices {
  measurementLastBatteryPercentage(
    where: {
      batteryPercentage: {_gte: 0, _lt: 20},
      device: {deviceType: {model: {_eq: "PRESENCE"}}}
    }
  ) {
    measuredAt
    batteryPercentage
    device {
      id
      name
      lastSeen
    }
  }
}

Replace these example values

PRESENCE — your device model name
0 / 20 — your battery percentage range (devices with less than 20% battery)

Spaces

The space hierarchy in Haltian IoT:

Site - Root location (typically an address with global coordinates)
- Building - Buildings within a site
  - Floor - Floors within a building
    - Room/Zone - Rooms and zones within a floor

Query Spaces

query Spaces {
  spaces(where: {organizationId: {_eq: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}) {
    id
    name
    spaceType
    parentId
    createdAt
    updatedAt
  }
}

Replace these example values

a1b2c3d4-e5f6-7890-abcd-ef1234567890 — your organization UUID

Assets

Assets are objects to which sensors are attached:

query Assets {
  assets(where: {spaceId: {_eq: "55a0a3d0-84b6-4ace-b131-0b2420053e91"}}) {
    id
    name
    assetType
    spaceId
    devices {
      id
      name
    }
  }
}

Replace these example values

55a0a3d0-84b6-4ace-b131-0b2420053e91 — your space UUID

Best Practices

Recommended Use

Meta data queries - Fetch devices, sites, buildings, floors, zones
Configuration data - This data is typically static and changes only when updated
Keep local cache - Cache results and fetch updates only when needed

Limited Use for Measurements

Use for PoCs and pilots with low device count and data volume
As a secondary channel to fill gaps when MQTT is unavailable
For single device latest measurements

Recommendation

For continuous measurement data, use the Stream API (MQTT) instead of polling the Service API.

Timestamps

All timestamps use ISO 8601 format in UTC:

YYYY-MM-DDThh:mm:ss.sss±hh:mm

Example: 2024-10-04T11:51:33.372171+00:00

Next Steps

Mutations - Modify configurations and data
Stream API - Real-time measurement streaming