Timeseries database
The timeseries database connector is a specialized client for InfluxDB. It stores high-frequency data where the recording time is as important as the value itself, such as sensor readings, machine performance metrics, or energy consumption.
Intelligent downsampling and native multi-fields
The connector supports downsampling. It retains high-resolution raw data for recent events while automatically aggregating older data into lower-resolution buckets to optimize storage.
It also natively supports multi-field telemetry. When you log entire objects (such as { cycle_time: 4.2, yield: 150 }), the database automatically fans them out into individual queryable fields and reconstructs the object on the fly when you read it back.
Quick start: the internal instance
Heisenware provides a pre-initialized InfluxDB instance called internal-influx. It is globally available and ready for use. Pick functions from inside internal-influx to make use of it.
Direct data recording with the recorder
The recorder extension node provides the fastest way to log data. Click the + icon on any function output or modifier and select the recorder. By default, the node logs data directly into the internal-influx instance without extra function blocks in your flow.
Connecting an external database
To connect an external InfluxDB instance, use the create function:
Cloud or public database: Connect directly if your InfluxDB server is accessible via the internet.
Local database (via Agent): If your InfluxDB sits inside a private network, deploy an Agent in that network first and create the database instance within that Agent.
The functions for writing and querying data remain identical whether you use the managed internal-influx or a custom connection.
Downsampling pipeline
The downsampling pipeline stores data efficiently, letting you write high-frequency data (such as sensor readings every second) without running out of storage or slowing down queries over long time ranges.
Hot and cold data
The system categorizes data by age:
Hot data (recent): Requires high detail for real-time monitoring (such as detecting short temperature spikes).
Cold data (historical): Requires trend visibility rather than microsecond detail (such as analyzing average monthly temperatures).
The system automatically moves data through buckets as it ages, reducing resolution to optimize storage while maintaining statistical accuracy.
Pipeline structure
Data flows automatically through a series of stages. Write data only to the start of the pipeline.
You never see the + buckets in the software. They are the internal stages of this pipeline. What you select instead, for example as the recording type of a recorder, is either a fixed retention (H, D, W, M, or Y, keeping raw data for 1 hour up to 1 year, matching the letter) or DS (downsampled), which feeds this pipeline for long-term storage without a fixed retention.
H+
Raw (every point)
1 day
Real-time monitoring, debugging recent events
D+
5 minutes
1 week
Zooming into last week's performance
W+
1 hour
1 week
Weekly trends and patterns
M+
1 day
1 month
Monthly analysis and seasonal trends
Y+
1 week
1 year
Yearly trends and seasonal patterns
F+
1 month
Forever
Long-term historical archiving
How writing works
Write operations send data to the raw (H+) bucket automatically. Background tasks then process the data. For example, every 5 minutes a task extracts raw data from H+, calculates the mean, minimum, maximum, and count, and saves a summary point to the D+ bucket.
How reading works (smart stitching)
You do not need to specify a bucket when reading data. Provide a time range and readDownsampled routes the query:
It evaluates the requested
startandstoptimes.It selects the highest-resolution bucket available for that period.
It stitches the data together if the request spans retention boundaries.
For example, if you query the last 2 days, the function returns the last 24 hours from the raw (H+) bucket and the preceding 24 hours from the 5-minute (D+) bucket.
Configuration examples
Real-time debugging: Pulls from the raw (
H+) bucket to view the last 15 minutes.Monthly reporting: Pulls from the hourly (
W+) or daily (M+) buckets to visualize trends over the last 30 days.Stitched view: Returns the last 50 data points regardless of age, automatically querying older buckets if needed.
Aggregated fields
During downsampling, the pipeline preserves four key statistics for each window:
mean: The average value.max: The highest value.min: The lowest value.count: The total number of raw data points in the window.
Connection
create
Creates an InfluxDB client instance.
Skip this step for internal-influx. It is already instantiated for you.
Parameters
url
The URL of the InfluxDB instance (such as http://localhost:8086).
string
token
The authentication token with permissions for the target organization and buckets.
string
org
The name of the organization in InfluxDB.
string
options
flushInterval
The interval in milliseconds to flush buffered writes. Default 5000.
integer
batchSize
The number of points to buffer before writing. Default 1000.
integer
downsamplingPipeline
Overrides the default downsampling stages.
array
Right-click the token input and mark it as a secret to mask it.
Output
Returns the name of the created instance.
delete (instance)
Removes the timeseries database client instance and its connection configuration. Not to be confused with delete (data), which deletes measurement data.
Irreversible action
Deleting an instance removes its configuration. To communicate with the database again, you must create a new instance.
Parameters
None.
Output
Returns true upon removal.
Writing data
writePoint
Writes a single data point to a specific bucket and measurement.
When you pass an object as data, the engine fans it out into native InfluxDB fields, allowing fast analytics on individual properties later. If a measurement historically used stringified JSON, the database continues using it to preserve existing dashboards.
Parameters
bucket
The name of the bucket to write to.
string
measurement
The name of the measurement (such as temperature or production_line).
string
data
The value to record. Accepts a number, string, boolean, or object (such as { temp: 45, status: "ok" }).
any
tags
Optional key-value pairs to tag the data. To force the object storage behavior, add objectStorageType: 'fields' or objectStorageType: 'json'. The database strips this control flag before saving.
object
Example
Output
Returns true when the point is accepted for buffered writing, including when the data type is invalid (the connector then skips the write and logs a warning). Write failures surface in the logs, not as errors.
Internal bucket names
When using the internal database, bucket names indicate retention: F (forever), Y (year), M (month), W (week), D (day), H (hour).
writePoints
Writes multiple data points to a specific bucket and measurement. This is more efficient than calling writePoint in a loop.
Parameters
bucket
The name of the bucket.
string
measurement
The name of the measurement.
string
data
An array of values or objects to record.
array
tags
Optional tags. If specified as an array, the length must match the data array (one tag object per point). If specified as a single object, the tags apply to all points.
any
Example
Output
Returns true when the points are accepted for buffered writing. Throws an error if data is not an array or the length of a tags array does not match the data array. Write failures surface in the logs, not as errors.
writeDownsampled
Writes numeric data or multi-field objects to the high-frequency bucket (H+) for automatic downsampling.
When you pass an object containing both numbers and strings (such as { speed: 120, status: "running" }), the system retains the full object in the raw H+ bucket for debugging, but only aggregates numeric fields into long-term historical buckets. The pipeline drops non-numeric fields (such as strings and booleans) during downsampling and logs a warning.
Parameters
measurement
The name of the measurement.
string
data
The numeric value, object, or array to store.
any
tags
Optional tags to associate with the data.
object
Example
Output
Returns true when the data is accepted for buffered writing, including when no numeric fields remain after filtering (the connector then logs a warning).
Reading data
read
Reads timeseries data from a specific bucket and measurement, with options for filtering by time, isolating fields, limiting results, and aggregating data.
When you query a measurement containing multiple fields and do not specify a target field, the engine automatically pivots the data and reconstructs the original object.
Parameters
bucket
The name of the bucket to query.
string
measurement
The name of the measurement.
string
options
field
The specific field to isolate (such as cycle_time). If omitted, the function returns all fields as an object.
string
start
The earliest time to include (such as -12h, -7d, or 2025-01-01T00:00:00Z). Default -1y.
string
stop
The latest time to include. Default now().
string
limit
Limits the result to the first n data points.
integer
tail
Limits the result to the last n data points.
integer
every
The duration of time windows for aggregation (such as 15m).
string
func
The aggregation function applied per window (such as mean, sum, count, or last). Default mean.
string
tags
An object of tags to filter by.
object
difference
Calculates differences between readings when set to true. Set to nonNegative to ignore counter resets. Default false.
any
fillPrevious
Carries the last known value forward into empty time windows when set to true. Default false.
boolean
cumulativeSum
Keeps a running total across the selected time range when set to true. Default false.
boolean
derivativeUnit
Calculates the rate of change per given unit (such as 1m for per-minute rates).
string
Understanding aggregation
Timeseries databases often contain thousands of individual points. To visualize this data effectively, group the points into larger time windows and summarize them. Two parameters control this:
every: The size of the time window (such as1h,15m, or1d).func: The calculation applied to the points within each window.
Available functions
mean
Calculates the average value.
Smoothing noisy sensor data (such as average temperature per hour).
median
Finds the middle value.
Finding the typical value while ignoring extreme outliers.
min
Finds the lowest value.
Detecting the coldest temperature or lowest battery level.
max
Finds the highest value.
Detecting peak power usage or maximum pressure.
sum
Adds up all values.
Calculating total energy consumption or total volume flowed.
count
Counts the number of data points.
Counting machine cycles or error logs.
last
Takes the last value in the window.
The final state of a system at the end of each period.
first
Takes the first value in the window.
The starting state of a system at the beginning of each period.
Examples
Example 1: Smoothing noisy sensor data (averages)
An analog sensor sends data every second. Group the data into time windows and calculate the mean to smooth the trend over the last 12 hours:
Example 2: Peak detection and shift highs
Find the maximum value reached per reporting period over the last 30 days:
Example 3: Counting incidents or machine faults
Count how many faults or failed inspections occurred per time window for the current shift:
Example 4: The resetting machine counter (pieces produced)
A PLC part counter resets to 0 at shift end. Use difference: nonNegative to calculate pieces produced between readings while ignoring the negative drop at reset:
Example 5: Event-driven machine states (sparse data)
A machine only sends data on state changes, leaving gaps in the timeline. Use fillPrevious: true to carry the last known state forward into empty windows:
Example 6: Cumulative running totals (energy or water usage)
Show the running total of energy consumed in the last 12 hours:
Example 7: Rate of change (derivatives)
Calculate the minute-by-minute drain rate of a chemical tank:
Example 8: Isolating metrics from multi-field payloads
Show the maximum vibration recorded every 5 minutes from a multi-field payload:
Output
Returns an array of objects, each containing a date (ISO timestamp) and a value (a primitive value or a reconstructed object).
readDownsampled
Reads downsampled data by automatically stitching together details across downsampling buckets (raw H+ for recent data, aggregated D+/W+/M+/Y+ for older data).
Parameters
measurement
The name of the measurement.
string
options
field
The specific field to extract. Default value.
string
aggFunc
The statistic returned as the main value (such as mean or max). Default mean.
string
start
The earliest time to include. Default -1y.
string
stop
The latest time to include. Default now().
string
limit
Limits the result to the first n points.
integer
tail
Limits the result to the last n points.
integer
tags
Filters by tags.
object
Example
Output
Returns an array of objects containing statistics (mean, min, max, count) per time point. The requested aggFunc maps to the main value key.
query
Executes a raw Flux query string for complex database operations.
Parameters
flux
The raw Flux query string.
string
Example
Output
Returns the raw query result rows from InfluxDB.
Live data and caching
subscribeToChange
Registers a callback executed whenever new data is written to a measurement.
Parameters
measurement
The name of the measurement to watch.
string
handler
The callback evaluated on every write. Receives an object containing the measurement name, plus the written data and tags when includeData is enabled.
callback
options
samplingInterval
Guarantees the handler fires at most once every X milliseconds. Default 0.
integer
includeData
Includes the written data and tags in the payload when set to true. Default false.
boolean
Output
Returns a unique handler ID string. Use this ID with unsubscribeFromChange to remove the listener.
Example
unsubscribeFromChange
Unregisters change handlers. Call it without parameters to remove all handlers across all measurements.
Parameters
measurement
An optional measurement to unsubscribe from.
string
handlerId
An optional specific handler ID returned by subscribeToChange.
string
Output
Returns true if the listener is unsubscribed, or false if it is not found.
enableCaching
Enables time-based caching of read and readDownsampled results for a specific measurement. Repeated identical queries within the TTL return the cached result instead of querying the database. Concurrent identical queries share a single database request.
Parameters
measurement
The name of the measurement to cache.
string
ttlMs
The time-to-live of cached results in milliseconds. Default 30000.
integer
Output
Returns nothing.
Example
disableCaching
Disables caching for a specific measurement and purges all cached results.
Parameters
measurement
The name of the measurement.
string
Output
Returns nothing.
Database management
delete (data)
Deletes data from a measurement over a specified time range. Not to be confused with delete (instance), which removes the instance.
Parameters
bucket
The name of the bucket.
string
measurement
The name of the measurement to delete.
string
options
start
The start time. Default 1970-01-01.
string
stop
The end time. Default is the current time.
string
Example
Output
Returns true when the deletion succeeds.
flush
Manually forces buffered pending writes to send to the database immediately. Use this during testing or before shutting down a process to prevent data loss.
Parameters
None.
Output
Returns nothing. Throws an error if flushing fails.
reset
Deletes all data from all measurements in all buckets. The buckets remain intact but empty.
Irreversible action
This permanently deletes all data associated with the instance. You cannot undo this action.
Parameters
None.
Output
Returns true when the reset succeeds.
listBuckets
Retrieves all available buckets in the connected organization.
Parameters
None.
Output
Returns an array of bucket objects.
listMeasurements
Lists detailed information about all measurements across all buckets.
Parameters
options
includeStats
Calculates row count and cardinality when set to true. This operation can be slow. Default false.
boolean
statsRangeStart
The start of the time range for calculations. Default -1y.
string
Example
Output
Returns an array of objects containing measurement details.
getMeasurementDetails
Retrieves the schema fields and tags of a specific measurement in a bucket.
Parameters
bucket
The bucket name.
string
measurement
The measurement name.
string
Example
Output
Returns an object detailing fields and tags.
getMeasurementStats
Calculates row count and cardinality of a specific measurement over a given time range.
Parameters
bucket
The bucket name.
string
measurement
The measurement name.
string
options
start
The start time. Default -30d.
string
stop
The end time. Default now().
string
Example
Output
Returns an object detailing row count and cardinality.
Last updated
Was this helpful?