Query - IOT-DSA/docs GitHub Wiki

Request fields

• path (string)
  • Path of the node to query
• mode (enum['live', 'snapshot'])
  • whether the query listen to children change, like when children nodes are added or removed, or when configs attributes have value change
• query (structure)
  • "?configs" ("*" or array or string) optional
    • list of configs the shows in result of the query
    • when value is "*", result has all configs
    • when omitted, the query result ignores config
  • "?attributes" ("*" or array or string) optional
    • list of attributes the shows in result of the query
    • when value is "*", result has all attributes
    • when omitted, the query result ignores attribute
  • "any node name" optional
    • query for a node with known node name
    • {"?filter": FilterStructure, "?value":"live"|"snapshot"}
    • ?filter optional, see filters section below
    • ?value optional
  • "?actions" wildcard action node, optional
    • query for all action nodes except those already have a filter with its name
    • {"?filter": FilterStructure, "?value":"live"|"snapshot"}
  • "*" wildcard node, optional
    • query for all non-action children nodes except those already have a filter with its name
    • {"?filter": FilterStructure, "?value":"live"|"snapshot"}

Filter Structure

when filter structure is omitted, show the node in result as long as node exists

• equal
  • {"field": fieldName, "=": value, "mode":"live"}
  • mode is optional, when omitted, it means snapshot (check only once)
• not equal
  • {"field": fieldName, "!=": value, "mode":"live"}
• greater
  • {"field": fieldName, ">": numberValue, "mode":"live"}
• less
  • {"field": fieldName, "<": numberValue, "mode":"live"}
• greater equal
  • {"field": fieldName, ">=": numberValue, "mode":"live"}
• less equal
  • {"field": fieldName, "<=": numberValue, "mode":"live"}
• match any
  • {"any": array of filters}
• match all
  • {"all": array of filters}

Filter's fieldName can be a config, an attribute, a node name, or "?value"

• When its a node name, use that child node's value
• when node value or child node doesn't exist, treat value as null, so {"=":null} should match the filter

Response

same as list method response, see https://github.com/IOT-DSA/docs/wiki/Methods#list

• when there is no value, return [name, node]
• when there is a value, return [name, node, value]
• when node is removed or no longer matching filter, return {"name":name, "change":"removed"}

Request Example

{
  "rid": 1,
  "method": "query",
  "path": "/downstream/abc",
  "mode": "live", // listen to children change
  "query" : {
    "?configs": "*", // all configs
    "?attributes": ["@unit"],
    "nodeA": {}, // show nodeA if it exists
    "nodeB": {"?filter": {"field": "?value", ">": 1}, "?value": "snapshot"}, // show nodeB if its value is number and value > 1, and show its value (only once)
    "nodeC": {"?filter": {"field": "version", "=": 3}}, // show nodeC if it has child node version and version's value is 3
    "*" : {
      "?filter": {"all":[{"field": "$type", "=": "number"}, {"field": "@unit", "=": "kWh"}]}, // show all the other children if they match both filters
      "?value": "live" // subscribe to its value
    }
  }
}