Documentation

Prophet forecasting plugin

The Prophet Forecasting Plugin enables time series forecasting for data in InfluxDB 3 using Facebook’s Prophet library. Generate predictions for future data points based on historical patterns, including seasonality, trends, and custom events. Supports both scheduled batch forecasting and on-demand HTTP-triggered forecasts with model persistence and validation capabilities.

Configuration

Scheduled trigger parameters

ParameterTypeDefaultDescription
measurementstringrequiredSource measurement containing historical data
fieldstringrequiredField name to forecast
windowstringrequiredHistorical data window. Format: <number><unit> (for example, "30d")
forecast_horizontstringrequiredForecast duration. Format: <number><unit> (for example, "2d")
tag_valuesstringrequiredDot-separated tag filters (for example, "region:us-west.device:sensor1")
target_measurementstringrequiredDestination measurement for forecast results
model_modestringrequiredOperation mode: “train” or “predict”
unique_suffixstringrequiredUnique model identifier for versioning

HTTP trigger parameters

ParameterTypeDefaultDescription
measurementstringrequiredSource measurement containing historical data
fieldstringrequiredField name to forecast
forecast_horizontstringrequiredForecast duration. Format: <number><unit> (for example, "7d")
tag_valuesobjectrequiredTag filters as JSON object (for example, {“region”:“us-west”})
target_measurementstringrequiredDestination measurement for forecast results
unique_suffixstringrequiredUnique model identifier for versioning
start_timestringrequiredHistorical window start (ISO 8601 format)
end_timestringrequiredHistorical window end (ISO 8601 format)

Advanced parameters

ParameterTypeDefaultDescription
seasonality_modestring“additive”Prophet seasonality mode: “additive” or “multiplicative”
changepoint_prior_scalenumber0.05Flexibility of trend changepoints
changepointsstring/arraynoneChangepoint dates (ISO format)
holiday_date_liststring/arraynoneCustom holiday dates (ISO format)
holiday_namesstring/arraynoneHoliday names corresponding to dates
holiday_country_namesstring/arraynoneCountry codes for built-in holidays
inferred_freqstringautoManual frequency specification (for example, "1D", "1H")
validation_windowstring“0s”Validation period duration
msre_thresholdnumberinfinityMaximum acceptable Mean Squared Relative Error
target_databasestringcurrentDatabase for forecast storage
save_modestring“false”Whether to save/load models (HTTP only)

Notification parameters

ParameterTypeDefaultDescription
is_sending_alertstring“false”Enable alerts on validation failure
notification_textstringtemplateCustom alert message template
sendersstringnoneDot-separated notification channels
notification_pathstring“notify”Notification endpoint path
influxdb3_auth_tokenstringenv varAuthentication token

TOML configuration

ParameterTypeDefaultDescription
config_file_pathstringnoneTOML config file path relative to PLUGIN_DIR (required for TOML configuration)

To use a TOML configuration file, set the PLUGIN_DIR environment variable and specify the config_file_path in the trigger arguments. This is in addition to the --plugin-dir flag when starting InfluxDB 3.

Example TOML configuration

prophet_forecasting_scheduler.toml

For more information on using TOML configuration files, see the Using TOML Configuration Files section in the influxdb3_plugins /README.md.

Installation

  1. Start InfluxDB 3 Enterprise with the Processing Engine enabled (--plugin-dir /path/to/plugins)

  2. Install required Python packages:

    influxdb3 install package pandas
    influxdb3 install package numpy
    influxdb3 install package requests
    influxdb3 install package prophet

Create scheduled trigger

Create a trigger for periodic forecasting:

influxdb3 create trigger \
  --database mydb \
  --plugin-filename prophet_forecasting.py \
  --trigger-spec "every:1d" \
  --trigger-arguments "measurement=temperature,field=value,window=30d,forecast_horizont=2d,tag_values=region:us-west.device:sensor1,target_measurement=temperature_forecast,model_mode=train,unique_suffix=20250619_v1" \
  prophet_forecast_trigger

Create HTTP trigger

Create a trigger for on-demand forecasting:

influxdb3 create trigger \
  --database mydb \
  --plugin-filename prophet_forecasting.py \
  --trigger-spec "request:forecast" \
  prophet_forecast_http_trigger

Enable triggers

influxdb3 enable trigger --database mydb prophet_forecast_trigger
influxdb3 enable trigger --database mydb prophet_forecast_http_trigger

Examples

Scheduled forecasting

Example HTTP request for on-demand forecasting:

curl -X POST http://localhost:8181/api/v3/engine/forecast \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "measurement": "temperature",
    "field": "value",
    "forecast_horizont": "7d",
    "tag_values": {"region":"us-west","device":"sensor1"},
    "target_measurement": "temperature_forecast",
    "unique_suffix": "model_v1_20250722",
    "start_time": "2025-05-20T00:00:00Z",
    "end_time": "2025-06-19T00:00:00Z",
    "seasonality_mode": "additive",
    "changepoint_prior_scale": 0.05,
    "validation_window": "3d",
    "msre_threshold": 0.05
  }'

Advanced forecasting with holidays

curl -X POST http://localhost:8181/api/v3/engine/forecast \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "measurement": "sales",
    "field": "revenue",
    "forecast_horizont": "30d",
    "tag_values": {"store":"main_branch"},
    "target_measurement": "revenue_forecast",
    "unique_suffix": "retail_model_v2",
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2025-06-01T00:00:00Z",
    "holiday_country_names": ["US"],
    "holiday_date_list": ["2025-07-04"],
    "holiday_names": ["Independence Day"],
    "changepoints": ["2025-01-01", "2025-03-01"],
    "inferred_freq": "1D"
  }'

Features

  • Dual trigger modes: Support for both scheduled batch forecasting and on-demand HTTP requests
  • Model persistence: Save and reuse trained models for consistent predictions
  • Forecast validation: Built-in accuracy assessment using Mean Squared Relative Error (MSRE)
  • Holiday support: Built-in holiday calendars and custom holiday configuration
  • Advanced seasonality: Configurable seasonality modes and changepoint detection
  • Notification integration: Alert delivery for validation failures via multiple channels
  • Flexible time intervals: Support for seconds, minutes, hours, days, weeks, months, quarters, and years

Output data structure

Forecast results are written to the target measurement with the following structure:

Tags

  • model_version: Model identifier from unique_suffix parameter
  • Additional tags from original measurement query filters

Fields

  • forecast: Predicted value (yhat from Prophet model)
  • yhat_lower: Lower bound of confidence interval
  • yhat_upper: Upper bound of confidence interval
  • run_time: Forecast execution timestamp (ISO 8601 format)

Timestamp

  • time: Forecast timestamp in nanoseconds

Troubleshooting

Common issues

Model training failures

  • Ensure sufficient historical data points for the specified window
  • Verify data contains required time column and forecast field
  • Check for data gaps that might affect frequency inference
  • Set inferred_freq manually if automatic detection fails

Validation failures

  • Review MSRE threshold settings - values too low may cause frequent failures
  • Ensure validation window provides sufficient data for comparison
  • Check that validation data aligns temporally with forecast period

HTTP trigger issues

  • Verify JSON request body format matches expected schema
  • Check authentication tokens and database permissions
  • Ensure start_time and end_time are in valid ISO 8601 format with timezone

Model persistence problems

  • Verify plugin directory permissions for model storage
  • Check disk space availability in plugin directory
  • Ensure unique_suffix values don’t conflict between different model versions

Model storage

  • Location: Models stored in prophet_models/ directory within plugin directory
  • Naming: Files named prophet_model_{unique_suffix}.json
  • Versioning: Use descriptive unique_suffix values for model management

Time format support

Supported time units for window, forecast_horizont, and validation_window:

  • s (seconds), min (minutes), h (hours)
  • d (days), w (weeks)
  • m (months ≈30.42 days), q (quarters ≈91.25 days), y (years = 365 days)

Validation process

When validation_window is set:

  1. Training data: current_time - window to current_time - validation_window
  2. Validation data: current_time - validation_window to current_time
  3. MSRE calculation: mean((actual - predicted)² / actual²)
  4. Threshold comparison and optional alert dispatch

Report an issue

For plugin issues, see the Plugins repository issues page.

Find support for InfluxDB 3 Enterprise

The InfluxDB Discord server is the best place to find support for InfluxDB 3 Enterprise. For other InfluxDB versions, see the Support and feedback options.


Was this page helpful?

Thank you for your feedback!


The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Read more

New in InfluxDB 3.4

Key enhancements in InfluxDB 3.4 and the InfluxDB 3 Explorer 1.2.

See the Blog Post

InfluxDB 3.4 is now available for both Core and Enterprise, which introduces offline token generation for use in automated deployments and configurable license type selection that lets you bypass the interactive license prompt. InfluxDB 3 Explorer 1.2 is also available, which includes InfluxDB cache management and other new features.

For more information, check out: