timechart

Calculates aggregate function results for each specified time interval. When you specify a group field using the by clause, the group field values are converted into columns and statistics are calculated per field.

Command properties

Syntax

Options

span=INT{s|m|h|d|w|mon|y}

Time interval (default: 1d). Specify in units of s (seconds), m (minutes), h (hours), d (days), w (weeks), mon (months), or y (years). For example, 10m means 10-minute intervals. When using the mon unit, only values that are divisors of 12 are allowed: 1mon, 2mon, 3mon, 4mon, 6mon. When using the y unit, only 1y is allowed.

offset=INT{s|m|h|d|w|mon|y}

Time offset. Specify in units of s (seconds), m (minutes), h (hours), d (days), w (weeks), mon (months), or y (years). Use this to adjust the starting point of the time intervals created by span. For example, offset=8h applies an 8-hour offset.

parallel=BOOL

Whether to use parallel aggregation. Specify t or f.

Target

AGG_FUNC [as ALIAS], ...

Aggregate functions with optional aliases. You can specify multiple aggregate functions separated by commas (,). Use the as keyword to specify the output field name.

[by FIELD, ...]

Group-by fields. You can specify multiple fields separated by commas (,). The values of the group fields are converted into columns in the output table.

Input fields

Output fields

Error codes

Parsing errors

Runtime errors

N/A

Description

The timechart command uses the _time field to divide the time axis into intervals of the specified span and calculates aggregate function results for each interval. It is a specialized pivot command for analyzing trends in time-series data.

Time intervals are created at equal span intervals from the machine's timezone-based epoch (1970-01-01 00:00:00). Each record's _time value is converted to the starting point of the corresponding interval for aggregation. For example, with span=10m, a record at 14:23:45 falls into the 14:20:00 interval.

Records without a _time field or with a non-timestamp value are excluded from aggregation.

When a by clause is specified, the values of the group fields are converted into columns in the output table. Unlike the general stats command, the data is restructured into a form well-suited for visualizing changes over time.

The offset option lets you adjust the starting point of the time intervals. For example, span=1d offset=8h aggregates by day starting at 8:00 AM.

Because timechart is a pivot command that uses a by clause, when the in-memory buffer exceeds the default threshold of 50,000 records, intermediate results are flushed to disk and the final result is produced via merge sort when the query completes. Memory usage and disk I/O increase as the number of unique values in the by clause or the number of time intervals grows.

Examples

1. Aggregate web request counts per hour

   table duration=1d web_logs | timechart span=1h count
   

   Aggregates web log request counts in 1-hour intervals over the last day.

2. Aggregate traffic every 10 minutes

   table duration=1h web_logs | timechart span=10m sum(bytes) as total_bytes
   

   Aggregates total bytes transmitted in 10-minute intervals over the last hour.

3. Analyze request counts by HTTP method per time period

   table duration=1d web_logs | timechart span=1h count by method
   

   Aggregates request counts in 1-hour intervals per HTTP method. The values of the method field (GET, POST, etc.) are each output as a column.

4. Daily aggregation based on business hours using an offset

   table duration=7d web_logs | timechart span=1d offset=8h count as daily_count
   

   Aggregates request counts by day starting at 8:00 AM.

5. Combine multiple aggregate functions with a group field

   json "[{'_time':'2025-03-17 10:00:00','svc':'api','bytes':1024,'elapsed':50},
          {'_time':'2025-03-17 10:05:00','svc':'api','bytes':2048,'elapsed':80},
          {'_time':'2025-03-17 10:00:00','svc':'web','bytes':512,'elapsed':30},
          {'_time':'2025-03-17 11:00:00','svc':'api','bytes':4096,'elapsed':120}]"
   | eval _time = date(_time, "yyyy-MM-dd HH:mm:ss")
   | timechart span=1h sum(bytes) as total_bytes, avg(elapsed) as avg_elapsed by svc
   

   Aggregates total bytes transmitted and average response time in 1-hour intervals per service.

6. Aggregate large data volumes with parallel processing

   table duration=30d web_logs | timechart span=1d parallel=t count as daily_count, sum(bytes) as daily_bytes
   

   Aggregates daily request counts and bytes transmitted for the last 30 days using parallel processing.