InfluxDB

The InfluxDB integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] lets you transfer all state changes to an external InfluxDB database. This integration supports:

• InfluxDB 3 Core and InfluxDB 3 Enterprise – The latest InfluxDB with v1 and v2 write API compatibility. Sensors query using InfluxQL. Use external tools for SQL.
• InfluxDB 2.x – Including InfluxDB Cloud. Sensors query using Flux.
• InfluxDB 1.x – Sensors query using InfluxQL.

The configuration differs between versions. The documentation below notes when fields apply to specific versions.

InfluxDB 3 (Core and Enterprise)

See how to get started using InfluxDB 3:

• InfluxDB 3 Core: Free, open-source, optimized for recent data queries.
• InfluxDB 3 Enterprise: Adds compaction for historical queries. Includes a free At-Home license for non-commercial use.

Write API compatibility

InfluxDB 3 Core and Enterprise provide InfluxDB v1 and v2 write API compatibility, allowing you to write data using api_version: 2.

Query API compatibility

InfluxDB 3 supports the v1 query API (InfluxQL) and v3 query API (SQL and InfluxQL). The v2 query API (Flux) is not supported.

Example configuration for InfluxDB 3

influxdb:
  api_version: 2
  ssl: false
  host: 192.168.6.193
  # InfluxDB 3 default (v1/v2 use 8086)
  port: 8181
  token: apiv3_YOUR_DATABASE_TOKEN
  # Required, but not validated
  organization: d1c92e4eef98a5b6
  # Maps to InfluxDB 3 database name
  bucket: gf_ha
  measurement_attr: entity_id

Generate tokens using the influxdb3 CLI or InfluxDB 3 Explorer.

There is currently support for the following device types within Home Assistant:

• Sensor

Configuration

Authentication requirements vary by version:

• InfluxDB 3: Authentication optional (enabled by default). Use api_version: 2 with a token. See example above.
• InfluxDB 2.x: Requires authentication. Use api_version: 2 with a token and organization.
• InfluxDB 1.x: Authentication optional (disabled by default). If running on the same host with default settings, no configuration is needed.

After changing the configuration.yamlThe 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.

# Minimal configuration for InfluxDB 1.x with authentication disabled
influxdb:

For InfluxDB 1.x, you must first create a database named home_assistant. InfluxDB 2.x and 3.x create buckets/databases automatically.

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:

1. No filter
   • All entities included
2. Only includes
   • Entity listed in entities include: include
   • Otherwise, entity matches domain include: include
   • Otherwise, entity matches glob include: include
   • Otherwise: exclude
3. Only excludes
   • Entity listed in exclude: exclude
   • Otherwise, entity matches domain exclude: exclude
   • Otherwise, entity matches glob exclude: exclude
   • Otherwise: include
4. 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
5. 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
6. 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 InfluxDB 1.x

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 InfluxDB 2.x

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 lets you query values from an InfluxDB database to populate a sensor state. Use this to present statistics as Home Assistant sensors from the influxdb history integration or an external data source.

influxdb:
  exclude:
    entity_globs: "*"

Sensor configuration

Define the sensor connection variables and queries in your configuration.yamlThe 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 is created for each query.

InfluxDB 1.x sensors (InfluxQL)

sensor:
  - platform: influxdb
    queries:
      - name: mean value of foo
        where: '"name" = ''foo'''
        measurement: '"°C"'

InfluxDB 2.x sensors (Flux)

InfluxDB 2.x requires queries in Flux. Use the query builder in the InfluxDB UI to construct queries:

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"

Sensor configuration variables

Examples

Full configuration for InfluxDB 1.x

The example configuration entry below creates two requests 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 InfluxDB 2.x

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 than unit_of_measurement and any others you promoted to tags).

This is more tables compared to 1.x queries, where you have one table per unit_of_measurement across all entities. You can still create aggregate metrics across multiple sensors. As shown above, use the keep or drop filters. When you remove key columns, InfluxDB merges tables that share a schema for _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;