Time Series Database:Predictor functions

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 Sparameter 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.