From 75a7de80b6360da9d60fcd26b22df47214bd2bbc Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Thu, 1 Oct 2020 14:42:03 -0500 Subject: [PATCH] Add explanation of the new template `rate_limit` directive. (#14631) --- .../_docs/configuration/templating.markdown | 2 +- .../binary_sensor.template.markdown | 25 +++++++++++++++++++ 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/source/_docs/configuration/templating.markdown b/source/_docs/configuration/templating.markdown index dce917e3bc7..832132b5109 100644 --- a/source/_docs/configuration/templating.markdown +++ b/source/_docs/configuration/templating.markdown @@ -58,7 +58,7 @@ Extensions allow templates to access all of the Home Assistant specific states a - `is_state('device_tracker.paulus', 'home')` will test if the given entity is the specified state. - `state_attr('device_tracker.paulus', 'battery')` will return the value of the attribute or None if it doesn't exist. - `is_state_attr('device_tracker.paulus', 'battery', 40)` will test if the given entity attribute is the specified state (in this case, a numeric value). Note that the attribute can be `None` and you want to check if it is `None`, you need to use `state_attr('sensor.my_sensor', 'attr') == None`. - +- `rate_limit` - limits re-renders of the template. Returns an empty string and accepts the same arguments as the Python `datetime.timedelta` function -- days, seconds, microseconds, milliseconds, minutes, hours, weeks.
Avoid using `states.sensor.temperature.state`, instead use `states('sensor.temperature')`. It is strongly advised to use the `states()`, `is_state()`, `state_attr()` and `is_state_attr()` as much as possible, to avoid errors and error message when the entity isn't ready yet (e.g., during Home Assistant startup). diff --git a/source/_integrations/binary_sensor.template.markdown b/source/_integrations/binary_sensor.template.markdown index 9635fc1af12..a01f176eb32 100644 --- a/source/_integrations/binary_sensor.template.markdown +++ b/source/_integrations/binary_sensor.template.markdown @@ -294,6 +294,31 @@ binary_sensor: {% endraw %} +### Rate limiting updates + +When there are entities present in the template, the template will be re-rendered when one of the entities changes states. + +When `states` is used in a template by itself to iterate all states on the system, the template is re-rendered each +time any state changed event happens if any part of the state is accessed. When merely counting states, the template +is only re-rendered when a state is added or removed from the system. On busy systems with many entities or hundreds of +thousands state changed events per day, templates may re-render more than desirable. + +A `rate_limit` directive can be used to limit how often the template re-renders. + +`rate_limit` returns an empty string and accepts the same arguments as the Python `datetime.timedelta` function -- days, seconds, microseconds, milliseconds, minutes, hours, weeks. + +In the below example, re-renders are limited to once per minute: + +{% raw %} +```yaml +binary_sensor: + - platform: template + sensors: + has_unavailable_states: + value_template: '{{ rate_limit(minutes=1) }}{% states | selectattr('state', 'in', ['unavailable', 'unknown', 'none']) | list | count }}' +``` +{% endraw %} + ### Working without entities The `template` sensors are not limited to use attributes from other entities but can also work with [Home Assistant's template extensions](/docs/configuration/templating/#home-assistant-template-extensions). If the template includes some non-deterministic property such as time in its calculation, the result will not continually update, but will only update when some entity referenced by the template updates.