timechart

指定した時間単位ごとに集計関数の結果を計算します。by 節でグループフィールドを指定すると、グループフィールドの値が列に変換されてフィールド別の統計値を計算します。

コマンドプロパティ

項目説明
コマンドタイプ加工クエリ
必要な権限なし
ライセンス使用量該当なし
並列実行対応
分散実行制御ノードで実行（reducer）

構文

timechart span=INT{s|m|h|d|w|mon|y} [offset=INT{s|m|h|d|w|mon|y}] [parallel=BOOL] AGG_FUNC [as ALIAS], ... [by FIELD, ...]

オプション

span=INT{s|m|h|d|w|mon|y}
時間間隔（デフォルト: 1d）。s（秒）、m（分）、h（時）、d（日）、w（週）、mon（月）、y（年）単位で指定できます。例えば 10m は 10 分単位です。mon 単位を使用する場合は 12 の約数である 1mon、2mon、3mon、4mon、6mon のみ指定できます。y 単位を使用する場合は 1y のみ許可されます。
offset=INT{s|m|h|d|w|mon|y}
時間オフセット。s（秒）、m（分）、h（時）、d（日）、w（週）、mon（月）、y（年）単位で指定できます。span で生成された時間区間の開始点を調整する際に使用します。例えば offset=8h は 8 時間のオフセットを適用します。
parallel=BOOL
並列集計の使用有無。t または f で指定します。

ターゲット

AGG_FUNC [as ALIAS], ...
集計関数とオプションのエイリアス。カンマ（,）で区切って複数の集計関数を指定できます。as キーワードで出力フィールド名を指定します。
[by FIELD, ...]
グループ基準フィールド。カンマ（,）で区切って複数のフィールドを指定できます。グループフィールドの値が出力テーブルの列に変換されます。

入力フィールド

フィールドタイプ必須説明
_timetimestamp必須時間基準フィールド。timestamp 型でなければならず、このフィールドがないかtimestamp 型でないレコードは集計から除外されます。

出力フィールド

フィールドタイプ説明
_timetimestampspan によって生成された時間区間の開始時点
集計結果またはグループ値可変by 節がなければ集計関数結果が列として出力され、by 節があればグループフィールド値が列として出力される

エラーコード

解析エラー
エラーコードメッセージ説明
21800필드를 입력하십시오.集計関数が指定されていない場合
ランタイムエラー

該当なし

説明

timechart コマンドは、_time フィールドを基準に時間軸を指定した間隔（span）で分割し、各区間ごとに集計関数の結果を計算します。時間ベースのデータのトレンドを分析するための特殊なピボットコマンドです。

マシンのタイムゾーン基準時刻（1970-01-01 00:00:00）から span 単位で均等な時間区間が生成されます。各レコードの _time 値が該当区間の開始点に変換されて集計されます。例えば span=10m の場合、14:23:45 のレコードは 14:20:00 区間に属します。

_time フィールドがないか timestamp 型でないレコードは集計から除外されます。

by 節を指定するとグループフィールドの値が出力テーブルの列に変換されます。通常の stats コマンドと異なり、時間別の変化トレンドを可視化するのに適した形でデータが再構成されます。

offset オプションを使用すると時間区間の開始点を調整できます。例えば span=1d offset=8h は午前 8 時を基準に 1 日単位で集計します。

timechartはby句を使用するピボットコマンドであるため、メモリ内バッファがデフォルト50,000件を超えると中間結果をディスクにフラッシュし、クエリ終了時にマージソートで最終結果を生成します。by句のユニーク値の種類が多いか時間区間数が多いほど、メモリ使用量とディスクI/Oが増加します。

使用例

  1. 1 時間単位の Web リクエスト件数を集計する

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

    直近 1 日間の Web ログを 1 時間単位でリクエスト件数を集計します。

  2. 10 分単位のトラフィックを集計する

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

    直近 1 時間の Web ログを 10 分単位で送信バイト合計を集計します。

  3. HTTP メソッド別の時間帯分析

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

    HTTP メソッド別に 1 時間単位のリクエスト件数を集計します。method フィールドの値（GET、POST など）がそれぞれ列として出力されます。

  4. オフセットを使用した業務時間基準の日別集計

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

    午前 8 時を基準に 1 日単位でリクエスト件数を集計します。

  5. 複数の集計関数とグループフィールドの組み合わせ

    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

    サービス別に 1 時間単位の送信バイト合計と平均応答時間を集計します。

  6. 並列処理を使用した大量データの集計

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

    直近 30 日間の Web ログを並列処理で日別リクエスト件数と送信バイトを集計します。