synthefy plugin

[ajanbekzat]

Synthefy Forecasting Plugin for InfluxDB 3

This PR adds a new HTTP trigger plugin that integrates Synthefy Forecasting API with InfluxDB 3 to enable on-demand time series forecasting.

Features

• On-demand forecasting via HTTP requests
• Multiple model support: Works with Synthefy models (sfm-tabular, Migas-latest, Chronos2, Moirai2, TimesFM, etc.)
• Multivariate forecasting: Supports metadata fields as covariates
• Tag filtering: Filter time series by tags (location, device, etc.)
• Automatic data writing: Forecasts written back to InfluxDB using Line Protocol

How It Works

1. Queries historical time series data from InfluxDB based on measurement, field, tags, and time range
2. Transforms data to Synthefy API v2 request format
3. Calls Synthefy Forecasting API to generate forecasts
4. Writes forecast results (with quantiles) back to InfluxDB

Requirements

• Python 3.7+
• pandas and httpx/requests packages
• Synthefy API key (create one here)

Usage Example

curl -X POST http://localhost:8181/api/v3/engine/forecast \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "measurement": "temperature",
    "field": "value",
    "tags": "location=NYC",
    "time_range": "30d",
    "forecast_horizon": "7d",
    "model": "sfm-tabular",
    "api_key": "your-api-key",
    "metadata_fields": "humidity,pressure"
  }'

[garylfowler]

Thank you for this submission; we will be reviewing soon.

[Aliaksei-Kharlap]

For new plugins, it is advisable to only pass sensitive data like api_key through request headers or environment variables

[Aliaksei-Kharlap]

For better understanding, it is worth specifying the supported units (d, h) in the documentation

[Aliaksei-Kharlap]

The documentation states that this parameter is also used to specify the database to read data from. However, the plugin's code doesn't support this logic, and triggers can only read data from the database in which they were created

[Aliaksei-Kharlap]

Currently, the processing engine for the influxdb3_local.write_to_db and influxdb3_local.write functions does not throw errors when writing during trigger execution. The current architecture works as follows: during trigger execution, all records are accumulated in a buffer, and the write itself occurs after the trigger completes. If there are write errors (different field types, etc.), errors are raised at the InfluxDB level. This means that the trigger is unaware of whether the write completed successfully and will never receive an error for the write operation. To address this issue, support for the influxdb3_local.write_sync and write_sync_to_db functions was added in InfluxDB 3.8.2. The write occurs immediately, which allows for error detection. You can see usage examples in other plugins (amqp_subscriber, kafka_subscriber, mqtt_subscriber)

[Aliaksei-Kharlap]

I think it's best to throw an error here and terminate the plugin. If there's an error in the request body, the plugin will continue executing implicitly with the settings in args, even though the user expects the behavior they specified in the request body

[Aliaksei-Kharlap]

When passing parameters via --trigger-arguments, avoid commas in the values ​​themselves, as parsing will fail. In the case of --trigger-arguments tags=room=Bedroom,room2=Bedroom,field=temp, parsing will return {"tags": "room=Bedroom", "room2": "Bedroom", "field": "temp"}, which is incorrect.
It is recommended to use a space (tags="room=Bedroom room2=Bedroom",field=temp)

[Aliaksei-Kharlap]

the same as for the tags field

[Aliaksei-Kharlap]

The httpx library always has a post method, the else branch is dead code

[Aliaksei-Kharlap]

The plugin code tries to import requests if httpx is missing, but the documentation doesn't mention installing requests

[Aliaksei-Kharlap]

When composing SQL, it is recommended to wrap field and table names in single quotes, which will allow their names to be parsed correctly