InfluxDB

Choose this action when you want to query device telemetry for operational trends or monitor time-series data in real time. You can use client-side or server-side batching to combine multiple points in one write request. AWS IoT Core converts each message to InfluxDB line protocol and writes it to the specified database and table. For more information about the format, see InfluxDB line protocol in the InfluxData documentation. For information about managed clusters, see Amazon Timestream for InfluxDB.

Prerequisites

This rule action has the following prerequisites:

InfluxDB action destination

Before you can use the InfluxDB rule action, you must create an InfluxDB action destination. The destination defines the connection parameters for your InfluxDB instance. AWS IoT Core then validates endpoint ownership.

Creating a destination

Use the CreateTopicRuleDestination API to create an InfluxDB destination:

{
  "destinationConfiguration": {
    "influxDBConfiguration": {
      "endpoint": "https://my-instance.timestream-influxdb.us-west-2.amazonaws.com:8086",
      "influxDBVersion": "V2",
      "secretId": "arn:aws:secretsmanager:us-west-2:111122223333:secret:my-influxdb-credentials-AbCdEf"
    }
  }
}

Destination parameters

Endpoint ownership validation

When you create an InfluxDB action destination, AWS IoT Core validates endpoint ownership by authenticating against the InfluxDB API using the credentials you provided:

A successful response (2xx) sets the destination status to ENABLED. On failure, AWS IoT Core sets the status to ERROR. To retry validation, call UpdateTopicRuleDestination with the status set to IN_PROGRESS.

InfluxDB terminology mapping

The following terms differ between InfluxDB V2 and V3.

Parameters

When you create an AWS IoT rule with the InfluxDB action, you must specify the following information:

Batching

The InfluxDB action supports two batching modes.

Client-side batching

Your IoT device batches time-series data as a JSON array and publishes it as a single MQTT message. With client-side batching, each array element becomes one line-protocol point in a single write request. You do not need additional configuration.

Server-side batching

Use server-side batching to group individual messages before writing them to InfluxDB. Configure server-side batching using the batchConfig parameter. The batch is flushed when any configured limit (maxBatchSize, maxBatchOpenMs, or maxBatchSizeBytes) is reached first.

The InfluxDB action is metered based on the outbound payload size in 5 KiB increments. Line-protocol conversion failures are also metered.

Per-element templates for array payloads

When your IoT devices send batched time-series data as a JSON array, you can use the “per-element substitution templates” to resolve values from each individual array element. This routes each data point to a different table or applies element-specific tags. For more information, see Per-element templates.

Syntax of two substitution templates

Use @{...} in tableName and tag values to resolve the expression against each array element individually.

Example

Given the following device payload (JSON array):

[
  {"measurement_type": "temperature", "room": "kitchen", "timestamp": 1700000000000, "value": 23.5},
  {"measurement_type": "humidity", "room": "bedroom", "timestamp": 1700000001000, "value": 60.1}
]

And the following action configuration:

{
  "influxDB": {
    "destinationArn": "arn:aws:iot:us-west-2:111122223333:ruledestination/influxdb/abc123",
    "roleArn": "arn:aws:iam::111122223333:role/iot-influxdb-role",
    "databaseName": "sensor_data",
    "tableName": "@{measurement_type}",
    "tags": {
      "room": "@{room}"
    },
    "timestampUnit": "ms"
  }
}

The resulting line-protocol output contains two points:

temperature,room=kitchen value=23.5 1700000000000
humidity,room=bedroom value=60.1 1700000001000

Restrictions

InfluxDB record content

For each record in the post-SQL query result, the resulting InfluxDB line-protocol point contains these components:

Data type conversion

AWS IoT Core converts JSON values to InfluxDB line protocol types as follows:

Naming restrictions

Reserved keys

The following payload keys are stripped from the field set during line-protocol conversion:

Error actions

If the InfluxDB action fails, the configured error action is triggered.

Using InfluxDB as an error action

You can configure the InfluxDB action as an error action for any rule. The entire payload is written to a single tableName as one record. Message-scope substitution templates (${...}) are supported in the error action's tableName and tags.

Error action output

When the error action is triggered, the output payload contains: ruleName, topic, cloudwatchTraceId, clientId, sourceIp, base64OriginalPayload (Base64-encoded original message), and a failures array where each entry has failedAction, failedResource, and errorMessage.

With server-side batching, the payload uses payloadsWithMetadata, with one entry for each distinct inbound MQTT message. Each failure's affectedIds values refer to the id values of those message entries; they are not point indices. A client-side JSON array is one inbound message even though it produces multiple InfluxDB points. For the complete payload format, see Error Actions for Batching.

Retryable errors (503) are retried with exponential backoff. For an HTTP 401 response, AWS IoT Core reloads the token from AWS Secrets Manager and retries the request once. Non-retryable errors (404, 422) trigger the error action immediately. For retry limits, see AWS IoT Core service quotas.

Examples

InfluxDB rule action

{
  "topicRulePayload": {
    "sql": "SELECT * FROM 'devices/+/telemetry'",
    "ruleDisabled": false,
    "awsIotSqlVersion": "2016-03-23",
    "actions": [
      {
        "influxDB": {
          "destinationArn": "arn:aws:iot:us-west-2:111122223333:ruledestination/influxdb/a1b2c3d4",
          "roleArn": "arn:aws:iam::111122223333:role/iot-influxdb-role",
          "organization": "my-org",
          "databaseName": "sensor_data",
          "tableName": "device_metrics",
          "tags": {
            "device_id": "${clientid()}",
            "location": "building-a"
          },
          "timestampUnit": "ms"
        }
      }
    ]
  }
}

Sample payload:

{
  "timestamp": 1700000000000,
  "temperature": 23.5,
  "humidity": 60.1,
  "pressure": 1013.25,
  "battery_level": 87
}

Resulting line protocol:

device_metrics,device_id=myDevice123,location=building-a temperature=23.5,humidity=60.1,pressure=1013.25,battery_level=87i 1700000000000

Field order in the output may vary — fields are not sorted alphabetically.

Client-batched array payload with per-element templates

{
  "influxDB": {
    "destinationArn": "arn:aws:iot:us-west-2:111122223333:ruledestination/influxdb/a1b2c3d4",
    "roleArn": "arn:aws:iam::111122223333:role/iot-influxdb-role",
    "organization": "my-org",
    "databaseName": "sensor_data",
    "tableName": "@{measurement_type}",
    "tags": {
      "sensor_id": "@{sensor_id}",
      "location": "${topic(2)}"
    },
    "timestampUnit": "ns"
  }
}

Sample payload (published to devices/floor3/telemetry):

[
  {"measurement_type": "temperature", "sensor_id": "sensor-42", "timestamp": 1700000000000000000, "value": 23.5},
  {"measurement_type": "humidity", "sensor_id": "sensor-42", "timestamp": 1700000001000000000, "value": 60.1},
  {"measurement_type": "pressure", "sensor_id": "sensor-43", "timestamp": 1700000002000000000, "value": 1013.25}
]

Resulting line protocol:

temperature,location=floor3,sensor_id=sensor-42 value=23.5 1700000000000000000
humidity,location=floor3,sensor_id=sensor-42 value=60.1 1700000001000000000
pressure,location=floor3,sensor_id=sensor-43 value=1013.25 1700000002000000000

Server-side batching with InfluxDB

To add server-side batching to any InfluxDB action, include batchConfig in the action configuration:

"batchConfig": {
  "maxBatchSize": 50,
  "maxBatchOpenMs": 1000,
  "maxBatchSizeBytes": 65536,
  "batchAcrossTopics": false
}

IAM policy for the rule action role

Trust policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {"Service": "iot.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }
  ]
}

Permission policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:us-west-2:111122223333:secret:my-influxdb-secret-a1b2c3"
    }
  ]
}

Combined client-side and server-side batching (point reordering)

When you enable both client-side batching (JSON array payloads) and server-side batching (batchConfig), be aware that the server-side batch may reorder points from a client-side batched payload. The Rules Engine accumulates points from multiple incoming messages into a single server-side batch. Because messages arrive asynchronously from different devices or topics, points that were ordered within the original client payload may be interleaved with points from other messages in the final write.

Action configuration:

{
  "influxDB": {
    "destinationArn": "arn:aws:iot:us-west-2:111122223333:ruledestination/influxdb/abc123",
    "roleArn": "arn:aws:iam::111122223333:role/iot-influxdb-role",
    "databaseName": "sensor_data",
    "tableName": "@{measurement_type}",
    "tags": {
      "device_id": "${topic(2)}",
      "floor": "@{floor}"
    },
    "timestampUnit": "ms",
    "batchConfig": {
      "maxBatchSize": 100,
      "maxBatchOpenMs": 500,
      "maxBatchSizeBytes": 65536,
      "batchAcrossTopics": true
    }
  }
}

Device A publishes to devices/deviceA/telemetry at time T:

[
  {"measurement_type": "temperature", "floor": "1", "timestamp": 1700000000000, "value": 22.1},
  {"measurement_type": "temperature", "floor": "2", "timestamp": 1700000000100, "value": 23.4},
  {"measurement_type": "humidity", "floor": "1", "timestamp": 1700000000200, "value": 55.0}
]

Device B publishes to devices/deviceB/telemetry at time T+10ms:

[
  {"measurement_type": "temperature", "floor": "3", "timestamp": 1700000000050, "value": 21.8},
  {"measurement_type": "humidity", "floor": "3", "timestamp": 1700000000150, "value": 62.3}
]

Both messages arrive within the 500ms batch window (maxBatchOpenMs), so the Rules Engine combines all five points into a single server-side batch.

Resulting line protocol (server-side batch write):

temperature,device_id=deviceB,floor=3 value=21.8 1700000000050
temperature,device_id=deviceA,floor=1 value=22.1 1700000000000
temperature,device_id=deviceA,floor=2 value=23.4 1700000000100
humidity,device_id=deviceB,floor=3 value=62.3 1700000000150
humidity,device_id=deviceA,floor=1 value=55.0 1700000000200

Notice that the points are no longer in the order they appeared within each client payload. The three points from Device A (timestamps 1700000000000, 1700000000100, 1700000000200) are interleaved with the two points from Device B (timestamps 1700000000050, 1700000000150). The server-side batch does not guarantee the original ordering within each message. InfluxDB uses the timestamp field to place each point on the timeline, so reordering does not affect query correctness. However, if your application relies on write-order semantics (for example, handling field type conflicts or last-write-wins deduplication within the same millisecond), be aware that the effective write order may differ from the publish order.