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 currently limited to be derived from entities, and so statistic_id is currently equivalent to entity_id. When an entity ID is changed, the statistic ID is automatically updated.

This restriction might be dropped in the future to allow integrations to import statistics without an entity.

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

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 strictly increasing value, such as utility meters (the sensor's state_class is 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))