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

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($device: uuid) {
  measurementLastPosition(where: {deviceId: {_eq: $device}}) {
    deviceId
    isStatic
    measuredAt
    position
    spaceId
  }
}

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($device: uuid, $from: timestamptz, $to: timestamptz) {
  measurementAmbientTemperature(
    where: {
      deviceId: {_eq: $device},
      measuredAt: {_gte: $from, _lte: $to}
    },
    order_by: {measuredAt: desc}
  ) {
    deviceId
    measuredAt
    ambientTemperature
  }
}

Low Battery Query

Find devices with low battery:

query MeasurementLastBatteryVoltageDevices($model: String, $lt: numeric, $gte: numeric) {
  measurementLastBatteryVoltage(
    where: {
      batteryVoltage: {_gte: $gte, _lt: $lt},
      device: {deviceType: {model: {_eq: $model}}}
    }
  ) {
    measuredAt
    batteryVoltage
    device {
      id
      name
      lastSeen
    }
  }
}

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($organizationId: uuid) {
  spaces(where: {organizationId: {_eq: $organizationId}}) {
    id
    name
    spaceType
    parentId
    createdAt
    updatedAt
  }
}

Assets

Assets are objects to which sensors are attached:

query Assets($spaceId: uuid) {
  assets(where: {spaceId: {_eq: $spaceId}}) {
    id
    name
    assetType
    spaceId
    devices {
      id
      name
    }
  }
}

Best Practices

  • 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

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