Get Entities

The Get Entities node retrieves entities based on specific search criteria, with three different output options. This node is useful for filtering and finding entities that match certain conditions, such as all lights that are currently on, or sensors reporting a specific range of values.

Configuration

Search Criteria

All specified criteria must be met for an entity to be considered valid.

Property

Autocomplete is available for all properties currently set on loaded entities.

Inputs

Payload

  • Type: Object

Override the configuration values by passing in a property with a valid value.

  • rules (array)
    • condition: string (e.g., stateObject, labelRegistry, areaRegistry, deviceRegistry, floorRegistry)
    • property: string
    • logic: string
    • value: string
    • valueType: string
  • outputType: string
  • outputEmptyResults: boolean
  • outputLocationType: string
  • outputLocation: string
  • outputResultsCount: number

Example

To retrieve all entities with the device class battery on the First floor that are not labeled not replaceable, include the following in the payload property of the message:

{
  "rules": [
    {
      "condition": "stateObject",
      "property": "attributes.device_class",
      "logic": "is",
      "value": "battery",
      "valueType": "str"
    },
    {
      "condition": "floorRegistry",
      "property": "name",
      "logic": "is",
      "value": "First floor",
      "valueType": "str"
    },
    {
      "condition": "labelRegistry",
      "property": "name",
      "logic": "is_not",
      "value": "not replaceable",
      "valueType": "str"
    }
  ]
}

Outputs

Array

  • Type: Array

Returns an array of state objects based on the search criteria and sends them to the specified output location.

Count

  • Type: number

Returns the total count of valid entities.

Random

  • Type: Object | Array

Returns a random object or array from the available state objects. If One Max Results is selected, it will return a single object; otherwise, it will return an array of state objects.

Split

  • Type: msg.part

Sends a separate message for each state object, similar to the output of a split node.

State Object Format

Sample output when the output type is an array:

[
  {
    "entity_id": "light.kitchen",
    "state": "on",
    "attributes": {
      "brightness": 243,
      "friendly_name": "Kitchen Light",
      "supported_features": 33,
      "icon": "mdi:light-switch"
    },
    "last_changed": "2019-12-29T05:38:53.016984+00:00",
    "last_updated": "2019-12-29T05:38:53.016984+00:00",
    "context": {
      "id": "6c16e348494c42fb8c8e8bda92b20fb2",
      "parent_id": null,
      "user_id": null
    },
    "timeSinceChangedMs": 3466747
  }
]

entity_id

  • Type: string

The entity to which this state belongs.

state

  • Type: string

The main attribute state value, such as 'on', 'off', 'home', 'open', 'closed', etc.

attributes

  • Type: Object

Supported attributes of the state as set by Home Assistant.

last_changed

  • Type: string

ISO Date string representing the last time the entity state changed.

timeSinceChangedMs

  • Type: number

Milliseconds since the last state change of the entity.

last_updated

  • Type: string

ISO Date string representing the last time the entity state was updated.

context

  • Type: Object

Information about who or what last changed the state of this entity.

Examples

### Example 1

Get a notification when you leave if any doors or windows are left open. Use the get entities node to get a list of entity IDs (e.g., binary_sensor.front_door, binary_sensor.back_door, binary_sensor.front_window, binary_sensor.back_window) where the state is open. The entities are returned with the output Split, sending a message for each valid entity. A template node can then format the payload into the entity's friendly name, and the messages can be joined back into one payload using the join node.

screenshot

[{"id":"4ad3d88d8a2357d5","type":"trigger-state","z":"b9bff4863336dc6b","name":"Left Home","server":"","version":5,"inputs":1,"outputs":2,"exposeAsEntityConfig":"","entities":{"entity":["device_tracker.jason"],"substring":[],"regex":[]},"debugEnabled":false,"constraints":[{"targetType":"this_entity","targetValue":"","propertyType":"previous_state","propertyValue":"old_state.state","comparatorType":"is","comparatorValueDatatype":"str","comparatorValue":"home"},{"targetType":"this_entity","targetValue":"","propertyType":"current_state","propertyValue":"new_state.state","comparatorType":"is","comparatorValueDatatype":"str","comparatorValue":"not_home"}],"customOutputs":[],"outputInitially":false,"stateType":"str","enableInput":true,"x":284,"y":1248,"wires":[["d115adfcfa168310"],[]]},{"id":"d115adfcfa168310","type":"ha-get-entities","z":"b9bff4863336dc6b","name":"","server":"","version":1,"rules":[{"condition":"stateObject","property":"entity_id","logic":"includes","value":"binary_sensor.front_door,binary_sensor.back_door,binary_sensor.front_window,binary_sensor.back_window","valueType":"str"},{"condition":"stateObject","property":"state","logic":"is","value":"open","valueType":"str"}],"outputType":"split","outputEmptyResults":false,"outputLocationType":"msg","outputLocation":"payload","outputResultsCount":1,"x":450,"y":1248,"wires":[["f7e4e11c30fe53bd"]]},{"id":"f7e4e11c30fe53bd","type":"template","z":"b9bff4863336dc6b","name":"Format Friendly Name","field":"payload","fieldType":"msg","format":"handlebars","syntax":"mustache","template":"{{payload.attributes.friendly_name}}","output":"str","x":654,"y":1248,"wires":[["6932846cb5c86e6f"]]},{"id":"6932846cb5c86e6f","type":"join","z":"b9bff4863336dc6b","name":"","mode":"custom","build":"string","property":"payload","propertyType":"msg","key":"topic","joiner":",","joinerType":"str","accumulate":false,"timeout":"","count":"","reduceRight":false,"reduceExp":"","reduceInit":"","reduceInitType":"","reduceFixup":"","x":824,"y":1248,"wires":[["601e97da25388235"]]},{"id":"601e97da25388235","type":"api-call-service","z":"b9bff4863336dc6b","name":"Notify","server":"","version":6,"debugenabled":false,"action":"notify.push_jason","floorId":[],"areaId":[],"deviceId":[],"entityId":[],"labelId":[],"data":"{\"message\": \"The {{payload}} are open.\",\"title\": \"Left Open\"}","dataType":"json","mergeContext":"","mustacheAltTags":false,"outputProperties":[{"property":"payload","propertyType":"msg","value":"","valueType":"data"}],"queue":"none","domain":"notify","service":"push_jason","output_location":"payload","output_location_type":"msg","x":952,"y":1248,"wires":[[]]}]

Example 2

Create a vacation or away script to randomly turn on lights around your home. Use an inject node (or your preferred timer node) and the get entities node to randomly choose an entity from the criteria where entity_id starts with light..

screenshot

[{"id":"39342a95.8db3d6","type":"inject","z":"b9bff4863336dc6b","name":"","repeat":"","crontab":"","once":false,"onceDelay":0.1,"topic":"","payload":"","payloadType":"date","x":300,"y":1360,"wires":[["e9038030.b79e4"]]},{"id":"e9038030.b79e4","type":"ha-get-entities","z":"b9bff4863336dc6b","name":"","server":"","version":1,"rules":[{"condition":"stateObject","property":"entity_id","logic":"starts_with","value":"light.","valueType":"str"}],"outputType":"random","outputEmptyResults":false,"outputLocationType":"msg","outputLocation":"payload","outputResultsCount":1,"x":450,"y":1360,"wires":[["2586f129.6136fe"]]},{"id":"58c67712.8aa4a8","type":"delay","z":"b9bff4863336dc6b","name":"","pauseType":"random","timeout":"5","timeoutUnits":"seconds","rate":"1","nbRateUnits":"1","rateUnits":"second","randomFirst":"20","randomLast":"30","randomUnits":"minutes","drop":false,"outputs":1,"x":780,"y":1360,"wires":[["986369ca.af3f48"]]},{"id":"2586f129.6136fe","type":"api-call-service","z":"b9bff4863336dc6b","name":"Turn on Light","server":"","version":6,"debugenabled":false,"action":"light.turn_on","floorId":[],"areaId":[],"deviceId":[],"entityId":["{{payload.entity_id}}"],"labelId":[],"data":"","dataType":"json","mergeContext":"","mustacheAltTags":false,"outputProperties":[],"queue":"none","domain":"light","service":"turn_on","output_location":"","output_location_type":"none","x":610,"y":1360,"wires":[["58c67712.8aa4a8"]]},{"id":"986369ca.af3f48","type":"api-call-service","z":"b9bff4863336dc6b","name":"Turn off Light","server":"","version":6,"debugenabled":false,"action":"light.turn_off","floorId":[],"areaId":[],"deviceId":[],"entityId":["{{payload.entity_id}}"],"labelId":[],"data":"","dataType":"json","mergeContext":"","mustacheAltTags":false,"outputProperties":[{"property":"payload","propertyType":"msg","value":"","valueType":"data"}],"queue":"none","domain":"light","service":"turn_off","output_location":"payload","output_location_type":"msg","x":946,"y":1360,"wires":[[]]}]

Example 3

Join pre-defined messages based on separate entity states. Use the get entities and function nodes with the Array output option.

screenshot

[{"id":"2bdd6fb7.15743","type":"server-state-changed","z":"b9bff4863336dc6b","name":"","server":"","version":6,"outputs":1,"exposeAsEntityConfig":"","entities":{"entity":[],"substring":["binary_sensor.button_bedroom"],"regex":[]},"outputInitially":false,"stateType":"str","ifState":"","ifStateType":"str","ifStateOperator":"is","outputOnlyOnStateChange":false,"for":"0","forType":"num","forUnits":"minutes","ignorePrevStateNull":false,"ignorePrevStateUnknown":false,"ignorePrevStateUnavailable":false,"ignoreCurrentStateUnknown":false,"ignoreCurrentStateUnavailable":false,"outputProperties":[{"property":"payload","propertyType":"msg","value":"","valueType":"entityState"},{"property":"data","propertyType":"msg","value":"","valueType":"eventData"},{"property":"topic","propertyType":"msg","value":"","valueType":"triggerId"}],"x":284,"y":1520,"wires":[["c2a9ffac.1e05d"]]},{"id":"c2a9ffac.1e05d","type":"ha-get-entities","z":"b9bff4863336dc6b","name":"","server":"","version":1,"rules":[{"condition":"stateObject","property":"entity_id","logic":"includes","value":"sensor.phon_charging,sensor.watch_charging,sensor.kaylas_phone_charging,lock.lock","valueType":"str"},{"condition":"stateObject","property":"state","logic":"includes","value":"no,unlocked","valueType":"str"}],"outputType":"array","outputEmptyResults":true,"outputLocationType":"msg","outputLocation":"payload","outputResultsCount":1,"x":562,"y":1520,"wires":[["2950c181.1ef95e"]]},{"id":"2950c181.1ef95e","type":"function","z":"b9bff4863336dc6b","name":"","func":"let lockFD = null;\nlet PC = false;\nlet WC = false;\nlet KP = false;\nlet FD = false;\n\nmsg.payload.forEach(entity => {\n    switch(entity.entity_id) {\n        case \"sensor.phone_charging\":\n            PC = true;\n            break;\n        case \"sensor.watch_charging\":\n            WC = true;\n            break;\n        case \"sensor.kaylas_phone_charging\":\n            KP = true;\n            break;\n        case \"lock.lock\":\n            FD = true;\n            lockFD = { payload: true };\n            break;\n    }\n    \n});\n\nlet message = \"Goodnight.\";\nif(PC && WC) {\n    message = `${message} Don’t forget to charge your phone and watch.`;\n} else {\n    message = `${message} Don’t forget to charge your ${PC ? 'phone' : 'watch'}.`\n}\nif(KP) {\n    message = `${message} Remind Kayla to charge her phone${PC ? ' too':''}.`;\n}\nif(FD) {\n    message = `${message} The door is now locked.`\n}\nmsg.payload = message;\nreturn [msg, lockFD];\n","outputs":2,"noerr":0,"x":702,"y":1520,"wires":[["ca4a5643.9bf0d8"],["64374b0e.f72394"]]},{"id":"ca4a5643.9bf0d8","type":"cast-to-client","z":"b9bff4863336dc6b","name":"","url":"","contentType":"","message":"","language":"en","ip":"192.168.1.29","port":"","volume":"40","x":886,"y":1520,"wires":[[]]},{"id":"64374b0e.f72394","type":"api-call-service","z":"b9bff4863336dc6b","name":"lock door","server":"","version":6,"debugenabled":false,"action":"scene.turn_on","floorId":[],"areaId":[],"deviceId":[],"entityId":["scene.lock_door"],"labelId":[],"data":"","dataType":"json","mergeContext":"","mustacheAltTags":false,"outputProperties":[{"property":"payload","propertyType":"msg","value":"","valueType":"data"}],"queue":"none","domain":"scene","service":"turn_on","output_location":"payload","output_location_type":"msg","x":856,"y":1568,"wires":[[]]}]

Example 4

Get all lights in an area named "Kitchen" that are off.

screenshot

[{"id":"a13b46e3d393d3d6","type":"inject","z":"b9bff4863336dc6b","name":"","props":[{"p":"payload"},{"p":"topic","vt":"str"}],"repeat":"","crontab":"","once":false,"onceDelay":0.1,"topic":"","payload":"","payloadType":"date","x":220,"y":1712,"wires":[["a16bfc3b499fc173"]]},{"id":"fe39495f3aab7683","type":"debug","z":"b9bff4863336dc6b","name":"do stuff","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"payload","targetType":"msg","statusVal":"","statusType":"auto","x":668,"y":1712,"wires":[]},{"id":"a16bfc3b499fc173","type":"ha-get-entities","z":"b9bff4863336dc6b","name":"get all off lights in the kitchen","server":"","version":1,"rules":[{"condition":"stateObject","property":"entity_id","logic":"starts_with","value":"light.","valueType":"str"},{"condition":"stateObject","property":"state","logic":"is","value":"off","valueType":"str"},{"condition":"areaRegistry","property":"name","logic":"is","value":"Kitchen","valueType":"str"}],"outputType":"array","outputEmptyResults":false,"outputLocationType":"msg","outputLocation":"payload","outputResultsCount":1,"x":444,"y":1712,"wires":[["fe39495f3aab7683"]]}]

References