From f9ad66c6be7d351b7715d8a70f175ebae4ac730b Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Thu, 21 Sep 2023 13:57:09 +0200 Subject: [PATCH] Document how to exclude state attributes from recording (#1926) Co-authored-by: Martin Hjelmare Co-authored-by: Franck Nijhof --- docs/core/entity.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/core/entity.md b/docs/core/entity.md index 5cddd695..559f4cfc 100644 --- a/docs/core/entity.md +++ b/docs/core/entity.md @@ -273,6 +273,19 @@ Called when an entity has their entity_id and hass object assigned, before it is Called when an entity is about to be removed from Home Assistant. Example use: disconnect from the server or unsubscribe from updates. +## Excluding state attributes from recorder history + +State attributes which are not suitable for state history recording should be excluded from state history recording by including them in either of `_entity_component_unrecorded_attributes` or `_unrecorded_attributes`. +- `_entity_component_unrecorded_attributes: frozenset[str]` may be set in a base component class, e.g. in `light.LightEntity` +- `_unrecorded_attributes: frozenset[str]` may be set in an integration's platform e.g. in an entity class defined in platform `hue.light`. + +Examples of platform state attributes which are exluded from recording include the `entity_picture` attribute of `image` entities which will not be valid after some time, the `preset_modes` attribute of `fan` entities which is not likely to change. +Examples of integration specific state attributes which are excluded from recording include `description` and `location` state attributes in platform `trafikverket.camera` which do not change. + +:::tip +The `_entity_component_unrecorded_attributes` and `_unrecorded_attributes` must be declared as class attributes; instance attributes will be ignored. +::: + ## Changing the entity model If you want to add a new feature to an entity or any of its subtypes (light, switch, etc), you will need to propose it first in our [architecture repo](https://github.com/home-assistant/architecture/discussions). Only additions will be considered that are common features among various vendors.