Examples¶
These showcase simple examples of using basic Python object notation, along with comprenhensions, to get command line access to Home Assistant APIs and data.
API Mode¶
Note
These examples don't need anything installed on the Home Assistant server - all you need is the Long Lived Access Token.
Object Tree¶
Inspect an entity¶
obj["/mqtt/sensor/greenhouse_temperature"] # by object tree path
obj["sensor.greenhouse_temperature"] # by HA entity_id
Find objects¶
Get an iterable of entity objects by reg exp on object tree and do something with them
Add a filter, and return a tuple of values, in this case listing all the entities that seem to be in the greenhouse that don't have the right area assigned
Find object names¶
[n for n in obj.find_names(platform="mqtt" domain="binary_sensor") if 'detector' in n and 'test' not in n]
Also possible to use regular expressions to find things, which can be combined with the platform etc filters
Entity and Entity Registry inspection¶
Find me all the MQTT devices that are exposed to Alexa.
Note
get("cloud.alexa",{}) used rather than ["cloud_alexa"] since not all entities will have this structure.
[
o.entity_id
for o in obj.find(platform="mqtt", object_type="entity")
if o.registry_entry.options.get("cloud.alexa", {}).get("should_expose", {})
]
homeassistant-api integration¶
Traverse the objects¶
Tip
More examples for hass_api at the homeassistant-api docs.
Live Mode¶
Note
These examples need the Live Server Marketplace component installed on a Home Assistant server.
hass object¶
Simple entity fetch¶
hass.states.get("sun.sun") # returns a `State` object
hass.states.get("sun.sun").state # returns sun position as string
hass.states.get("sun.sun").attributes["next_dawn"] # date time from attributes
Look inside an object¶
show() gives the attributes and their values, where the object alone would print as its class name.
show(hass.config)
show(hass.states.get("sun.sun"))
show(hass.config_entries.async_entries("mqtt")[0], private=True)
Get integration data¶
Note that each integration can have wildly different data, and some like mqtt can be huge.
Mapping of all notify entities by platform name¶
SQL¶
Get a list of tables and their columns¶
Quick analysis of tables¶
Joins¶
Get the event data when dumping events. The event_history virtual table already has the textual event type, and is joined here like any table.
Long term statistics for an entity¶
The statistics_history virtual table has an hourly row for each statistic, kept after state history has been purged.
sql("""
select start_ts, mean, min, max, state, sum
from statistics_history
where statistic_id = 'sensor.outside_temperature'
order by start_ts desc
""").show()
State history for an entity¶
stateshas no entity id of its own, so this uses thestate_historyvirtual table, which adds it- Times are seconds since the epoch, in the
_tscolumns, so the cutoff is worked out in Python. In the result they are datetimes
import time
since = time.time() - 24 * 3600
sql(f"""
select state, last_updated_ts
from state_history
where entity_id = 'update.home_assistant_core_update' and last_updated_ts > {since}
order by last_updated_ts desc
""").show()
Find the top talkers¶
This uses a HAVING query to filter the aggregate values.
It also writes out the join of states to states_meta that gets each state's entity id, to show what the state_history virtual table stands for. The other examples here use a virtual table instead.
sql("""
SELECT m.entity_id, COUNT(*) as "States"
FROM states s
INNER JOIN states_meta m ON m.metadata_id = s.metadata_id
GROUP BY m.entity_id
HAVING COUNT(*) > 100
ORDER BY COUNT(*) DESC
""").show()
Distinct field analysis¶
[0][0]notation here means get me the value of the first column of the first row.- Dictionary comprehension to do all the analysis and build report in one line
fstring to build a simple query- Could extend this to
legacycolumns by passinglegacy=trueon thesqlandsql.tablecalls
{ col:sql(f'select count(distinct {col}) from events')[0][0] for col
in sql.table("events").column_names }
{
'event_id': 173121,
'origin_idx': 2,
'time_fired_ts': 173112,
'data_id': 97248,
'context_id_bin': 161680,
'context_user_id_bin': 4,
'context_parent_id_bin': 1679,
'event_type_id': 42
}
Domain / Cardinality analysis on states¶
This is a handy way of checking the variability within column states - how many values, how many unique values and the max and minimum values (which could be numeric or string, the latter sorting alphanumerically).
It also demonstrates column renaming for the result sets, and filtering the state_history virtual table with a where clause, with no join or table aliases needed. Note that the formatting and upper case here is purely for readability.
sql("""
SELECT entity_id,
COUNT(*) as States,
COUNT(distinct state) as "Distinct States",
MIN(state) as "Min State",
MAX(state) as "Max State"
FROM state_history
WHERE entity_id like 'sensor.%'
GROUP BY entity_id
""").show()
Tip
For more advanced data analysis, use polars or pandas
and turn the sql result into a dataframe using to_polars() or to_pandas()