stl

Decomposes time series data into trend, seasonality, and residual (error) components. Uses the STL (Seasonal-Trend decomposition procedure based on LOESS) algorithm to analyze patterns in time series data.

Command properties

Item	Description
Command type	Transforming
Required permission	None
License usage	N/A
Parallel execution	Not supported
Distributed execution	Not supported

Syntax

stl [period=INT{y|mon|w|d|h|m|s}] FIELD [by FIELD, ...]

Options

period=INT{y|mon|w|d|h|m|s}: Time series period. Specify using s (second), m (minute), h (hour), d (day), w (week), mon (month), or y (year) units. If not specified, the seasonal period is automatically estimated using spectral density estimation.

Target

FIELD: Target field for decomposition. The field value must be a numeric type.
[by FIELD, ...]: Group fields. When a by clause is specified, records with the same group field value are decomposed independently.

Input fields

Field	Type	Required	Description
`_time`	timestamp	Required	Time series timestamp field. The period is estimated from the time interval between adjacent records.
`FIELD`	number	Required	Target field for decomposition. If the value is non-numeric or null, the original record is output unchanged without decomposition.

Output fields

Field	Type	Description
`_trend`	double	Trend component
`_seasonal`	double	Seasonal component. Not output if no periodicity is detected.
`_error`	double	Residual component (original value minus trend and seasonal components)

Error codes

Parse errors

Error code	Message	Description
40300	stl 명령의 대상 필드가 누락되었습니다.	The target field is not specified.
40301	stl 명령의 그룹 필드가 누락되었습니다.	No group field is specified after the `by` clause.
40804	머신러닝 라이선스가 필요합니다.	A machine learning license is required.

Runtime errors

N/A

Description

The stl command collects all input records and then performs LOESS-based seasonal-trend decomposition.

If the period option is not specified, the seasonal period is automatically estimated using spectral density estimation. If periodicity is detected, three fields are output: _trend, _seasonal, and _error. If no periodicity is detected, only trend extraction using LOESS smoothing is performed, outputting two fields: _trend and _error.

LOESS smoothing requires a minimum of 7 records. If the input has fewer than 7 records, the original records are output unchanged without decomposition.

When the by clause is specified, decomposition is performed independently for each group. The number of records per group is limited to 1,000 by default, and you can adjust the limit using the -Dlogpresso.stl.limit=N JVM option.

Examples

Auto-detect the period
```
table duration=7d sys_cpu_logs
| timechart span=1h avg(usage) as usage
| stl usage
```
Aggregates CPU usage from the past 7 days in 1-hour intervals, then automatically detects the period and decomposes into trend, seasonal, and residual components.

Specify the period

table duration=30d sys_cpu_logs
| timechart span=1h avg(usage) as usage
| stl period=1d usage

Decomposes the time series data with a specified daily period.

Decompose by group
```
table duration=7d sys_cpu_logs
| timechart span=1h avg(usage) as usage by host
| stl usage by host
```
Performs time series decomposition independently for records sharing the same host field value.