InfluxDB
The influxdb
integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] makes it possible to transfer all state changes to an external InfluxDB
Additionally, you can now make use of an InfluxDB 2.0 installation with this integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more]. See the official installation instructions
There is currently support for the following device types within Home Assistant:
The influxdb
database integration runs parallel to the Home Assistant database. It does not replace it.
Configuration
The default InfluxDB configuration doesn’t enforce authentication. If you have installed InfluxDB on the same host where Home Assistant is running and haven’t made any configuration changes, add the following to your configuration.yaml
The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file.
After changing the configuration.yaml
The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file, restart Home Assistant to apply the changes. The integration is now shown on the integrations page under Settings > Devices & services. Its entities are listed on the integration card itself and on the Entities tab.
# Example configuration.yaml entry
influxdb:
You will still need (not for version 2) to create a database named home_assistant
via InfluxDB’s command-line interface. For instructions on how to create a database check the InfluxDB documentation
Configuration Variables
Use HTTPS instead of HTTP to connect. 2.xx - Defaults to true
for 2.xx, false otherwise false
.
IP address or domain of your database host, e.g., 192.168.1.10. 2.xx - Defaults to ‘us-west-2-1.aws.cloud2.influxdata.com’ for 2.xx, not ‘localhost’.
Port to use. 2.xx - Must specify port for 2.xx, otherwise 8086.
1.xx only - The username of the database user. The user needs read/write privileges on the database.
1.xx only - The password for the database user account. Needed with username
configuration variable.
1.xx only - Name of the database to use. The database must already exist.
Verify SSL certificate for HTTPS request. This can take on boolean values false
or true
.
Optional path of a CA certificate to be used during SSL verification.
2.xx only - Auth token with WRITE access to your chosen Organization and Bucket. Needed with organization
configuration variable.
2.xx only - Organization ID to write to. To obtain this, open the UI of your 2.xx installation, the URL at the top will have it after /orgs
. For example, in InfluxDB Cloud it looks like this: https://us-west-2-1.aws.cloud2.influxdata.com/orgs/{OrganizationID}token
configuration variable.
2.xx only - Name of the bucket (not the generated bucket ID) within your Organization to write to.
Set this to allow the integration to retry if there was a network error when transmitting data.
Set this to specify the time precision sent to influxdb. Setting a coarser precision allows InfluxDb to compress your data better. If not set, defaults to ns.
State object attribute(s) to use as measurement name. Possible values: unit_of_measurement
, domain__device_class
or entity_id
.
Measurement name to use when the measurement_attr state attribute does not exist, e.g. when an entity doesn’t have a unit.
uses the entity id of the entity
Measurement name to use instead of measurement_attr or default measurement. This will store all data points in a single measurement.
Configure which integrations should be excluded from recording to InfluxDB. (Configure Filter)
Configure which integrations should be included in recordings to InfluxDB. If set, all other entities will not be recorded to InfluxDB. (Configure Filter)
The list of attribute names which should be reported as tags and not fields to InfluxDB. For example, if set to friendly_name
, it will be possible to group by entities’ friendly names as well, in addition to their ids.
The list of attribute names to ignore when reporting to InfluxDB. This can be used to filter out attributes that either don’t change or don’t matter to you in order to reduce the amount of data stored in InfluxDB. Please be aware of the underlying InfluxDB mechanism that converts non-string attributes to strings and adds a _str
suffix to the attribute name in this case. It means that when you want to ignore, for example, the icon_str
attribute that shows in your InfluxDB instance, you need to provide icon
to ignore_attributes
.
This attribute contains integration-specific override values. See Customizing devices and services for format.
Measurement name to use instead of a unit or default measurement. This will store all data points in a single measurement.
This attribute contains domain-specific integration override values. See Customizing devices and services for format.
Measurement name to use instead of a unit or default measurement. This will store all data points in a single measurement.
This attribute contains integration-specific override values. See Customizing devices and services for format.
Measurement name to use instead of unit or default measurement. This will store all data points in a single measurement.
Configure filter
By default, no entity will be excluded. To limit which entities are being exposed to InfluxDB
, you can use the include
and exclude
parameters.
# Example filter to include specified domains and exclude specified entities
influxdb:
include:
domains:
- alarm_control_panel
- light
entity_globs:
- binary_sensor.*_occupancy
exclude:
entities:
- light.kitchen_light
Filters are applied as follows:
- No filter
- All entities included
- Only includes
- Entity listed in entities include: include
- Otherwise, entity matches domain include: include
- Otherwise, entity matches glob include: include
- Otherwise: exclude
- Only excludes
- Entity listed in exclude: exclude
- Otherwise, entity matches domain exclude: exclude
- Otherwise, entity matches glob exclude: exclude
- Otherwise: include
- Domain and/or glob includes (may also have excludes)
- Entity listed in entities include: include
- Otherwise, entity listed in entities exclude: exclude
- Otherwise, entity matches glob include: include
- Otherwise, entity matches glob exclude: exclude
- Otherwise, entity matches domain include: include
- Otherwise: exclude
- Domain and/or glob excludes (no domain and/or glob includes)
- Entity listed in entities include: include
- Otherwise, entity listed in exclude: exclude
- Otherwise, entity matches glob exclude: exclude
- Otherwise, entity matches domain exclude: exclude
- Otherwise: include
- No Domain and/or glob includes or excludes
- Entity listed in entities include: include
- Otherwise: exclude
The following characters can be used in entity globs:
*
- The asterisk represents zero, one, or multiple characters
?
- The question mark represents zero or one character
Examples
Full configuration for 1.xx installations
influxdb:
host: 192.168.1.190
port: 20000
database: DB_TO_STORE_EVENTS
username: MY_USERNAME
password: MY_PASSWORD
ssl: true
verify_ssl: true
max_retries: 3
default_measurement: state
exclude:
entities:
- entity.id1
- entity.id2
domains:
- automation
include:
entities:
- entity.id3
- entity.id4
tags:
instance: prod
source: hass
Full configuration for 2.xx installations
influxdb:
api_version: 2
ssl: false
host: localhost
port: 9999
token: GENERATED_AUTH_TOKEN
organization: RANDOM_16_DIGIT_HEX_ID
bucket: BUCKET_NAME
tags:
source: HA
tags_attributes:
- friendly_name
default_measurement: units
exclude:
entities:
- zone.home
domains:
- persistent_notification
- person
include:
domains:
- sensor
- binary_sensor
- sun
entities:
- weather.home
Sensor
The influxdb
sensor allows you to use values from an InfluxDBinfluxdb
history integration. It can also be used with an external data source.
You must configure the influxdb
history integration in order to create influxdb
sensors. If you just want to create sensors for an external InfluxDB database and you don’t want Home Assistant to write any data to it you can exclude all entities like this:
influxdb:
exclude:
entity_globs: "*"
Configuration
To configure this sensor, you need to define the sensor connection variables and a list of queries to your configuration.yaml
The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file. A sensor will be created for each query:
# Example configuration.yaml entry
sensor:
- platform: influxdb
queries:
- name: mean value of foo
where: '"name" = ''foo'''
measurement: '"°C"'
Note that 2.xx installations of InfluxDB only support queries in their Flux language. While this language was available in 1.xx installations, it was not the default and not used in the API so you may not be aware of it. You can learn more about it from their documentation
You will need to construct your queries in this language in sensors for 2.xx installations, it looks like this:
# Example configuration.yaml entry
sensor:
- platform: influxdb
api_version: 2
organization: RANDOM_16_DIGIT_HEX_ID
token: GENERATED_AUTH_TOKEN
queries_flux:
- group_function: mean
imports:
- strings
name: "Mean humidity reported from past day"
query: >
filter(fn: (r) => r._field == "value" and r.domain == "sensor" and strings.containsStr(v: r.entity_id, substr: "humidity"))
|> keep(columns: ["_value"])
range_start: "-1d"
Configuration Variables
Use HTTPS instead of HTTP to connect. 2.xx - Defaults to true
for 2.xx, otherwise false
.
IP address or domain of your database host, e.g., 192.168.1.10. 2.xx - Defaults to ‘us-west-2-1.aws.cloud2.influxdata.com’ for 2.xx, not ‘localhost’.
Port to use. 2.xx - No default port for 2.xx, otherwise 8086.
1.xx only - The username of the database user. The user needs read/write privileges on the database.
1.xx only - The password for the database user account. Needed with username
configuration variable.
1.xx only - Name of the database to use. The database must already exist. Sets the default database for sensors, individual sensors can also read from a different database.
1.xx only - Verify SSL certificate for HTTPS request. For 2.xx SSL verification is required, library provides no way to disable it.
2.xx only - Auth token with READ access to your chosen Organization and Bucket. Needed with organization
configuration variable.
2.xx only - Organization ID to read from. To obtain this, open the UI of your 2.xx installation, the URL at the top will have it after /orgs
. For example, in InfluxDB Cloud it looks like this: https://us-west-2-1.aws.cloud2.influxdata.com/orgs/{OrganizationID}token
configuration variable.
2.xx only - Name of the bucket (not the generated bucket ID) within your Organization to read from. This sets the default bucket for sensors, individual sensors can also read from a different bucket.
1.xx only - List of sensors to expose in Home Assistant. Each sensor’s state is set by configuring an InfluxQL query.
The unique ID for this query. This allows changing the name, icon and entity_id from the web interface.
Defines the measurement name in InfluxDB (the FROM clause of the query).
Defines the data selection clause (the where clause of the query). This supports templates.
2.xx only - List of sensors to expose in Home Assistant. Each sensor’s state is set by configuring a Flux query.
The unique ID for this query. This allows changing the name, icon and entity_id from the web interface.
Duration or time value to start range from. All Flux queries require a range
filter, one is automatically added to the beginning of your Flux query in the form of range(start: {range_start}, stop: {range_stop})
.
Duration or time value to stop range at. See range_start
above for how this is used in query.
One or more flux filters used to get to the data you want. These should limit resultset to one table, or any beyond the first will be ignored. Your query should not begin or end with a pipe (|>
). This supports templates.
The group function to be used. If provided, this will add a filter to the end of your query like this {group_function}(column: "_value")
. Note that unlike the 1.xx queries, this does not default to mean. You can omit if you wish to use your own aggregator, which takes additional/different parameters or want to act on a different column. If omitted, then a filter of limit(n: 1)
will be added to the end instead to restrict to one result per table.
Defines a template to extract a value from the payload. Note that value
will be set to the value of the _value
field in your query output.
Name of the bucket within your Organization to read from.
Examples
Full configuration for 1.xx installations
The example configuration entry below create two request to your local InfluxDB instance, one to the database db1
, the other to db2
:
select last(value) as value from "°C" where "name" = "foo"
select min(tmp) as value from "%" where "entity_id" = ''salon'' and time > now() - 1h
sensor:
- platform: influxdb
host: localhost
username: home-assistant
password: password
queries:
- name: last value of foo
unit_of_measurement: °C
value_template: '{{ value | round(1) }}'
group_function: last
where: '"name" = ''foo'''
measurement: '"°C"'
field: value
database: db1
- name: Min for last hour
unit_of_measurement: "%"
value_template: '{{ value | round(1) }}'
group_function: min
where: '"entity_id" = ''salon'' and time > now() - 1h'
measurement: '"%"'
field: tmp
database: db2
Full configuration for 2.xx installations
sensor:
- platform: influxdb
api_version: 2
token: GENERATED_AUTH_TOKEN
organization: RANDOM_16_DIGIT_HEX_ID
bucket: BUCKET_NAME
queries_flux:
- range_start: "-1d"
name: "How long have I been here"
query: >
filter(fn: (r) => r._domain == "person" and r._entity_id == "me" and r._value != "{{ states('person.me') }}")
|> map(fn: (r) => ({ _value: r._time }))
value_template: "{{ relative_time(strptime(value, '%Y-%m-%d %H:%M:%S %Z')) }}"
- range_start: "-1d"
name: "Cost of my house today across all power sensor"
query: >
filter(fn: (r) => r.domain == "sensor" and r._field == "value" and regexp.matchRegexpString(r: /_power$/, v: r.entity_id))
|> keep(columns: ["_value", "_time"])
|> sort(columns: ["_time"], desc: false)
|> integral(unit: 5s, column: "_value")
imports: regexp
value_template: "{{ value|float / 24.0 / 1000.0 * states('sensor.current_cost_per_kwh')|float }}"
- range_start: "-1d"
bucket: Glances Bucket
name: "Average CPU temp today"
query: "filter(fn: (r) => r._field == \"value\" and r.entity_id == \"glances_cpu_temperature\")"
group_function: mean
Note that when working with Flux queries, the resultset is broken into tables, you can see how this works in the Data Explorer of the UI. If you are operating on data created by the InfluxDB history integration, this means by default, you will have a table for each entity and each attribute of each entity (other then unit_of_measurement
and any others you promoted to tags).
This is a lot more tables compared to 1.xx queries, where you essentially had one table per unit_of_measurement
across all entities. You can still create aggregate metrics across multiple sensors though. As you can see in the example above, a good way to do this is with the keep_value
into one.
Querying your data in Influx
Sensors
For sensors with a unit of measurement defined the unit of measurement is used as the measurement name and entries are tagged with the second part of the entity_id
. Therefore you need to add a WHERE clause to the query to filter out values.
For example a query on a %
battery for sensor.multi_sensor_battery_level
:
SELECT * FROM "%" WHERE time > now() - 12h AND "entity_id" = 'multi_sensor_battery_level';
Or for temperatures represented in °C
:
SELECT * FROM "°C" WHERE time > now() - 1h;
Everything else
Everything else can be queried using the entity_id
as its measurement name.
SELECT * FROM "binary_sensor.front_doorbell" WHERE time > now() - 24h;
SELECT "temperature" FROM "climate.kitchen" WHERE time > now() - 24h;