History
The history
integration will track everything that is going on within Home
Assistant and allows the user to browse through it. It depends on the recorder
integration for storing the data and uses the same database setting.
If any entities are excluded from being recorded,
no history will be available for these entities.
This integration is by default enabled, unless you’ve disabled or removed the default_config:
line from your configuration. If that is the case, the following example shows you how to enable this integration manually:
# Basic configuration.yaml entry
history:
Configuration Variables
Configure which integrations should not be displayed.
Configure which integrations should be displayed.
Without any include
or exclude
configuration the history displays graphs for
every entity (well that’s not exactly true -
scenes
are never shown) on a given date. If you are only interested in some
of the entities you have several options:
Define domains and entities to exclude
(aka. blocklist). This is convenient
when you are basically happy with the information displayed, but just want to
remove some entities or domains. Usually these are entities/domains which do not
change or rarely change (like updater
or automation
).
# Example configuration.yaml entry with exclude
history:
exclude:
domains:
- automation
- updater
entities:
- sensor.last_boot
- sensor.date
entity_globs:
- binary_sensor.*_occupancy
Define domains and entities to display by using the include
configuration
(aka. allowlist). If you have a lot of entities in your system and your
exclude
list is getting too large, it might be better just to define the
entities or domains to include
.
# Example configuration.yaml entry with include
history:
include:
domains:
- sensor
- switch
- media_player
Use the include
list to define the domains/entities to display, and exclude
some of them within the exclude
list. This makes sense if you, for instance,
include the sensor
domain, but want to exclude some specific sensors. Instead
of adding every sensor entity to the include
entities
list just include the
sensor
domain and exclude the sensor entities you are not interested in.
Note that the order of any include
entities
will be displayed as listed in
the configuration, otherwise, the display order is arbitrary.
# Example configuration.yaml entry with include and exclude
history:
include:
domains:
- sensor
- switch
- media_player
exclude:
entities:
- sensor.last_boot
- sensor.date
Filters are applied as follows:
- No filter
- All entities included
- Only includes
- Entity listed in entities include: include
- Otherwise, entity matches domain include: include
- Otherwise, entity matches glob include: include
- Otherwise: exclude
- Only excludes
- Entity listed in exclude: exclude
- Otherwise, entity matches domain exclude: exclude
- Otherwise, entity matches glob exclude: exclude
- Otherwise: include
- Domain and/or glob includes (may also have excludes)
- Entity listed in entities include: include
- Otherwise, entity listed in entities exclude: exclude
- Otherwise, entity matches glob include: include
- Otherwise, entity matches glob exclude: exclude
- Otherwise, entity matches domain include: include
- Otherwise: exclude
- Domain and/or glob excludes (no domain and/or glob includes)
- Entity listed in entities include: include
- Otherwise, entity listed in exclude: exclude
- Otherwise, entity matches glob exclude: exclude
- Otherwise, entity matches domain exclude: exclude
- Otherwise: include
- No Domain and/or glob includes or excludes
- Entity listed in entities include: include
- Otherwise: exclude
The following characters can be used in entity globs:
*
- The asterisk represents zero, one, or multiple characters
?
- The question mark represents a single character
Implementation details
The history is stored in a SQLite database home-assistant_v2.db
within your
configuration directory unless the recorder
integration is set up differently.
- events table is all that happened while recorder integration was running.
- states table contains all the
new_state
values ofstate_changed
events. - Inside the states table you have:
-
entity_id
: the entity_id of the entity -
state
: the state of the entity -
attributes
: JSON of the state attributes -
last_changed
: timestamp last time the state has changed. -
last_updated
: timestamp anything has changed (state, attributes) -
created
: timestamp this entry was inserted into the database
-
When the history
integration queries the states table it only selects states
where the state has changed: WHERE last_changed=last_updated
On dates
SQLite databases do not support native dates. That’s why all the dates are saved in seconds since the UNIX epoch. Convert them manually using this site or in Python:
from datetime import datetime
datetime.fromtimestamp(1422830502)
API
The history information is also available through the RESTful API.