Skip to main content

Home Assistant Statistics

Home Assistant has support for long-term statistics. Each hour it will take a snapshot of supported entities and track different things about the entity state. Currently it differentiates between two types:

  • Sensor entities with a measurement, like current temperature. It will store the min, max and mean value.
  • Sensor entities that are metered, like daily energy consumption. It will store the growth of that entity.

Long-term statistics are different than the other objects in the database, which are stored exactly as they happened and are automatically purged after a period (default is 10 days). Statistics are never purged. Because they are summarized every hour, they only create 24 entries per day.

Read the sensor developer documentation on how to configure entities to be tracked by the long-term statistics.

Database tables

Long-term statistics consist of two tables. One contains the metadata, the other the data.

Statistics Meta

This table contains the metadata describing the source. Statistics are either derived from entities, in which case statistic_id is equivalent to the entity_id, or imported from an external source. Statistics imported from an external source are similar to entity_id, but use a : instead of a . as a delimiter between the domain and object ID.

If an entity ID of an entity is changed, the statistic ID is automatically updated.

FieldType
idColumn(Integer, primary_key=True)
statistic_idColumn(String(255), index=True)
sourceColumn(String(32))
state_unit_of_measurementColumn(String(255))
unit_of_measurementColumn(String(255))
has_meanColumn(Boolean)
has_sumColumn(Boolean)
nameColumn(String(255))

Statistics

This table contains the actual data. Depending on the entity type, different data is tracked.

  • Sensor entities with a measurement (the sensor's state_class is measurement):
    • mean - hourly time-weighted average
    • min - hourly minimum
    • max - hourly maximum
  • Sensor entities that have a value which is integrated over time, such as utility meters (the sensor's state_class is total or total_increasing):
    • last_reset - the time when the last meter cycle was started, if known
    • state - the sensor's state at the end of the hour
    • sum - hourly grand total since statistics for the sensor was first compiled, offset by the sensor's first valid state when compiling statistics. Please refer to the developer documentation for how the sum is calculated.
FieldType
idColumn(Integer, primary_key=True)
createdColumn(DATETIME_TYPE, default=dt_util.utcnow)
metadata_idColumn(Integer, ForeignKey(f"{TABLE_STATISTICS_META}.id", ondelete="CASCADE"), index=True)
startColumn(DATETIME_TYPE, index=True)
meanColumn(DOUBLE_TYPE())
minColumn(DOUBLE_TYPE())
maxColumn(DOUBLE_TYPE())
last_resetColumn(DATETIME_TYPE)
stateColumn(DOUBLE_TYPE())
sumColumn(DOUBLE_TYPE())

Statistics Runs

This table is used to keep track of hours for which statistics have been compiled.

FieldType
run_idColumn(Integer, primary_key=True)
startColumn(DateTime(timezone=True))