v1 API Query Language

Some Remote Manager v1 APIs include a query parameter for GET requests. Using the query parameter, you can build complex expressions for selecting Remote Manager objects.

Query language summary

  • Similar in concept to SQL or other query languages.
  • Use conditions and operators based on field types.
  • Single quoted text literals 'TheText' .
  • Text escape for quote character is the quote: 'isn''t difficult' .
  • Numeric literals support 0x prefix for hex.
  • Relative values from “now’ for timestamp values. For example, -10s for 10 seconds ago or +30d for 30 days from now.
  • Text-based comparisons are case insensitive.
  • Use the and and or keywords as well as parenthesis to group simple conditions into more complex expressions.
  • Use the not keyword to negate individual conditions or complex parenthesized conditions.
  • Use the special value keyword empty to represent empty string, null, and unset.
Info

Although the query parameter in each API provides the same query expression capability, the fields that you can query depend on the fields returned for objects of that API. For example, a query using the ws/v1/devices/inventory API specifies device fields, while a query using the ws/v1/alerts/inventory APIs specifies alert fields.

Warning

Be sure to correctly URL encode the query expression (for example space encodes to %20 in a URL parameter value.

Specify values in query conditions

The syntax for specifying literal values varies depending on the type of literal value. Not all syntaxes from other query languages are supported.

Value Type Description
String, Enumerated String, Group Specify these values using single quotes. If the value contains a single quote, specify two single quotes. Enumerated strings cannot accept all values, for example connection_status can only be connected or disconnected. For example: connection_status = 'connected' or name = 'Fred''s Device' or group = 'TheGroup' or not group = 'TheGroup'
Numeric Specify these values using a normal decimal number notation or a hex number notation. For example: value = 0 or value = -3.14or value = 0x10
Timestamp Specify these values using a relative time notation where positive or negative values are supported. Use a one letter suffix to indicate time units: s for seconds, m for minutes, h for hours, d for days (exactly 24 hours) and w for weeks (exactly 7 days). For example: last_updated > -60m or last_connect >= -24h or expires < +30d
Geoposition Specify a bounding box value. The geoposition can be within or outside of the bounding box. The bounding box consists of four coordinates of the form: [ Southwest longitude, Southwest latitude, Northeast longitude, Northwest latitude ]. For example, to select items approximately within the continental United States: geoposition within [ 125.0, 25.0, 65.0, 50.0 ]

Specify operators in query conditions

The following table summarizes Remote Manager v1 query language conditions.

Operator Permitted Types Description
= <> Enumerated String, Enumerated Value, Group, Tags, Timestamp Exact equality or inequality. For a tag, indicates the presense or absense of the tag on the item. For a group, indicates the full group path.
< <= >= > String, Numeric, Timestamp The string, number or timestamp sorts before or after the value.
contains String, Tag The String contains the specified substring. Any tag contains the specified substring.
startswith, endsWith String, Tag, Group The string starts with or ends with the specified value. Any tag starts with or ends with the specified value. For a group, targets the full group path. For example, group startswith 'test/' targets any device in the root/test group and all subgroups, while group startswith 'test' targets any device in the root/test* groups and any subgroups.
within, outside Geoposition The geoposition is within or outside of a bounding box. For example, to select items approximately within the continental United Statess, query for geoposition within [ 125.0, 25.0, 65.0, 50.0 ]

Example Queries

  • Complex Queries

    • Query of group startsWith '/NorthWest' and (connection_status = 'disconnected' or signal_percent < 20) - find any devices in the /Northwest group and any subgroups that are either disconnected or have a low signal strength
    • Query of tags = 'important' and (health_status = 'error' or health_status = 'warning') - Find any devices that have the ‘important’ tag and are in an error or warning health status
    • Query of tags = 'important' and not (health_status = 'error' or health_status = 'warning') - Find any devices that have the ‘important’ tag and are not in an error or warning health status
    • Query of last_connect = empty - Find any devices whose last connect value is unset (have never connected).
    • Query of not last_connect = empty - Find any devices whose last connect value is set (have connected at least once).

  • Group Queries

    • Query of group = '/test' - query full group path, so matches any device in group ‘/test’ and ignores any subgroups.
    • Query of group startsWith 'test/' - query full group path, so matches any device in the test root group and any subgroups.
    • Query of group startsWith 'test' - query full group path, so matches any device in any root group whose name starts with ’test’ and all subgroups.
    • Query of group endsWith '/leaf' - query full group path, so matches any device in any path that ends with the group name ’leaf’.

  • Tag Queries

    • Query of tags = empty - matches any device having no tags.
    • Query of tags <> empty - matches any device having any tags.
    • Query of tags = 'sensor' - matches any device having a tag ‘sensor’.
    • Query of tags <> 'sensor' - matches any device having no tag ‘sensor’.
    • Query of tags contains 'ns' - matches any device having any tag containing ’ns’.
    • Query of tags startsWith 'sens' - matches any device having any tag that starts with ‘sens’.
    • Query of tags endsWith 'or' - matches any device having any tag that ends with ‘or’.

  • Geoposition Queries

    • Query of geoposition within [ 125.0, 25.0, 65.0, 50.0 ] - matches any device with coordinates within the specified bounding box (approximately the continental United States).
    • Query of geoposition outside [ 125.0, 25.0, 65.0, 50.0 ] - matches any device with coordinates outside the specified bounding box (approximately the continental United States).