Classes
class	BaseStatisticsRow

class	PlatformCompiledStatistics

class	ShortTermStatisticsRunCache

class	StatisticsRow

class	ValidationIssue

Functions
None	_adjust_sum_statistics (Session session, type[StatisticsBase] table, int metadata_id, datetime start_time, float adj)

None	_async_import_statistics (HomeAssistant hass, StatisticMetaData metadata, Iterable[StatisticData] statistics)

None	_augment_result_with_change (HomeAssistant hass, Session session, datetime start_time, dict[str, str]\|None units, set[Literal["change", "last_reset", "max", "mean", "min", "state", "sum"]] _types, type[Statistics\|StatisticsShortTerm] table, dict[str, tuple[int, StatisticMetaData]] metadata, dict[str, list[StatisticsRow]] result)

list[StatisticsRow]	_build_converted_stats (list[Row] db_rows, float table_duration_seconds, int start_ts_idx, tuple[tuple[str, int],...] row_mapping, Callable[[float\|None], float\|None]\|Callable[[float], float] convert)

list[StatisticsRow]	_build_stats (list[Row] db_rows, float table_duration_seconds, int start_ts_idx, tuple[tuple[str, int],...] row_mapping)

list[StatisticsRow]	_build_sum_converted_stats (list[Row] db_rows, float table_duration_seconds, int start_ts_idx, int sum_idx, Callable[[float\|None], float\|None]\|Callable[[float], float] convert)

list[StatisticsRow]	_build_sum_stats (list[Row] db_rows, float table_duration_seconds, int start_ts_idx, int sum_idx)

None	_change_statistics_unit_for_table (Session session, type[StatisticsBase] table, int metadata_id, Callable[[float\|None], float\|None] convert)

None	_compile_hourly_statistics (Session session, datetime start)

StatementLambdaElement	_compile_hourly_statistics_last_sum_stmt (float start_time_ts, float end_time_ts)

StatementLambdaElement	_compile_hourly_statistics_summary_mean_stmt (float start_time_ts, float end_time_ts)

set[str]	_compile_statistics (Recorder instance, Session session, datetime start, bool fire_events)

list[int]	_extract_metadata_and_discard_impossible_columns (dict[str, tuple[int, StatisticMetaData]] metadata, set[Literal["last_reset", "max", "mean", "min", "state", "sum"]] types)

StatementLambdaElement	_find_latest_short_term_statistic_for_metadata_id_stmt (int metadata_id)

datetime	_find_month_end_time (datetime timestamp)

datetime\|None	_first_statistic (Session session, type[StatisticsBase] table, int metadata_id)

list[dict]	_flatten_list_statistic_ids_metadata_result (dict[str, dict[str, Any]] result)

StatementLambdaElement	_generate_max_mean_min_statistic_in_sub_period_stmt (Select columns, datetime\|None start_time, datetime\|None end_time, type[StatisticsBase] table, int metadata_id)

StatementLambdaElement	_generate_select_columns_for_types_stmt (type[StatisticsBase] table, set[Literal["last_reset", "max", "mean", "min", "state", "sum"]] types)

StatementLambdaElement	_generate_statistics_at_time_stmt (type[StatisticsBase] table, set[int] metadata_ids, float start_time_ts, set[Literal["last_reset", "max", "mean", "min", "state", "sum"]] types)

StatementLambdaElement	_generate_statistics_during_period_stmt (datetime start_time, datetime\|None end_time, list[int]\|None metadata_ids, type[StatisticsBase] table, set[Literal["last_reset", "max", "mean", "min", "state", "sum"]] types)

Callable[[float], float]\|None	_get_display_to_statistic_unit_converter (str\|None display_unit, str\|None statistic_unit)

StatementLambdaElement	_get_first_id_stmt (datetime start)

dict[str, list[StatisticsRow]]	_get_last_statistics (HomeAssistant hass, int number_of_stats, str statistic_id, bool convert_units, type[StatisticsBase] table, set[Literal["last_reset", "max", "mean", "min", "state", "sum"]] types)

StatementLambdaElement	_get_last_statistics_short_term_stmt (int metadata_id, int number_of_stats)

StatementLambdaElement	_get_last_statistics_stmt (int metadata_id, int number_of_stats)

dict[str, float\|None]	_get_max_mean_min_statistic (Session session, datetime\|None head_start_time, datetime\|None head_end_time, datetime\|None main_start_time, datetime\|None main_end_time, datetime\|None tail_start_time, datetime\|None tail_end_time, bool tail_only, int metadata_id, set[Literal["max", "mean", "min", "change"]] types)

None	_get_max_mean_min_statistic_in_sub_period (Session session, dict[str, float] result, datetime\|None start_time, datetime\|None end_time, type[StatisticsBase] table, set[Literal["max", "mean", "min", "change"]] types, int metadata_id)

float\|None	_get_newest_sum_statistic (Session session, datetime\|None head_start_time, datetime\|None head_end_time, datetime\|None main_start_time, datetime\|None main_end_time, datetime\|None tail_start_time, datetime\|None tail_end_time, bool tail_only, int metadata_id)

float\|None	_get_oldest_sum_statistic (Session session, datetime\|None head_start_time, datetime\|None main_start_time, datetime\|None tail_start_time, datetime\|None oldest_stat, datetime\|None oldest_5_min_stat, bool tail_only, int metadata_id)

Callable[[float\|None], float\|None]\|Callable[[float], float]\|None	_get_statistic_to_display_unit_converter (str\|None statistic_unit, str\|None state_unit, dict[str, str]\|None requested_units, bool allow_none=True)

Callable[[float\|None], float\|None]\|None	_get_unit_converter (str from_unit, str to_unit)

bool	_import_statistics_with_session (Recorder instance, Session session, StatisticMetaData metadata, Iterable[StatisticData] statistics, type[StatisticsBase] table)

StatisticsBase\|None	_insert_statistics (Session session, type[StatisticsBase] table, int metadata_id, StatisticData statistic)

datetime\|None	_last_statistic (Session session, type[StatisticsBase] table, int metadata_id)

StatementLambdaElement	_latest_short_term_statistics_by_ids_stmt (Iterable[int] ids)

dict[str, list[StatisticsRow]]	_reduce_statistics (dict[str, list[StatisticsRow]] stats, Callable[[float, float], bool] same_period, Callable[[float], tuple[float, float]] period_start_end, timedelta period, set[Literal["last_reset", "max", "mean", "min", "state", "sum"]] types)

dict[str, list[StatisticsRow]]	_reduce_statistics_per_day (dict[str, list[StatisticsRow]] stats, set[Literal["last_reset", "max", "mean", "min", "state", "sum"]] types)

dict[str, list[StatisticsRow]]	_reduce_statistics_per_month (dict[str, list[StatisticsRow]] stats, set[Literal["last_reset", "max", "mean", "min", "state", "sum"]] types)

dict[str, list[StatisticsRow]]	_reduce_statistics_per_week (dict[str, list[StatisticsRow]] stats, set[Literal["last_reset", "max", "mean", "min", "state", "sum"]] types)

dict[str, list[StatisticsRow]]	_sorted_statistics_to_dict (HomeAssistant hass, Sequence[Row[Any]] stats, set[str]\|None statistic_ids, dict[str, tuple[int, StatisticMetaData]] _metadata, bool convert_units, type[StatisticsBase] table, dict[str, str]\|None units, set[Literal["last_reset", "max", "mean", "min", "state", "sum"]] types)

dict[str, dict[str, Any]]	_statistic_by_id_from_metadata (HomeAssistant hass, dict[str, tuple[int, StatisticMetaData]] metadata)

Sequence[Row]\|None	_statistics_at_time (Session session, set[int] metadata_ids, type[StatisticsBase] table, datetime start_time, set[Literal["last_reset", "max", "mean", "min", "state", "sum"]] types)

dict[str, list[StatisticsRow]]	_statistics_during_period_with_session (HomeAssistant hass, Session session, datetime start_time, datetime\|None end_time, set[str]\|None statistic_ids, Literal["5minute", "day", "hour", "week", "month"] period, dict[str, str]\|None units, set[Literal["change", "last_reset", "max", "mean", "min", "state", "sum"]] _types)

int\|None	_statistics_exists (Session session, type[StatisticsBase] table, int metadata_id, datetime start)

None	_update_statistics (Session session, type[StatisticsBase] table, int stat_id, StatisticData statistic)

bool	adjust_statistics (Recorder instance, str statistic_id, datetime start_time, float sum_adjustment, str adjustment_unit)

None	async_add_external_statistics (HomeAssistant hass, StatisticMetaData metadata, Iterable[StatisticData] statistics)

None	async_change_statistics_unit (HomeAssistant hass, str statistic_id, *str new_unit_of_measurement, str old_unit_of_measurement)

None	async_import_statistics (HomeAssistant hass, StatisticMetaData metadata, Iterable[StatisticData] statistics)

list[dict]	async_list_statistic_ids (HomeAssistant hass, set[str]\|None statistic_ids=None, Literal["mean", "sum"]\|None statistic_type=None)

int\|None	cache_latest_short_term_statistic_id_for_metadata_id (ShortTermStatisticsRunCache run_cache, Session session, int metadata_id)

bool	can_convert_units (str\|None from_unit, str\|None to_unit)

None	change_statistics_unit (Recorder instance, str statistic_id, str new_unit, str old_unit)

bool	cleanup_statistics_timestamp_migration (Recorder instance)

None	clear_statistics (Recorder instance, list[str] statistic_ids)

bool	compile_missing_statistics (Recorder instance)

bool	compile_statistics (Recorder instance, datetime start, bool fire_events)

str\|None	get_display_unit (HomeAssistant hass, str statistic_id, str\|None statistic_unit)

dict[str, list[StatisticsRow]]	get_last_short_term_statistics (HomeAssistant hass, int number_of_stats, str statistic_id, bool convert_units, set[Literal["last_reset", "max", "mean", "min", "state", "sum"]] types)

dict[str, list[StatisticsRow]]	get_last_statistics (HomeAssistant hass, int number_of_stats, str statistic_id, bool convert_units, set[Literal["last_reset", "max", "mean", "min", "state", "sum"]] types)

list[Row]	get_latest_short_term_statistics_by_ids (Session session, Iterable[int] ids)

dict[str, list[StatisticsRow]]	get_latest_short_term_statistics_with_session (HomeAssistant hass, Session session, set[str] statistic_ids, set[Literal["last_reset", "max", "mean", "min", "state", "sum"]] types, dict[str, tuple[int, StatisticMetaData]]\|None metadata=None)

dict[str, tuple[int, StatisticMetaData]]	get_metadata (HomeAssistant hass, *set[str]\|None statistic_ids=None, Literal["mean", "sum"]\|None statistic_type=None, str\|None statistic_source=None)

dict[str, tuple[int, StatisticMetaData]]	get_metadata_with_session (Recorder instance, Session session, *set[str]\|None statistic_ids=None, Literal["mean", "sum"]\|None statistic_type=None, str\|None statistic_source=None)

ShortTermStatisticsRunCache	get_short_term_statistics_run_cache (HomeAssistant hass)

datetime	get_start_time ()

bool	import_statistics (Recorder instance, StatisticMetaData metadata, Iterable[StatisticData] statistics, type[StatisticsBase] table)

list[dict]	list_statistic_ids (HomeAssistant hass, set[str]\|None statistic_ids=None, Literal["mean", "sum"]\|None statistic_type=None)

float\|None	mean (list[float] values)

( tuple[ Callable[[float, float], bool], Callable[[float], tuple[float, float]],])	reduce_day_ts_factory ()

( tuple[ Callable[[float, float], bool], Callable[[float], tuple[float, float]],])	reduce_month_ts_factory ()

( tuple[ Callable[[float, float], bool], Callable[[float], tuple[float, float]],])	reduce_week_ts_factory ()

list[str]	split_statistic_id (str entity_id)

dict[str, Any]	statistic_during_period (HomeAssistant hass, datetime\|None start_time, datetime\|None end_time, str statistic_id, set[Literal["max", "mean", "min", "change"]]\|None types, dict[str, str]\|None units)

dict[str, list[StatisticsRow]]	statistics_during_period (HomeAssistant hass, datetime start_time, datetime\|None end_time, set[str]\|None statistic_ids, Literal["5minute", "day", "hour", "week", "month"] period, dict[str, str]\|None units, set[Literal["change", "last_reset", "max", "mean", "min", "state", "sum"]] types)

None	update_statistics_issues (HomeAssistant hass)

None	update_statistics_metadata (Recorder instance, str statistic_id, str\|None\|UndefinedType new_statistic_id, str\|None\|UndefinedType new_unit_of_measurement)

bool	valid_statistic_id (str statistic_id)

str	validate_statistic_id (str value)

dict[str, list[ValidationIssue]]	validate_statistics (HomeAssistant hass)

Variables
	_LOGGER = logging.getLogger(__name__)

dictionary	_type_column_mapping

string	DATA_SHORT_TERM_STATISTICS_RUN_CACHE = "recorder_short_term_statistics_run_cache"

tuple	QUERY_STATISTICS

tuple	QUERY_STATISTICS_SHORT_TERM

tuple	QUERY_STATISTICS_SUMMARY_MEAN

tuple	QUERY_STATISTICS_SUMMARY_SUM

dictionary	UNIT_CLASSES

	VALID_STATISTIC_ID = re.compile(r"^(?!.+__)(?!_)[\da-z_]+(?<!_):(?!_)[\da-z_]+(?<!_)$")

Detailed Description

Statistics helper.

Function Documentation

◆ _adjust_sum_statistics()

None homeassistant.components.recorder.statistics._adjust_sum_statistics	(	Session	session,
		type[StatisticsBase]	table,
		int	metadata_id,
		datetime	start_time,
		float	adj
	)

private

Adjust statistics in the database.

Definition at line 639 of file statistics.py.

◆ _async_import_statistics()

None homeassistant.components.recorder.statistics._async_import_statistics	(	HomeAssistant	hass,
		StatisticMetaData	metadata,
		Iterable[StatisticData]	statistics
	)

private

Validate timestamps and insert an import_statistics job in the queue.

Definition at line 2261 of file statistics.py.

◆ _augment_result_with_change()

None homeassistant.components.recorder.statistics._augment_result_with_change	(	HomeAssistant	hass,
		Session	session,
		datetime	start_time,
		dict[str, str] \| None	units,
		set[Literal["change", "last_reset", "max", "mean", "min", "state", "sum"]]	_types,
		type[Statistics \| StatisticsShortTerm]	table,
		dict[str, tuple[int, StatisticMetaData]]	metadata,
		dict[str, list[StatisticsRow]]	result
	)

private

Add change to the result.

Definition at line 1657 of file statistics.py.

◆ _build_converted_stats()

list[StatisticsRow] homeassistant.components.recorder.statistics._build_converted_stats	(	list[Row]	db_rows,
		float	table_duration_seconds,
		int	start_ts_idx,
		tuple[tuple[str, int], ...]	row_mapping,
		Callable[[float \| None], float \| None] \| Callable[[float], float]	convert
	)

private

Build a list of statistics with unit conversion.

Definition at line 2123 of file statistics.py.

◆ _build_stats()

list[StatisticsRow] homeassistant.components.recorder.statistics._build_stats	(	list[Row]	db_rows,
		float	table_duration_seconds,
		int	start_ts_idx,
		tuple[tuple[str, int], ...]	row_mapping
	)

private

Build a list of statistics without unit conversion.

Definition at line 2106 of file statistics.py.

◆ _build_sum_converted_stats()

list[StatisticsRow] homeassistant.components.recorder.statistics._build_sum_converted_stats	(	list[Row]	db_rows,
		float	table_duration_seconds,
		int	start_ts_idx,
		int	sum_idx,
		Callable[[float \| None], float \| None] \| Callable[[float], float]	convert
	)

private

Build a list of sum statistics.

Definition at line 2071 of file statistics.py.

◆ _build_sum_stats()

list[StatisticsRow] homeassistant.components.recorder.statistics._build_sum_stats	(	list[Row]	db_rows,
		float	table_duration_seconds,
		int	start_ts_idx,
		int	sum_idx
	)

private

Build a list of sum statistics.

Definition at line 2089 of file statistics.py.

◆ _change_statistics_unit_for_table()

None homeassistant.components.recorder.statistics._change_statistics_unit_for_table	(	Session	session,
		type[StatisticsBase]	table,
		int	metadata_id,
		Callable[[float \| None], float \| None]	convert
	)

private

Insert statistics in the database.

Definition at line 2489 of file statistics.py.

◆ _compile_hourly_statistics()

None homeassistant.components.recorder.statistics._compile_hourly_statistics	(	Session	session,
		datetime	start
	)

private

Compile hourly statistics.

This will summarize 5-minute statistics for one hour:
- average, min max is computed by a database query
- sum is taken from the last 5-minute entry during the hour

Definition at line 398 of file statistics.py.

◆ _compile_hourly_statistics_last_sum_stmt()

StatementLambdaElement homeassistant.components.recorder.statistics._compile_hourly_statistics_last_sum_stmt	(	float	start_time_ts,
		float	end_time_ts
	)

private

Generate the summary mean statement for hourly statistics.

Definition at line 380 of file statistics.py.

◆ _compile_hourly_statistics_summary_mean_stmt()

StatementLambdaElement homeassistant.components.recorder.statistics._compile_hourly_statistics_summary_mean_stmt	(	float	start_time_ts,
		float	end_time_ts
	)

private

Generate the summary mean statement for hourly statistics.

Definition at line 367 of file statistics.py.

◆ _compile_statistics()

set[str] homeassistant.components.recorder.statistics._compile_statistics	(	Recorder	instance,
		Session	session,
		datetime	start,
		bool	fire_events
	)

private

Compile 5-minute statistics for all integrations with a recorder platform.

This is a helper function for compile_statistics and compile_missing_statistics
that does not retry on database errors since both callers already retry.

returns a set of modified statistic_ids if any were modified.

Definition at line 535 of file statistics.py.

◆ _extract_metadata_and_discard_impossible_columns()

list[int] homeassistant.components.recorder.statistics._extract_metadata_and_discard_impossible_columns	(	dict[str, tuple[int, StatisticMetaData]]	metadata,
		set[Literal["last_reset", "max", "mean", "min", "state", "sum"]]	types
	)

private

Extract metadata ids from metadata and discard impossible columns.

Definition at line 1635 of file statistics.py.

◆ _find_latest_short_term_statistic_for_metadata_id_stmt()

StatementLambdaElement homeassistant.components.recorder.statistics._find_latest_short_term_statistic_for_metadata_id_stmt ( int metadata_id )

private

Create a statement to find the latest short term statistics for a metadata_id.

Definition at line 2400 of file statistics.py.

◆ _find_month_end_time()

datetime homeassistant.components.recorder.statistics._find_month_end_time ( datetime timestamp )

private

Return the end of the month (midnight at the first day of the next month).

Definition at line 1068 of file statistics.py.

◆ _first_statistic()

datetime \| None homeassistant.components.recorder.statistics._first_statistic	(	Session	session,
		type[StatisticsBase]	table,
		int	metadata_id
	)

private

Return the date of the oldest statistic row for a given metadata id.

Definition at line 1267 of file statistics.py.

◆ _flatten_list_statistic_ids_metadata_result()

list[dict] homeassistant.components.recorder.statistics._flatten_list_statistic_ids_metadata_result ( dict[str, dict[str, Any]] result )

private

Return a flat dict of metadata.

Definition at line 835 of file statistics.py.

◆ _generate_max_mean_min_statistic_in_sub_period_stmt()

StatementLambdaElement homeassistant.components.recorder.statistics._generate_max_mean_min_statistic_in_sub_period_stmt	(	Select	columns,
		datetime \| None	start_time,
		datetime \| None	end_time,
		type[StatisticsBase]	table,
		int	metadata_id
	)

private

Definition at line 1146 of file statistics.py.

◆ _generate_select_columns_for_types_stmt()

StatementLambdaElement homeassistant.components.recorder.statistics._generate_select_columns_for_types_stmt	(	type[StatisticsBase]	table,
		set[Literal["last_reset", "max", "mean", "min", "state", "sum"]]	types
	)

private

Definition at line 1618 of file statistics.py.

◆ _generate_statistics_at_time_stmt()

StatementLambdaElement homeassistant.components.recorder.statistics._generate_statistics_at_time_stmt	(	type[StatisticsBase]	table,
		set[int]	metadata_ids,
		float	start_time_ts,
		set[Literal["last_reset", "max", "mean", "min", "state", "sum"]]	types
	)

private

Create the statement for finding the statistics for a given time.

Definition at line 2029 of file statistics.py.

◆ _generate_statistics_during_period_stmt()

StatementLambdaElement homeassistant.components.recorder.statistics._generate_statistics_during_period_stmt	(	datetime	start_time,
		datetime \| None	end_time,
		list[int] \| None	metadata_ids,
		type[StatisticsBase]	table,
		set[Literal["last_reset", "max", "mean", "min", "state", "sum"]]	types
	)

private

Prepare a database query for statistics during a given period.

This prepares a lambda_stmt query, so we don't insert the parameters yet.

Definition at line 1123 of file statistics.py.

◆ _get_display_to_statistic_unit_converter()

Callable[[float], float] \| None homeassistant.components.recorder.statistics._get_display_to_statistic_unit_converter	(	str \| None	display_unit,
		str \| None	statistic_unit
	)

private

Prepare a converter from the display unit to the statistics unit.

Definition at line 280 of file statistics.py.

◆ _get_first_id_stmt()

StatementLambdaElement homeassistant.components.recorder.statistics._get_first_id_stmt ( datetime start )

private

Return a statement that returns the first run_id at start.

Definition at line 530 of file statistics.py.

◆ _get_last_statistics()

dict[str, list[StatisticsRow]] homeassistant.components.recorder.statistics._get_last_statistics	(	HomeAssistant	hass,
		int	number_of_stats,
		str	statistic_id,
		bool	convert_units,
		type[StatisticsBase]	table,
		set[Literal["last_reset", "max", "mean", "min", "state", "sum"]]	types
	)

private

Return the last number_of_stats statistics for a given statistic_id.

Definition at line 1873 of file statistics.py.

◆ _get_last_statistics_short_term_stmt()

StatementLambdaElement homeassistant.components.recorder.statistics._get_last_statistics_short_term_stmt	(	int	metadata_id,
		int	number_of_stats
	)

private

Generate a statement for number_of_stats short term statistics.

For a given statistic_id.

Definition at line 1857 of file statistics.py.

◆ _get_last_statistics_stmt()

StatementLambdaElement homeassistant.components.recorder.statistics._get_last_statistics_stmt	(	int	metadata_id,
		int	number_of_stats
	)

private

Generate a statement for number_of_stats statistics for a given statistic_id.

Definition at line 1844 of file statistics.py.

◆ _get_max_mean_min_statistic()

dict[str, float \| None] homeassistant.components.recorder.statistics._get_max_mean_min_statistic	(	Session	session,
		datetime \| None	head_start_time,
		datetime \| None	head_end_time,
		datetime \| None	main_start_time,
		datetime \| None	main_end_time,
		datetime \| None	tail_start_time,
		datetime \| None	tail_end_time,
		bool	tail_only,
		int	metadata_id,
		set[Literal["max", "mean", "min", "change"]]	types
	)

private

Return max, mean and min during the period.

The mean is a time weighted average, combining hourly and 5-minute statistics if
necessary.

Definition at line 1201 of file statistics.py.

◆ _get_max_mean_min_statistic_in_sub_period()

None homeassistant.components.recorder.statistics._get_max_mean_min_statistic_in_sub_period	(	Session	session,
		dict[str, float]	result,
		datetime \| None	start_time,
		datetime \| None	end_time,
		type[StatisticsBase]	table,
		set[Literal["max", "mean", "min", "change"]]	types,
		int	metadata_id
	)

private

Return max, mean and min during the period.

Definition at line 1163 of file statistics.py.

◆ _get_newest_sum_statistic()

float \| None homeassistant.components.recorder.statistics._get_newest_sum_statistic	(	Session	session,
		datetime \| None	head_start_time,
		datetime \| None	head_end_time,
		datetime \| None	main_start_time,
		datetime \| None	main_end_time,
		datetime \| None	tail_start_time,
		datetime \| None	tail_end_time,
		bool	tail_only,
		int	metadata_id
	)

private

Return the newest non-NULL sum during the period.

Definition at line 1392 of file statistics.py.

◆ _get_oldest_sum_statistic()

float \| None homeassistant.components.recorder.statistics._get_oldest_sum_statistic	(	Session	session,
		datetime \| None	head_start_time,
		datetime \| None	main_start_time,
		datetime \| None	tail_start_time,
		datetime \| None	oldest_stat,
		datetime \| None	oldest_5_min_stat,
		bool	tail_only,
		int	metadata_id
	)

private

Return the oldest non-NULL sum during the period.

Definition at line 1301 of file statistics.py.

◆ _get_statistic_to_display_unit_converter()

Callable[[float \| None], float \| None] \| Callable[[float], float] \| None homeassistant.components.recorder.statistics._get_statistic_to_display_unit_converter	(	str \| None	statistic_unit,
		str \| None	state_unit,
		dict[str, str] \| None	requested_units,
		bool	allow_none = `True`
	)

private

Prepare a converter from the statistics unit to display unit.

Definition at line 249 of file statistics.py.

◆ _get_unit_converter()

Callable[[float \| None], float \| None] \| None homeassistant.components.recorder.statistics._get_unit_converter	(	str	from_unit,
		str	to_unit
	)

private

Prepare a converter from a unit to another unit.

Definition at line 293 of file statistics.py.

◆ _import_statistics_with_session()

bool homeassistant.components.recorder.statistics._import_statistics_with_session	(	Recorder	instance,
		Session	session,
		StatisticMetaData	metadata,
		Iterable[StatisticData]	statistics,
		type[StatisticsBase]	table
	)

private

Import statistics to the database.

Definition at line 2335 of file statistics.py.

◆ _insert_statistics()

StatisticsBase \| None homeassistant.components.recorder.statistics._insert_statistics	(	Session	session,
		type[StatisticsBase]	table,
		int	metadata_id,
		StatisticData	statistic
	)

private

Insert statistics in the database.

Definition at line 664 of file statistics.py.

◆ _last_statistic()

datetime \| None homeassistant.components.recorder.statistics._last_statistic	(	Session	session,
		type[StatisticsBase]	table,
		int	metadata_id
	)

private

Return the date of the newest statistic row for a given metadata id.

Definition at line 1284 of file statistics.py.

◆ _latest_short_term_statistics_by_ids_stmt()

StatementLambdaElement homeassistant.components.recorder.statistics._latest_short_term_statistics_by_ids_stmt ( Iterable[int] ids )

private

Create the statement for finding the latest short term stat rows by id.

Definition at line 1955 of file statistics.py.

◆ _reduce_statistics()

dict[str, list[StatisticsRow]] homeassistant.components.recorder.statistics._reduce_statistics	(	dict[str, list[StatisticsRow]]	stats,
		Callable[[float, float], bool]	same_period,
		Callable[[float], tuple[float, float]]	period_start_end,
		timedelta	period,
		set[Literal["last_reset", "max", "mean", "min", "state", "sum"]]	types
	)

private

Reduce hourly statistics to daily or monthly statistics.

Definition at line 910 of file statistics.py.

◆ _reduce_statistics_per_day()

dict[str, list[StatisticsRow]] homeassistant.components.recorder.statistics._reduce_statistics_per_day	(	dict[str, list[StatisticsRow]]	stats,
		set[Literal["last_reset", "max", "mean", "min", "state", "sum"]]	types
	)

private

Reduce hourly statistics to daily statistics.

Definition at line 1007 of file statistics.py.

◆ _reduce_statistics_per_month()

dict[str, list[StatisticsRow]] homeassistant.components.recorder.statistics._reduce_statistics_per_month	(	dict[str, list[StatisticsRow]]	stats,
		set[Literal["last_reset", "max", "mean", "min", "state", "sum"]]	types
	)

private

Reduce hourly statistics to monthly statistics.

Definition at line 1112 of file statistics.py.

◆ _reduce_statistics_per_week()

dict[str, list[StatisticsRow]] homeassistant.components.recorder.statistics._reduce_statistics_per_week	(	dict[str, list[StatisticsRow]]	stats,
		set[Literal["last_reset", "max", "mean", "min", "state", "sum"]]	types
	)

private

Reduce hourly statistics to weekly statistics.

Definition at line 1057 of file statistics.py.

◆ _sorted_statistics_to_dict()

dict[str, list[StatisticsRow]] homeassistant.components.recorder.statistics._sorted_statistics_to_dict	(	HomeAssistant	hass,
		Sequence[Row[Any]]	stats,
		set[str] \| None	statistic_ids,
		dict[str, tuple[int, StatisticMetaData]]	_metadata,
		bool	convert_units,
		type[StatisticsBase]	table,
		dict[str, str] \| None	units,
		set[Literal["last_reset", "max", "mean", "min", "state", "sum"]]	types
	)

private

Convert SQL results into JSON friendly data structure.

Definition at line 2144 of file statistics.py.

◆ _statistic_by_id_from_metadata()

dict[str, dict[str, Any]] homeassistant.components.recorder.statistics._statistic_by_id_from_metadata	(	HomeAssistant	hass,
		dict[str, tuple[int, StatisticMetaData]]	metadata
	)

private

Return a list of results for a given metadata dict.

Definition at line 814 of file statistics.py.

◆ _statistics_at_time()

Sequence[Row] \| None homeassistant.components.recorder.statistics._statistics_at_time	(	Session	session,
		set[int]	metadata_ids,
		type[StatisticsBase]	table,
		datetime	start_time,
		set[Literal["last_reset", "max", "mean", "min", "state", "sum"]]	types
	)

private

Return last known statistics, earlier than start_time, for the metadata_ids.

Definition at line 2058 of file statistics.py.

◆ _statistics_during_period_with_session()

dict[str, list[StatisticsRow]] homeassistant.components.recorder.statistics._statistics_during_period_with_session	(	HomeAssistant	hass,
		Session	session,
		datetime	start_time,
		datetime \| None	end_time,
		set[str] \| None	statistic_ids,
		Literal["5minute", "day", "hour", "week", "month"]	period,
		dict[str, str] \| None	units,
		set[Literal["change", "last_reset", "max", "mean", "min", "state", "sum"]]	_types
	)

private

Return statistic data points during UTC period start_time - end_time.

If end_time is omitted, returns statistics newer than or equal to start_time.
If statistic_ids is omitted, returns statistics for all statistics ids.

Definition at line 1708 of file statistics.py.

◆ _statistics_exists()

int \| None homeassistant.components.recorder.statistics._statistics_exists	(	Session	session,
		type[StatisticsBase]	table,
		int	metadata_id,
		datetime	start
	)

private

Return id if a statistics entry already exists.

Definition at line 2244 of file statistics.py.

◆ _update_statistics()

None homeassistant.components.recorder.statistics._update_statistics	(	Session	session,
		type[StatisticsBase]	table,
		int	stat_id,
		StatisticData	statistic
	)

private

Insert statistics in the database.

Definition at line 684 of file statistics.py.

◆ adjust_statistics()

bool homeassistant.components.recorder.statistics.adjust_statistics	(	Recorder	instance,
		str	statistic_id,
		datetime	start_time,
		float	sum_adjustment,
		str	adjustment_unit
	)

Process an add_statistics job.

Definition at line 2448 of file statistics.py.

◆ async_add_external_statistics()

None homeassistant.components.recorder.statistics.async_add_external_statistics	(	HomeAssistant	hass,
		StatisticMetaData	metadata,
		Iterable[StatisticData]	statistics
	)

Add hourly statistics from an external source.

This inserts an import_statistics job in the recorder's queue.

Definition at line 2314 of file statistics.py.

◆ async_change_statistics_unit()

None homeassistant.components.recorder.statistics.async_change_statistics_unit	(	HomeAssistant	hass,
		str	statistic_id,
		*str	new_unit_of_measurement,
		str	old_unit_of_measurement
	)

Change statistics unit for a statistic_id.

Definition at line 2556 of file statistics.py.

◆ async_import_statistics()

None homeassistant.components.recorder.statistics.async_import_statistics	(	HomeAssistant	hass,
		StatisticMetaData	metadata,
		Iterable[StatisticData]	statistics
	)

Import hourly statistics from an internal source.

This inserts an import_statistics job in the recorder's queue.

Definition at line 2294 of file statistics.py.

◆ async_list_statistic_ids()

list[dict] homeassistant.components.recorder.statistics.async_list_statistic_ids	(	HomeAssistant	hass,
		set[str] \| None	statistic_ids = `None`,
		Literal["mean", "sum"] \| None	statistic_type = `None`
	)

Return all statistic_ids (or filtered one) and unit of measurement.

Queries the database for existing statistic_ids, as well as integrations with
a recorder platform for statistic_ids which will be added in the next statistics
period.

Definition at line 784 of file statistics.py.

◆ cache_latest_short_term_statistic_id_for_metadata_id()

int \| None homeassistant.components.recorder.statistics.cache_latest_short_term_statistic_id_for_metadata_id	(	ShortTermStatisticsRunCache	run_cache,
		Session	session,
		int	metadata_id
	)

Cache the latest short term statistic for a given metadata_id.

Returns the id of the latest short term statistic for the metadata_id
that was added to the cache, or None if no latest short term statistic
was found for the metadata_id.

Definition at line 2377 of file statistics.py.

◆ can_convert_units()

bool homeassistant.components.recorder.statistics.can_convert_units	(	str \| None	from_unit,
		str \| None	to_unit
	)

Return True if it's possible to convert from from_unit to to_unit.

Definition at line 307 of file statistics.py.

◆ change_statistics_unit()

None homeassistant.components.recorder.statistics.change_statistics_unit	(	Recorder	instance,
		str	statistic_id,
		str	new_unit,
		str	old_unit
	)

Change statistics unit for a statistic_id.

Definition at line 2512 of file statistics.py.

◆ cleanup_statistics_timestamp_migration()

bool homeassistant.components.recorder.statistics.cleanup_statistics_timestamp_migration ( Recorder instance )

Clean up the statistics migration from timestamp to datetime.

Returns False if there are more rows to update.
Returns True if all rows have been updated.

Definition at line 2576 of file statistics.py.

◆ clear_statistics()

None homeassistant.components.recorder.statistics.clear_statistics	(	Recorder	instance,
		list[str]	statistic_ids
	)

Clear statistics for a list of statistic_ids.

Definition at line 753 of file statistics.py.

◆ compile_missing_statistics()

bool homeassistant.components.recorder.statistics.compile_missing_statistics ( Recorder instance )

Compile missing statistics.

Definition at line 456 of file statistics.py.

◆ compile_statistics()

bool homeassistant.components.recorder.statistics.compile_statistics	(	Recorder	instance,
		datetime	start,
		bool	fire_events
	)

Compile 5-minute statistics for all integrations with a recorder platform.

The actual calculation is delegated to the platforms.

Definition at line 497 of file statistics.py.

◆ get_display_unit()

str \| None homeassistant.components.recorder.statistics.get_display_unit	(	HomeAssistant	hass,
		str	statistic_id,
		str \| None	statistic_unit
	)

Return the unit which the statistic will be displayed in.

Definition at line 228 of file statistics.py.

◆ get_last_short_term_statistics()

dict[str, list[StatisticsRow]] homeassistant.components.recorder.statistics.get_last_short_term_statistics	(	HomeAssistant	hass,
		int	number_of_stats,
		str	statistic_id,
		bool	convert_units,
		set[Literal["last_reset", "max", "mean", "min", "state", "sum"]]	types
	)

Return the last number_of_stats short term statistics for a statistic_id.

Definition at line 1929 of file statistics.py.

◆ get_last_statistics()

dict[str, list[StatisticsRow]] homeassistant.components.recorder.statistics.get_last_statistics	(	HomeAssistant	hass,
		int	number_of_stats,
		str	statistic_id,
		bool	convert_units,
		set[Literal["last_reset", "max", "mean", "min", "state", "sum"]]	types
	)

Return the last number_of_stats statistics for a statistic_id.

Definition at line 1916 of file statistics.py.

◆ get_latest_short_term_statistics_by_ids()

list[Row] homeassistant.components.recorder.statistics.get_latest_short_term_statistics_by_ids	(	Session	session,
		Iterable[int]	ids
	)

Return the latest short term statistics for a list of ids.

Definition at line 1942 of file statistics.py.

◆ get_latest_short_term_statistics_with_session()

dict[str, list[StatisticsRow]] homeassistant.components.recorder.statistics.get_latest_short_term_statistics_with_session	(	HomeAssistant	hass,
		Session	session,
		set[str]	statistic_ids,
		set[Literal["last_reset", "max", "mean", "min", "state", "sum"]]	types,
		dict[str, tuple[int, StatisticMetaData]] \| None	metadata = `None`
	)

Return the latest short term statistics for a list of statistic_ids with a session.

Definition at line 1966 of file statistics.py.

◆ get_metadata()

dict[str, tuple[int, StatisticMetaData]] homeassistant.components.recorder.statistics.get_metadata	(	HomeAssistant	hass,
		*set[str] \| None	statistic_ids = `None`,
		Literal["mean", "sum"] \| None	statistic_type = `None`,
		str \| None	statistic_source = `None`
	)

Return metadata for statistic_ids.

Definition at line 735 of file statistics.py.

◆ get_metadata_with_session()

dict[str, tuple[int, StatisticMetaData]] homeassistant.components.recorder.statistics.get_metadata_with_session	(	Recorder	instance,
		Session	session,
		*set[str] \| None	statistic_ids = `None`,
		Literal["mean", "sum"] \| None	statistic_type = `None`,
		str \| None	statistic_source = `None`
	)

Fetch meta data.

Returns a dict of (metadata_id, StatisticMetaData) tuples indexed by statistic_id.
If statistic_ids is given, fetch metadata only for the listed statistics_ids.
If statistic_type is given, fetch metadata only for statistic_ids supporting it.

Definition at line 713 of file statistics.py.

◆ get_short_term_statistics_run_cache()

ShortTermStatisticsRunCache homeassistant.components.recorder.statistics.get_short_term_statistics_run_cache ( HomeAssistant hass )

Get the short term statistics run cache.

Definition at line 2370 of file statistics.py.

◆ get_start_time()

datetime homeassistant.components.recorder.statistics.get_start_time ( )

Return start time.

Definition at line 359 of file statistics.py.

◆ import_statistics()

bool homeassistant.components.recorder.statistics.import_statistics	(	Recorder	instance,
		StatisticMetaData	metadata,
		Iterable[StatisticData]	statistics,
		type[StatisticsBase]	table
	)

Process an import_statistics job.

Definition at line 2428 of file statistics.py.

◆ list_statistic_ids()

list[dict] homeassistant.components.recorder.statistics.list_statistic_ids	(	HomeAssistant	hass,
		set[str] \| None	statistic_ids = `None`,
		Literal["mean", "sum"] \| None	statistic_type = `None`
	)

Return all statistic_ids (or filtered one) and unit of measurement.

Queries the database for existing statistic_ids, as well as integrations with
a recorder platform for statistic_ids which will be added in the next statistics
period.

Definition at line 854 of file statistics.py.

◆ mean()

float | None homeassistant.components.recorder.statistics.mean ( list[float] values )

Return the mean of the values.

This is a very simple version that only works
with a non-empty list of floats. The built-in
statistics.mean is more robust but is almost
an order of magnitude slower.

Definition at line 168 of file statistics.py.

◆ reduce_day_ts_factory()

( tuple[ Callable[[float, float], bool], Callable[[float], tuple[float, float]], ] ) homeassistant.components.recorder.statistics.reduce_day_ts_factory ( )

Return functions to match same day and day start end.

Definition at line 969 of file statistics.py.

◆ reduce_month_ts_factory()

( tuple[ Callable[[float, float], bool], Callable[[float], tuple[float, float]], ] ) homeassistant.components.recorder.statistics.reduce_month_ts_factory ( )

Return functions to match same month and month start end.

Definition at line 1076 of file statistics.py.

◆ reduce_week_ts_factory()

( tuple[ Callable[[float, float], bool], Callable[[float], tuple[float, float]], ] ) homeassistant.components.recorder.statistics.reduce_week_ts_factory ( )

Return functions to match same week and week start end.

Definition at line 1018 of file statistics.py.

◆ split_statistic_id()

list[str] homeassistant.components.recorder.statistics.split_statistic_id ( str entity_id )

Split a state entity ID into domain and object ID.

Definition at line 323 of file statistics.py.

◆ statistic_during_period()

dict[str, Any] homeassistant.components.recorder.statistics.statistic_during_period	(	HomeAssistant	hass,
		datetime \| None	start_time,
		datetime \| None	end_time,
		str	statistic_id,
		set[Literal["max", "mean", "min", "change"]] \| None	types,
		dict[str, str] \| None	units
	)

Return a statistic data point for the UTC period start_time - end_time.

Definition at line 1456 of file statistics.py.

◆ statistics_during_period()

dict[str, list[StatisticsRow]] homeassistant.components.recorder.statistics.statistics_during_period	(	HomeAssistant	hass,
		datetime	start_time,
		datetime \| None	end_time,
		set[str] \| None	statistic_ids,
		Literal["5minute", "day", "hour", "week", "month"]	period,
		dict[str, str] \| None	units,
		set[Literal["change", "last_reset", "max", "mean", "min", "state", "sum"]]	types
	)

Return statistic data points during UTC period start_time - end_time.

If end_time is omitted, returns statistics newer than or equal to start_time.
If statistic_ids is omitted, returns statistics for all statistics ids.

Definition at line 1817 of file statistics.py.

◆ update_statistics_issues()

None homeassistant.components.recorder.statistics.update_statistics_issues ( HomeAssistant hass )

Update statistics issues.

Definition at line 2234 of file statistics.py.

◆ update_statistics_metadata()

None homeassistant.components.recorder.statistics.update_statistics_metadata	(	Recorder	instance,
		str	statistic_id,
		str \| None \| UndefinedType	new_statistic_id,
		str \| None \| UndefinedType	new_unit_of_measurement
	)

Update statistics metadata for a statistic_id.

Definition at line 759 of file statistics.py.

◆ valid_statistic_id()

bool homeassistant.components.recorder.statistics.valid_statistic_id ( str statistic_id )

Test if a statistic ID is a valid format.

Format: <domain>:<statistic> where both are slugs.

Definition at line 331 of file statistics.py.

◆ validate_statistic_id()

str homeassistant.components.recorder.statistics.validate_statistic_id ( str value )

Validate statistic ID.

Definition at line 339 of file statistics.py.

◆ validate_statistics()

dict[str, list[ValidationIssue]] homeassistant.components.recorder.statistics.validate_statistics ( HomeAssistant hass )

Validate statistics.

Definition at line 2223 of file statistics.py.

Variable Documentation

◆ _LOGGER

homeassistant.components.recorder.statistics._LOGGER = logging.getLogger(__name__)

private

Definition at line 179 of file statistics.py.

◆ _type_column_mapping

dictionary homeassistant.components.recorder.statistics._type_column_mapping

private

Initial value:

 =  {
     "last_reset": "last_reset_ts",
     "max": "max",
     "mean": "mean",
     "min": "min",
     "state": "state",
     "sum": "sum",
 }

Definition at line 1608 of file statistics.py.

◆ DATA_SHORT_TERM_STATISTICS_RUN_CACHE

string homeassistant.components.recorder.statistics.DATA_SHORT_TERM_STATISTICS_RUN_CACHE = "recorder_short_term_statistics_run_cache"

Definition at line 165 of file statistics.py.

◆ QUERY_STATISTICS

tuple homeassistant.components.recorder.statistics.QUERY_STATISTICS

Initial value:

 =  (
     Statistics.metadata_id,
     Statistics.start_ts,
     Statistics.mean,
     Statistics.min,
     Statistics.max,
     Statistics.last_reset_ts,
     Statistics.state,
     Statistics.sum,
 )

Definition at line 88 of file statistics.py.

◆ QUERY_STATISTICS_SHORT_TERM

tuple homeassistant.components.recorder.statistics.QUERY_STATISTICS_SHORT_TERM

Initial value:

 =  (
     StatisticsShortTerm.metadata_id,
     StatisticsShortTerm.start_ts,
     StatisticsShortTerm.mean,
     StatisticsShortTerm.min,
     StatisticsShortTerm.max,
     StatisticsShortTerm.last_reset_ts,
     StatisticsShortTerm.state,
     StatisticsShortTerm.sum,
 )

Definition at line 99 of file statistics.py.

◆ QUERY_STATISTICS_SUMMARY_MEAN

tuple homeassistant.components.recorder.statistics.QUERY_STATISTICS_SUMMARY_MEAN

Initial value:

 =  (
     StatisticsShortTerm.metadata_id,
     func.avg(StatisticsShortTerm.mean),
     func.min(StatisticsShortTerm.min),
     func.max(StatisticsShortTerm.max),
 )

Definition at line 110 of file statistics.py.

◆ QUERY_STATISTICS_SUMMARY_SUM

tuple homeassistant.components.recorder.statistics.QUERY_STATISTICS_SUMMARY_SUM

Initial value:

 =  (
     StatisticsShortTerm.metadata_id,
     StatisticsShortTerm.start_ts,
     StatisticsShortTerm.last_reset_ts,
     StatisticsShortTerm.state,
     StatisticsShortTerm.sum,
     func.row_number()
     .over(
         partition_by=StatisticsShortTerm.metadata_id,
         order_by=StatisticsShortTerm.start_ts.desc(),
     )
     .label("rownum"),
 )

Definition at line 117 of file statistics.py.

◆ UNIT_CLASSES

dictionary homeassistant.components.recorder.statistics.UNIT_CLASSES

Initial value:

 =  {
     unit: converter.UNIT_CLASS
     for unit, converter in STATISTIC_UNIT_TO_UNIT_CONVERTER.items()
 }

Definition at line 160 of file statistics.py.

◆ VALID_STATISTIC_ID

homeassistant.components.recorder.statistics.VALID_STATISTIC_ID = re.compile(r"^(?!.+__)(?!_)[\da-z_]+(?<!_):(?!_)[\da-z_]+(?<!_)$")

Definition at line 328 of file statistics.py.

Home Assistant Unofficial Reference 2024.12.1

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ _adjust_sum_statistics()

◆ _async_import_statistics()

◆ _augment_result_with_change()

◆ _build_converted_stats()

◆ _build_stats()

◆ _build_sum_converted_stats()

◆ _build_sum_stats()

◆ _change_statistics_unit_for_table()

◆ _compile_hourly_statistics()

◆ _compile_hourly_statistics_last_sum_stmt()

◆ _compile_hourly_statistics_summary_mean_stmt()

◆ _compile_statistics()

◆ _extract_metadata_and_discard_impossible_columns()

◆ _find_latest_short_term_statistic_for_metadata_id_stmt()

◆ _find_month_end_time()

◆ _first_statistic()

◆ _flatten_list_statistic_ids_metadata_result()

◆ _generate_max_mean_min_statistic_in_sub_period_stmt()

◆ _generate_select_columns_for_types_stmt()

◆ _generate_statistics_at_time_stmt()

◆ _generate_statistics_during_period_stmt()

◆ _get_display_to_statistic_unit_converter()

◆ _get_first_id_stmt()

◆ _get_last_statistics()

◆ _get_last_statistics_short_term_stmt()

◆ _get_last_statistics_stmt()

◆ _get_max_mean_min_statistic()

◆ _get_max_mean_min_statistic_in_sub_period()

◆ _get_newest_sum_statistic()

◆ _get_oldest_sum_statistic()

◆ _get_statistic_to_display_unit_converter()

◆ _get_unit_converter()

◆ _import_statistics_with_session()

◆ _insert_statistics()

◆ _last_statistic()

◆ _latest_short_term_statistics_by_ids_stmt()

◆ _reduce_statistics()

◆ _reduce_statistics_per_day()

◆ _reduce_statistics_per_month()

◆ _reduce_statistics_per_week()

◆ _sorted_statistics_to_dict()

◆ _statistic_by_id_from_metadata()

◆ _statistics_at_time()

◆ _statistics_during_period_with_session()

◆ _statistics_exists()

◆ _update_statistics()

◆ adjust_statistics()

◆ async_add_external_statistics()

◆ async_change_statistics_unit()

◆ async_import_statistics()

◆ async_list_statistic_ids()

◆ cache_latest_short_term_statistic_id_for_metadata_id()

◆ can_convert_units()

◆ change_statistics_unit()

◆ cleanup_statistics_timestamp_migration()

◆ clear_statistics()

◆ compile_missing_statistics()

◆ compile_statistics()

◆ get_display_unit()

◆ get_last_short_term_statistics()

◆ get_last_statistics()

◆ get_latest_short_term_statistics_by_ids()

◆ get_latest_short_term_statistics_with_session()

◆ get_metadata()

◆ get_metadata_with_session()

◆ get_short_term_statistics_run_cache()

◆ get_start_time()

◆ import_statistics()

◆ list_statistic_ids()

◆ mean()

◆ reduce_day_ts_factory()

◆ reduce_month_ts_factory()

◆ reduce_week_ts_factory()

◆ split_statistic_id()

◆ statistic_during_period()