This topic describes the syntax and parameters of predictor functions. It also provides multiple examples.
HOLT_WINTERS()
Returns N predicted field values by using the Holt-Winters seasonal method.
You can use the HOLT_WINTERS()
function to perform the following operations:
Predict when a specified threshold will be exceeded.
Compare predicted values with actual values to identify data anomalies.
Syntax
SELECT HOLT_WINTERS[_WITH-FIT](<function>(<field_key>),<N>,<S>)[INTO_clause] FROM_clause [WHERE_clause] GROUP_BY_clause [ORDER_BY_clause][LIMIT_clause][OFFSET_clause][SLIMIT_clause][SOFFSET_clause]
Description
The HOLT_WINTERS(function(field_key),N,S)
function returns N
predicted field values of the specified field key. The predicted field values are seasonally adjusted.
The N
predicted values occur at the same time interval as that specified by the GROUP BY time() clause. If you set the time interval to 6m
in the GROUP BY time()
clause and set N
to 3
, the query returns 3 predicted values based on a 6-minute interval.
The S
parameter specifies the seasonal pattern setting. You can use this parameter to specify the length of a seasonal pattern based on the time interval that is specified by the GROUP BY time()
clause. If you set the time interval to 2m
in the GROUP BY time()
clause and set S
to 3
, the seasonal pattern occurs every 6 minutes. This indicates that the seasonal pattern occurs every 3 points. If you do not want to seasonally adjust the predicted values, set S
to 0
or 1
.
The HOLT_WINTERS_WITH_FIT(function(field_key),N,S)
function returns the fitted values and N
predicted field values of the specified field key. The predicted field values are seasonally adjusted.
The HOLT_WINTERS()
and HOLT_WINTERS_WITH_FIT()
functions process the data that occurs at the same time interval. The nested InfluxQL functions and GROUP BY time()
clauses allow the Holt-Winters functions to process general data.
The HOLT_WINTERS()
and HOLT_WINTERS_WITH_FIT()
functions support INT64 and FLOAT64 field values.
Example 1: Predict the field values of a field key
This example shows how to use Chronograf to visualize data. The following data of the NOAA_water_database
dataset is used in this example.
SELECT "water_level" FROM "NOAA_water_database"."autogen"."h2o_feet" WHERE "location"='santa_monica' AND time >='2015-08-22 22:12:00' AND time <='2015-08-28 03:00:00'
Step 1: Match the overall trend of raw data. Write an SQL statement to match the overall trend of the water_level
raw data. The SQL statement must include the GROUP BY time()
clause. In the following example, the FIRST()
function is used.
SELECT FIRST("water_level") FROM "NOAA_water_database"."autogen"."h2o_feet" WHERE "location"='santa_monica'and time >='2015-08-22 22:12:00'and time <='2015-08-28 03:00:00' GROUP BY time(379m,348m)
In the GROUP BY time()
clause, the first argument 379m
indicates the time duration between each peak and trough in the water_level
data. The second argument 348m
is an offset interval. In TSDB for InfluxDB®, you can use the offset interval to change the default time boundaries that are specified by the GROUP BY time()
clause to match the time ranges of the raw data.
Step 2: Determine a seasonal pattern. Determine the seasonal pattern of data based on the query results that are obtained in Step 1.
The blue line in the following figure shows that the seasonal pattern in the water_level
data occurs about every 25 hours and 15 minutes. Each season contains four points. Therefore, 4
is the argument that is used to determine the seasonal pattern.
Step 3: Apply the HOLT_WINTERS()
function. Add the Holt-Winters function to the query. In the following example, the HOLT_WINTERS_WITH_FIT()
function is used to obtain fitted values and predicted values.
SELECT HOLT_WINTERS_WITH_FIT(FIRST("water_level"),10,4) FROM "NOAA_water_database"."autogen"."h2o_feet" WHERE "location"='santa_monica' AND time >='2015-08-22 22:12:00' AND time <='2015-08-28 03:00:00' GROUP BY time(379m,348m)
In the HOLT_WINTERS_WITH_FIT()
function, the first argument 10
indicates that 10 predicted field values are requested. All the predicted points occur based on the 379m
interval. This interval is the same as the first argument in the GROUP BY time()
clause. The second argument 4
in the HOLT_WINTERS_WITH_FIT()
function indicates the seasonal pattern that is specified in Step 2.
FAQ
Why is the number of points returned by a query that uses the HOLT_WINTERS() function less than N?
The number of the predicted points that you obtain may be less than N
. This occurs when the mathematical calculations show unstable performance and the function cannot predict more points as expected. This indicates that the HOLT_WINTERS()
function is not applicable to the specified dataset, or that the seasonal adjustment parameters are invalid and the algorithms cannot run as expected.