Understanding and Using Home Assistant Statistics
This site contains documents that explains how statistics are generated in Home Assistant (HA) and how to work with them effectively. It also provides SQL Examples on how to query the database.
About this site
Home Assistant stores a wealth of information in its database. Statistics are the long-term, aggregated representation of that data, used by many dashboards — most notably the Energy dashboard.
This documentation covers everything you need to know about statistics: how they are generated, how to configure sensors correctly, how to troubleshoot and fix common issues, and how to query the database directly with SQL.
Whether you are trying to understand why your energy dashboard shows wrong values, need to change a sensor's unit of measurement, or want to explore your data with SQL — you'll find the answer here.
Who is this for?
- HA users who want to understand how statistics work behind the scenes
- Troubleshooters dealing with missing data, spikes, or incorrect values
- Power users who want to query and manipulate the database directly
Important notes
This documentation is based on Home Assistant documents and thorough testing, so it should be relatively accurate. However, it will inevitably contain errors or omissions — HA evolves quickly and some behaviors are not well documented.
Documentation structure
Overview ← Start here
A high-level map of all documentation sections and what they cover.
Part 1 — Foundational Concepts
Entities, states, the recorder, and how they relate to statistics.
Part 2 — Statistics Generation
How HA compiles short-term and long-term statistics from sensor data.
Part 3 — Working with Statistics
Dashboards, graphs, and how statistics are displayed in the UI.
Part 4 — Best Practices & Troubleshooting
Choosing the right state_class, recorder configuration, and common pitfalls.
Part 5 — Find & Fix Statistics Errors
Detect and repair data gaps, spikes, orphaned entries, counter resets, and more.
Part 6 — Statistics Migration Guideline
Migrate statistics from one Home Assistant instance to another.
Appendix 1 — Mysterious Table Fields
Deep dive into created_ts and mean_weight fields.
Appendix 2 — Statistics Domains
Examples of statistics from non-sensor domains (number, input_number, counter).
Quick Reference Guide
Cheat sheet with key concepts, common queries, and decision tables at a glance.
SQL Examples
Ready-to-use queries for statistics, states, and error detection.