InfluxDB

Connect to and query InfluxDB time-series databases with OIBus. All three major InfluxDB API versions are supported: InfluxDB v1 (InfluxQL), InfluxDB v2 (Flux), and InfluxDB v3 (SQL / Flight SQL).

Technology Overview

• Purpose-built time-series database by InfluxData
• History-only connector: queries a time range on each scan cycle
• Three distinct API versions, each with a different query language and authentication scheme

API Versions

InfluxDB has gone through three major API revisions that are not backwards-compatible. Select the version that matches your server before configuring the other settings.

Version	Query language	Authentication	Typical deployment
v1	InfluxQL (SQL-like)	Username / Password	Self-hosted InfluxDB 1.x
v2	Flux (functional pipeline)	API Token + Organisation + Bucket	InfluxDB 2.x, InfluxDB Cloud (TSM)
v3	SQL (Apache Arrow Flight SQL)	API Token	InfluxDB 3.x, InfluxDB Cloud Serverless

Specific Settings

Common

Setting	Description
Version	InfluxDB API version to use: 1, 2, 3.

InfluxDB v1

Setting	Description	Example Value
Host	Hostname or IP address of the InfluxDB server.	localhost
Port	Server port. Default: 8086.	8086
Protocol	Transport protocol: http or https.	http
Database	Name of the InfluxDB database to query.	telegraf
Username	Optional. Username for authentication.	reader
Password	Optional. Password for authentication.	••••••••

InfluxDB v2

Setting	Description	Example Value
URL	Full URL of the InfluxDB v2 instance.	http://localhost:8086
Token	API token with read access to the target bucket.	••••••••
Organisation	Name of the InfluxDB organisation that owns the bucket.	my-org
Bucket	Name of the bucket to query.	sensors

InfluxDB v3

Setting	Description	Example Value
URL	Full URL of the InfluxDB v3 / Cloud Serverless endpoint.	https://us-east-1-1.aws.cloud2.influxdata.com
Token	API token with read access to the target database.	••••••••
Database	Name of the database (equivalent to a v1 database or v2 bucket).	sensors

Use a read-only token

Create a dedicated read-only token or user for OIBus. On InfluxDB v1, grant only READ privilege on the target database; on v2/v3, scope the token to the specific bucket or database.

Item Settings

Each item represents one query executed against the InfluxDB server on each scan cycle. Items have their own scan mode and throttling settings (there are no groups in the InfluxDB connector).

Setting	Description	Example Value
Scan mode	Schedule used to trigger the query.	Every 1 min

Throttling Settings

Throttling controls how OIBus paces historical data requests. These settings appear on each group (for connectors that support groups) or on each item (for single-item connectors). Items in a group can override the group defaults by disabling the Sync with group toggle.

Setting	Description	Example Value
Max read interval	Maximum duration of each sub-query in seconds. Larger time ranges are automatically split into chunks not exceeding this value.	3600
Read delay	Pause in milliseconds between consecutive sub-queries. Helps prevent server overload and manages rate limits.	1000
Start time offset	Milliseconds added to the start of the query window (@StartTime). A negative value moves the start earlier, to capture late-arriving data from the previous interval — this is the old "Overlap" behavior. A positive value moves the start later instead, skipping that much of the window.	-60000
End time offset	Milliseconds added to the end of the query window (@EndTime). A negative value pulls the end in earlier — useful for eventually-consistent sources where the very latest rows aren't reliable yet. A positive value extends the window later. If the resulting end is not after the effective start, the query is skipped for this run.	0
Recovery strategy	Order in which OIBus catches up on a backlog of unqueried sub-intervals — e.g. after being stopped for a while, or on first run against a wide time range. From oldest to newest (default) processes the backlog chronologically. From newest to oldest queries the most recent sub-interval first, so up-to-date values become available immediately while older gaps are backfilled afterward.	From oldest to newest

How Throttling Works

1. Interval splitting — A 24-hour range with Max read interval = 3600 (1 hour) is split into 24 separate 1-hour sub-queries.
2. Read delay — A pause is inserted between sub-queries to manage server load.
3. Start/End time offset — With Start time offset = -60000 (-1 minute), a query for [10:00–11:00] actually requests [9:59–11:00], ensuring no late-arriving data is missed. End time offset shifts the other boundary the same way.
4. Recovery strategy — Only matters when there's more than one sub-interval to catch up on. With From newest to oldest, the tracked instant only advances once every sub-interval in the backlog has been queried — this avoids skipping over not-yet-queried older intervals if OIBus restarts mid-catch-up.

Offsets apply to the full query range

Start/End time offset are applied once, to the start and end of the overall query window — not to the start of each individual sub-interval when a large range is split into chunks by Max read interval.

Recommended Configurations

Scenario	Max read interval	Read delay	Start time offset
Stable network, small datasets	3600 (1 hour)	500	0 (none)
Unstable network	1800 (30 min)	2000	0 (none)
Large historical retrievals	7200 (2 hours)	1000	0 (none)
Real-time with occasional gaps	900 (15 min)	200	-15000 (-15 sec)

Going deeper

For the reasoning behind these numbers — sizing Max read interval against real data volumes, the Read delay / Max read interval trade-off on a large backlog, and worked examples of Start vs. End time offset (including the batched multi-item case where items don't all flush at once) — see Tuning South History Call Settings.

Query

Setting	Description	Example Value
Query	The query to run. Supports @StartTime and @EndTime placeholders.	See below
Request timeout	Maximum execution time in milliseconds before the query is aborted. (v1 only)	15000

Query examples by version

v1 — InfluxQL

SELECT mean("temperature"), mean("pressure")
FROM "sensors"
WHERE time > '@StartTime' AND time <= '@EndTime'
GROUP BY time(1m), "device_id"

v2 — Flux

from(bucket: "sensors")
  |> range(start: @StartTime, stop: @EndTime)
  |> filter(fn: (r) => r["_measurement"] == "temperature")
  |> aggregateWindow(every: 1m, fn: mean, createEmpty: false)

Excluding the start of the range

Flux's range() is inclusive of start and exclusive of stop (start <= _time < stop). Since timestamp tracking sets the next scan's @StartTime to the maximum _time returned by the previous one, a point landing exactly on that boundary would otherwise be returned twice. Add an explicit filter on _time to make the start exclusive too:

from(bucket: "sensors")
  |> range(start: @StartTime, stop: @EndTime)
  |> filter(fn: (r) => r._time > @StartTime)
  |> filter(fn: (r) => r["_measurement"] == "temperature")

The InfluxQL (v1) and SQL (v3) examples above don't need this — they already use a strict time > '@StartTime' comparison.

v3 — SQL

SELECT time, device_id, temperature, pressure
FROM sensors
WHERE time > '@StartTime' AND time <= '@EndTime'
ORDER BY time

Time Variables

The following placeholders can be used anywhere in the query string and are replaced by OIBus before sending the request to the server:

Variable	Value injected	Example
@StartTime	Start of the current query interval. Initialised to the first scan time, then advanced by the tracking mechanism.	2024-01-15T10:00:00.000Z
@EndTime	End of the current query interval, capped to the current time or the sub-interval end.	2024-01-15T11:00:00.000Z

The substitution is a plain text replacement — wrap the placeholders in quotes if the query language requires string literals (InfluxQL, SQL). In Flux, range(start:, stop:) accepts RFC 3339 strings directly without surrounding quotes.

Query splitting

When a large time range is requested, OIBus splits it into smaller sub-intervals based on the Max read interval throttling setting. Each sub-interval gets its own @StartTime / @EndTime pair.

Timestamp Tracking

After each successful query, OIBus takes the timestamp of the last row of the result set and uses it as @StartTime of the next scan cycle. No configuration is required.

Query results must be in ascending time order

OIBus does not scan the whole result set for the true maximum — it assumes InfluxDB returns rows in ascending time order (its default) and simply reads the last row. Queries that don't guarantee that order — for example a multi-series GROUP BY query without an explicit ORDER BY time — can return a last row that isn't actually the latest timestamp, which may cause skipped or re-fetched data. Add an explicit ORDER BY time (or equivalent) to your query if it groups or reorders results.

The timestamp column name is determined by the API version:

Version	Timestamp column	Format
v1	time	ISO 8601 string — OIBus normalizes the raw INanoDate returned by the client
v2	_time	RFC 3339 string returned directly by the Flux query API
v3	time	ISO 8601 string returned by the Arrow Flight client

If no results are returned, @StartTime is not advanced and the next scan retries the same interval.

Data Flow

1. OIBus substitutes @StartTime and @EndTime into the query string.
2. The query is sent to the InfluxDB server via the appropriate client library for the configured version.
3. Results are collected as a JSON array of row objects.
4. OIBus extracts the maximum value of the timestamp column (time for v1/v3, _time for v2) and stores it as the @StartTime for the next scan cycle.
5. The JSON array is written to a file and forwarded to configured North connectors as a raw JSON payload.

Output format

Unlike SQL connectors (which produce CSV files), the InfluxDB connector always outputs a JSON file. Use a North connector that accepts raw file payloads — OIAnalytics, Azure Blob, S3, File Writer — or add a JSON-to-CSV transformer if your downstream system requires CSV.