HOWTO - Creating Complex Queries

Building Blocks for Query Construction

1. Logical Operators

Logical operators are used to combine multiple parameters in a query.

2. Standard Fields

Properties
Key-value pairs that define specific attributes of an asset.

• Example Fields:
  • properties.deviceId: Unique identifier of the device.
  • properties.serialNumber: Serial number of the device.
  • properties.dateLastCharge: Last charge timestamp in ISO format.

Tags
Metadata assigned to the asset for categorization or identification.

• Example Tags:
  • tags.customer: Customer name.
  • tags._manufacturer: Manufacturer name.
  • tags._model: Model name.

Data
Time-series or aggregated metrics related to the asset's usage.

• Example Fields:
  • data.runTimeLast7: Total runtime in the last 7 days.
  • data.chargeTimeLifetime: Total charge time over the device's lifetime.

Dates
Date fields in ISO 8601 format for filtering time-based events.

• Example Fields:
  • dateLastActivity: Timestamp of the last recorded activity.
  • dateSubscriptionExpires: Subscription expiration date.

Alerts
Details about specific events or conditions associated with the asset.

• Example Fields:
  • alerts.details: Detailed description of an alert.
  • alerts.class: Severity classification of the alert (error, warning, etc.).

3. Query Examples

Search by Device ID

properties.deviceId=="123456789012345"

Search for Manufacturer at Customer

tags.customer=="DEMO" && tags._manufacturer=="Kaivac"

Filter by Subscription Status

tags.customer=="DEMO" && dateSubscriptionExpires>date("2025-01-01T00:00:00Z")

Search by Alert Details

alerts.details==contains("Subscription is expired")

Complex Queries
Combine multiple conditions using logical operators:

tags._manufacturer=="Kaivac" && exists("properties.deviceId") && exists("properties.prevDeviceIds")

4. Example Data Fields

Below is a breakdown of fields from a sample JSON query return:

• Identification Fields:

  • id: Unique ID of the asset.
  • modelId: Model identifier (e.g., sc901).
  • properties.deviceId: IMEI of device (15 digits)
  • properties.serialNumber: Serial number of the asset
  • name: Nickname of the asset

• Metrics:

  • runTimeLast7: Total runtime in the last 7 days.
  • runTimeLast30:Total runtime in the last 30 days.
  • runTimeLastLifetimeTotal runtime.
  • chargeTimeLast7: Total runtime in the last 7 days.
  • chargeTimeLast30Total runtime in the last 30 days.
  • chargeTimeLifetime: Lifetime charge time.

• Location:

  • address.address1: Street address 1
  • address.address2: Street address 2
  • address.city: City of address
  • address.state: State of address
  • address.zipCode: Zip code of address
  • geoHash: Encoded geographic location.
  • location.coordinates: GPS coordinates (longitude, latitude).

• Alerts:

  • alerts.class: Severity of the alert (e.g., error).
  • alerts.details: Description of the alert.

• Dates:

  • dateLastActivity: Last activity timestamp.
  • dateSubscriptionExpires: Expiration date of the subscription.

-- ARMOR Support