DQL 関数リファレンス¶

DQL は、データの集約、変換、マッチングのための豊富な関数を提供します。このドキュメントでは、各関数のセマンティクス、パラメータ、使用方法について詳しく説明します。

集約関数¶

集約関数は、複数行のデータを単一の値に集約するために使用されます。通常、時間ウィンドウ（time-expr）とグループ化（BY 句）と組み合わせて使用します。

基本集約¶

sum¶

フィールド値の合計を計算します。

構文：

sum(field)

パラメータ：

• field: 数値フィールド

例：

// 総リクエスト数を計算
M::http_requests:(sum(request_count)) [1h]

// サービスごとにグループ化して総リクエスト数を計算
M::http_requests:(sum(request_count)) [1h] BY service

avg¶

フィールド値の平均値を計算します。

構文：

avg(field)

パラメータ：

• field: 数値フィールド

例：

// 平均応答時間を計算
M::response_time:(avg(duration)) [1h] BY endpoint

// 平均 CPU 使用率を計算
M::cpu:(avg(usage)) [1h] BY host

count¶

データ行数をカウントします。

構文：

count(field)
count(*)

パラメータ：

• field: 任意のフィールド。NULL でない値の数をカウントします。
• *: すべての行数をカウントします。

例：

// ログエントリ数をカウント
L::nginx:(count(*)) [1h]

// 応答時間があるリクエスト数をカウント
M::response_time:(count(duration)) [1h] BY service

min / max¶

フィールドの最小値または最大値を計算します。

構文：

min(field)
max(field)

パラメータ：

• field: 数値フィールド

例：

// 最大応答時間を特定
M::response_time:(max(duration)) [1h] BY endpoint

// CPU 使用率の範囲を特定
M::cpu:(min(usage), max(usage)) [1h] BY host

first / last¶

最初または最後の値を取得します（時間順）。

構文：

first(field)
last(field)
last_row(field)

パラメータ：

• field: 任意のフィールド

説明：

• first: 最も古い時間の値を返します。
• last: 最も新しい時間の値を返します。フィールドが配列型の場合は展開されます。
• last_row: 最も新しい時間の値を返します。配列型は展開されません。

例：

// 最新のステータス値を取得
M::system:(last(status)) [1h] BY host

// 初期値と最終値を取得
M::counter:(first(value), last(value)) [1h] BY metric

any¶

任意のNULLでない値を1つ返します。サンプルデータの取得や、特定の集約順序が必要ない場合に適しています。

構文：

any(field)

パラメータ：

• field: 任意のフィールド

例：

// 任意のメッセージサンプルを取得
L::logs:(any(message)) [1h] BY service

// 任意のエラースタックトレースを取得
L::error_logs:(any(stack_trace)) [1h] BY error_type

SHIFT¶

式レベルの SHIFT は、プロジェクション内で過去のウィンドウの集約値を参照し、現在の集約結果と並べて表示します。

構文：

<aggregate-or-subquery-measure> SHIFT <duration>

現在値、過去値、および派生計算はすべてプロジェクション式で明示的に指定します。同じ過去値を複数回参照する場合は、同じ SHIFT 式を繰り返し記述します。

例：

L::logs:(
  service,
  count(*) AS requests,
  count(*) SHIFT 7d AS requests_last_week,
  CASE
    WHEN (count(*) SHIFT 7d) = nil OR (count(*) SHIFT 7d) = 0 THEN nil
    ELSE count(*) / (count(*) SHIFT 7d)
  END AS requests_ratio
)[1d:1h] BY service

duration は正の固定長（例：1h、7d）である必要があります。

使用制限：

• プロジェクション内でのみ使用でき、現在のプロジェクション内で行アイデンティティがウィンドウ間で安定している集約式、またはそのような集約をソースとするサブクエリのメジャーにのみ作用します。
• 同じ SELECT で宣言されたばかりのプロジェクションエイリアス、ディメンション列、WHERE、BY、HAVING、ORDER BY、SORDER BY には作用できません。また、SHIFT をネストすることもできません。
• distinct、distinct_by_collapse、field_values、histogram など、各ウィンドウのデータによって出力行が決まる集約は operand として使用できません。uint(field) など、元のフィールドを変換するだけの式は集約メジャーではなく、abs(sum(field)) など、安定した集約をラップするスカラー変換は使用できます。
• 過去の値に基づいてフィルタリングや並べ替えを行う必要がある場合は、外側の SELECT で実行します。
• 同じ SELECT 内のすべての式レベルの SHIFT は、合計で最大16個の異なるオフセットを含むことができます。

クエリレベルの SHIFT（DQL メインドキュメントの時間シフト を参照）と式レベルの SHIFT は組み合わせることができます。クエリレベルのオフセットが最初にクエリ全体の基準ウィンドウを決定し、式レベルのオフセットはその基準ウィンドウに対して相対的に、より古い集約値を読み取ります。

spread¶

レンジ（最大値と最小値の差）を計算します。

構文：

spread(field)

パラメータ：

• field: 数値フィールド

例：

// 応答時間の変動幅を計算
M::response_time:(spread(duration)) [1h] BY endpoint

stddev¶

標準偏差を計算します。

構文：

stddev(field)

パラメータ：

• field: 数値フィールド

例：

// 応答時間の標準偏差を計算
M::response_time:(stddev(duration)) [1h] BY endpoint

mode¶

最頻値（最も頻繁に出現する値）を計算します。

構文：

mode(field)

パラメータ：

• field: 任意のフィールド

例：

// 最も一般的な応答ステータスコードを特定
M::http:(mode(status)) [1h] BY endpoint

count_series¶

時系列（グループ）の数を計算します。現在のクエリ範囲内にいくつの独立した時系列があるかを返します。

構文：

count_series(field)

パラメータ：

• field: 任意のフィールド（通常は * または任意の存在するフィールドを使用）

例：

// CPU メトリクスを報告しているホストの数を計算
M::cpu:(count_series(*)) [1h]

// サービスごとのインスタンス数を計算
M::http_requests:(count_series(*)) [1h] BY service

統計集約（推定関数）¶

以下の関数は、確率的データ構造を使用して推定を行います。大規模データのシナリオに適しており、精度とパフォーマンスのバランスを取ることができます。

count_distinct¶

フィールドの異なる値の数（推定値）を計算します。

構文：

count_distinct(field)

パラメータ：

• field: 任意のフィールド

アルゴリズムの説明：

HyperLogLog アルゴリズムを使用してカーディナリティを推定します。 - レジスタ数：2¹⁶ = 65536 - LogLog-Beta 推定法を使用 - 標準誤差：約 0.4%

適用シナリオ：

• 独立ユーザー数（UV）の統計
• 異なる IP アドレス数の計算
• 一意のリクエスト ID 数の分析

例：

// 独立ユーザー数を統計
L::access_logs:(count_distinct(user_id)) [1d] BY service

// アクセスした異なる IP の数を計算
L::nginx:(count_distinct(client_ip)) [1h] BY endpoint

percentile¶

フィールドの百分位数（推定値）を計算します。

構文：

percentile(field, n)
pXX(field)  // 短縮形

パラメータ：

• field: 数値フィールド
• n: 百分位数、範囲 0-100

短縮形：

• p50(field) は percentile(field, 50) と同等
• p95(field) は percentile(field, 95) と同等
• p99(field) は percentile(field, 99) と同等

アルゴリズムの説明：

対数線形補間ヒストグラムを使用して推定します。 - バケット範囲：10⁻⁹ から 10¹⁸、ほとんどの数値シナリオをカバー - 各桁は128個のバケットに分割 - 対数空間での線形補間を使用して精度を向上

適用シナリオ：

• 応答時間の P99、P95 の計算
• パフォーマンス指標のテールレイテンシの分析
• サービスレベルアグリーメント（SLA）達成状況の評価

例：

// 応答時間の P99 を計算
M::response_time:(percentile(duration, 99)) [1h] BY service

// 短縮形を使用
M::response_time:(p99(duration)) [1h] BY service

// Rollup 関数として呼び出し：各時系列で P95 を計算し、service で集約
M::response_time:(avg(duration)) [1h::5m:percentile(95)] BY service

// 複数の百分位数を同時に計算
M::response_time:(p50(duration), p95(duration), p99(duration)) [1h] BY service

median¶

中央値を計算します。percentile(field, 50) と同等です。

構文：

median(field)

例：

// 応答時間の中央値を計算
M::response_time:(median(duration)) [1h] BY service

ヒストグラム関数¶

DQL は、さまざまなデータソースとシナリオに適した3つのヒストグラム関連関数を提供します。

histogram_auto（推奨）¶

分布ヒストグラムを自動生成します。ログ、Trace などの明細データの数値分布統計のために設計されています。

特徴：

• バケット境界の指定が不要で、データ分布に自動適応します。
• 対数線形補間ヒストグラムアルゴリズムを使用し、10⁻⁹ から 10¹⁸ の数値範囲をカバーします。
• 分位数統計とバケット分布情報を同時に返します。

構文：

histogram_auto(field)

パラメータ：

• field: 数値フィールド

戻り値： | 列名 | 説明 | | -------------- | ---------------- | | lower_bounds | 各バケットの下限境界の配列 | | upper_bounds | 各バケットの上限境界の配列 | | counts | 各バケットのカウントの配列 | | min | 最小値 | | p50 | 中央値 | | p75 | 75パーセンタイル | | p90 | 90パーセンタイル | | p95 | 95パーセンタイル | | p99 | 99パーセンタイル | | max | 最大値 |

アルゴリズムの説明： 推定ヒストグラム（対数線形補間）を使用し、各桁は128個のバケットに分割されます。大規模データの分布統計に適しています。

適用シナリオ：

• ログ内の応答時間分布の分析
• Trace 内の処理時間分布の統計
• バケット境界を事前に設定せずに行う探索的データ分析

例：

// Nginx アクセスログの応答時間分布を分析
L::nginx:(histogram_auto(response_time)) [1h]

// サービスごとにリクエスト処理時間の分布を統計
L::app_logs:(histogram_auto(duration)) [1h] BY service

// Trace 呼び出しの処理時間分布を統計
T::http_client:(histogram_auto(elapsed)) [1h] BY operation

結果例：

注：lower_bounds、upper_bounds、counts は配列型で、各バケットの境界とカウントを表します。

histogram（Deprecated）¶

指定されたバケット境界のヒストグラムを生成します。この関数は Deprecated です。代わりに histogram_auto を使用することを推奨します。

説明： histogram はバケットの境界パラメータを手動で指定する必要があり、柔軟性に欠けます。histogram_auto はデータ分布に自動適応し、より広い数値範囲をカバーし、より豊富な統計情報を返します。

構文：

histogram(field, left_bound, right_bound, bucket_size [, threshold])

パラメータ：

• field: 数値フィールド
• left_bound: 左境界
• right_bound: 右境界
• bucket_size: バケットサイズ
• threshold（オプション）: 単一バケットの最小カウント。この値未満のバケットは返されません。

戻り値： 2つの列を返します。bucket_le（バケットの上限境界）と count（カウント）です。

例：

// 0-1000ms の範囲で、100ms ごとのバケットを持つヒストグラムを生成
M::response_time:(histogram(duration, 0, 1000, 100)) [1h]

// 代わりに histogram_auto を使用することを推奨
M::response_time:(histogram_auto(duration)) [1h]

結果例：

histogram_quantile¶

Prometheus ヒストグラムメトリクスから分位数を計算します。

特徴：

• Prometheus から報告されたヒストグラムタイプのメトリクスを処理するために特化しています。
• le タグ（または VictoriaMetrics の vmrange タグ）に依存してバケット境界を識別します。
• 入力データは累積カウント（cumulative）である必要があります。

構文：

histogram_quantile(field, q)

パラメータ：

• field: ヒストグラムカウントフィールド（例：http_request_duration_bucket）
• q: 分位数、範囲 0-1（例：0.99 は P99 を意味します）

使用シナリオ比較：

le タグ処理メカニズム：

histogram_quantile は le タグ（less than or equal）に依存してヒストグラムバケットの境界を識別します。

1. Prometheus 形式（デフォルト）：le タグを使用してバケットの上限境界を直接表します。
2. le の値は数値（例："0.1", "1", "10"）または "+Inf"（無限大）です。

3. データは累積カウント（cumulative）である必要があります。

4. VictoriaMetrics 形式：vmrange タグを使用して範囲を表します。

5. 形式は "下限...上限"（例："0.1...0.2"）です。
6. データは範囲カウント（非累積）です。
7. 関数は自動的に範囲カウントを累積カウントに変換します。

計算プロセス： 1. le の値ですべてのバケットをソートします。 2. vmrange 形式の場合は、カウントを累積して累積分布に変換します。 3. バケットカウントが単調増加していることを確認します（異常なデータの可能性を修正）。 4. 線形補間を使用して目的の分位数を計算します。

PromQL との違い：

同等の例：

ヒストグラムメトリクス http_request_duration_bucket があり、le タグ（例：0.1, 0.5, 1, 5, +Inf）と service タグが含まれているとします。

シナリオ 1: P99 レイテンシの計算

DQL：

M::http_request_duration:(histogram_quantile(duration_bucket, 0.99)) [1h] BY service

PromQL と同等：

histogram_quantile(0.99, sum(rate(http_request_duration_bucket[1h])) by (le, service))

シナリオ 2: 各サービスの P95 レイテンシの計算（複数グループ）

DQL：

M::http_request_duration:(
    histogram_quantile(duration_bucket, 0.95)
) [1h] BY service, endpoint

PromQL と同等：

histogram_quantile(0.95, sum(rate(http_request_duration_bucket[1h])) by (le, service, endpoint))

シナリオ 3: P50（中央値）と P99 の計算

DQL：

M::http_request_duration:(
    histogram_quantile(duration_bucket, 0.50) as p50,
    histogram_quantile(duration_bucket, 0.99) as p99
) [1h] BY service

PromQL と同等：

label_join(
  histogram_quantile(0.50, sum(rate(http_request_duration_bucket[1h])) by (le, service)), "quantile", "", "0.50"
)
or
label_join(
  histogram_quantile(0.99, sum(rate(http_request_duration_bucket[1h])) by (le, service)), "quantile", "", "0.99"
)

注：PromQL では、異なる分位数の結果を区別するために label_join または label_replace が必要です。

注意事項：

• 入力データには le または vmrange タグが含まれている必要があります。含まれていないと計算できません。
• +Inf バケットがない場合、最後のバケットの上限境界が最大値として使用されます。
• カウントが 0 または NaN のバケットはスキップされます。
• 分位数が 0 未満の場合は -Inf を返し、1 より大きい場合は +Inf を返します。

TopN 関数¶

top¶

上位 N 個の最大値を取得します。

構文：

top(field, n)

パラメータ：

• field: 数値フィールド
• n: 返される値の数

例：

// 応答時間が最も長い 5 つのリクエストを取得
M::response_time:(top(duration, 5)) [1h] BY service

// トラフィックが最も多い 10 のホストを取得
M::network:(top(bytes, 10)) [1h]

結果例：

注：複数行を返し、各行に1つの TopN 値が含まれます。

bottom¶

下位 N 個の最小値を取得します。

構文：

bottom(field, n)

パラメータ：

• field: 数値フィールド
• n: 返される値の数

例：

// 応答時間が最も短い 5 つのリクエストを取得
M::response_time:(bottom(duration, 5)) [1h] BY service

結果例：

注：複数行を返し、各行に1つの BottomN 値が含まれます。

値収集関数¶

distinct¶

フィールドのすべての異なる値を返します。

構文：

distinct(field)

例：

// すべての異なるステータスコードを取得
M::http:(distinct(status)) [1h] BY endpoint

結果例：

注：複数行を返し、各行に1つの異なる値が含まれます。

distinct_by_collapse¶

折りたたみ戦略に従ってフィールドの異なる値を取得し、重複排除時に他のフィールドの最後の値を保持します。

構文：

distinct_by_collapse(field, [last_field1, last_field2, ...])

パラメータ：

• field: 重複排除の基準となるフィールド
• last_fields（オプション）: 最後の値を保持する必要があるフィールドのリスト

説明： distinct とは異なり、distinct_by_collapse は重複排除時に関連する他のフィールドの情報（最後の値を取得）を保持します。コンテキスト情報を保持する必要があるシナリオに適しています。

例：

// 異なるユーザー ID を取得し、各ユーザーの最後のアクセス時刻を保持
L::access_logs:(distinct_by_collapse(user_id, [timestamp])) [1h]

// 異なるホストを取得し、最後のステータスとメッセージを保持
O::HOST:(distinct_by_collapse(host, [status, message])) [1h]

結果例：

注：重複排除された主フィールドの値と、last_fields で指定された他のフィールドの最後の値を返します。

collect¶

すべての値を収集します（重複を含む）。

構文：

collect(field [, limit])

パラメータ：

• field: 任意のフィールド
• limit（オプション）: 収集する最大数

例：

// すべての応答時間を収集
M::response_time:(collect(duration)) [1h] BY service

// 最大 100 個の値を収集
M::response_time:(collect(duration, 100)) [1h] BY service

結果例：

注：配列型を返し、収集されたすべての値が含まれます（重複値を含む可能性があります）。

collect_distinct¶

すべての異なる値を収集します。

構文：

collect_distinct(field [, limit])

パラメータ：

• field: 任意のフィールド
• limit（オプション）: 収集する最大数

例：

// すべての異なるエラータイプを収集
L::error_logs:(collect_distinct(error_type)) [1h] BY service

結果例：

注：配列型を返し、重複排除されたすべての値が含まれます。

field_values¶

フィールドのすべての値を取得し、配列型を返します。

構文：

field_values(field)

例：

// すべてのタグ値を取得
M::metrics:(field_values(tags)) [1h] BY metric_name

結果例：

注：配列型を返し、フィールドのすべての値が含まれます。

フィルタリング集約¶

count_filter¶

指定されたリスト内のフィールド値の数をカウントします。

構文：

count_filter(field, [value1, value2, ...])

パラメータ：

• field: 任意のフィールド
• values: 値のリスト

例：

// 特定のステータスコードのリクエスト数をカウント
M::http:(count_filter(status, [200, 201, 204])) [1h] BY endpoint

// エラーレベルのログをカウント
L::logs:(count_filter(level, ["error", "critical"])) [1h] BY service

補助関数¶

default¶

フィールドにデフォルト値を設定します。フィールドが空の場合にデフォルト値を返します。

構文：

default(field, default_value)

パラメータ：

• field: 任意のフィールド
• default_value: デフォルト値（数値、文字列、ブール値、または null を指定可能）

例：

// 空の値にデフォルトの応答時間を設定
M::response_time:(default(duration, 0)) [1h] BY service

時系列関数¶

時系列関数は、時間とともに変化するデータ、特に Counter タイプのメトリクスを処理するために使用されます。

Rollup 関数¶

Rollup 関数は、時間ウィンドウ内で元の時系列データを前処理するために使用されます。詳細については、このドキュメント内の Rollup 関数 を参照してください。

記述方法の説明：

• Rollup は時間句に記述されます。例：[rate]、[1h::5m:rate]。
• クエリの外側（例：rate(DQL)）に記述するのは、Rollup ではなく外側関数です。
• Rollup の短縮形、Rollup 関数呼び出し、および明示的な集約呼び出しの実行フェーズとパラメータの違いについては、DQL メインドキュメントの Rollup 関数 を参照してください。

時間句は Rollup の短縮形をサポートし、Rollup 関数に追加のアルゴリズムパラメータを渡すこともできます。例：[1h::1m:ewma(0.3)]。時間句内のパラメータはアルゴリズムパラメータのみを示し、入力フィールドは Select フィールドによって決定されます。複数の入力フィールドが必要な関数は、Select 句で明示的な集約呼び出しを使用する必要があります。

Rollup 短縮形をサポートする関数：

Rollup 関数呼び出しをサポートする関数：

例：

// リクエスト QPS を計算
M::http_requests:(sum(request_count)) [1h::5m:rate] BY service

// 短縮形
M::cpu:(max(usage)) [rate]

// アルゴリズムパラメータ付きの Rollup 関数呼び出し
M::cpu:(avg(usage)) [1h::1m:ewma(0.3)] BY host

増加率計算¶

rate¶

メトリクスの増加率（毎秒）を計算します。

構文：

rate(field)

説明： rate は、時間ウィンドウ内の Counter メトリクスの平均増加率を計算します。単調増加する Counter タイプのメトリクスの場合、元の値をそのまま集約しても意味がなく、最初に増加率を計算する必要があります。

適用シナリオ：

• リクエスト QPS の計算
• データ書き込みレートの計算
• トラフィック増加トレンドの分析

例：

// リクエスト QPS を計算
M::http_requests:(sum(request_count)) [rate] BY service

// データ取り込みレートを計算
M::data_ingestion:(sum(bytes)) [rate] BY source

irate¶

メトリクスの瞬間増加率を計算します。

構文：

irate(field)

説明： rate とは異なり、irate は最後の2つのデータポイントのみを使用して増加率を計算し、瞬間的な変化率を反映します。アラートシナリオに適しています。

例：

// 瞬間リクエスト QPS を計算
M::http_requests:(sum(request_count)) [irate] BY service

increase¶

メトリクスの増加量を計算します。

構文：

increase(field)

説明： increase は、増加率ではなく、時間ウィンドウ内の総増加量を返します。

例：

// 総リクエスト数の増加を計算
M::http_requests:(sum(request_count)) [increase] BY service

rate_over_sum¶

1秒あたりの平均値を計算します（sum / 時間ウィンドウ（秒））。

構文：

rate_over_sum(field)

説明： sum(field) / 時間ウィンドウ（秒） と同等で、1秒あたりの平均値を計算するために使用されます。Rollup フェーズで累積値を1秒あたりのレートに変換するためによく使用されます。

rate との違い：

• rate：Counter の増加率を計算します（リセットを処理します）。
• rate_over_sum：sum を時間ウィンドウ（秒）で単純に割ります。

例：

// 1秒あたりの平均リクエスト数を計算
M::http_requests:(rate_over_sum(request_count)) [1h] BY service

rate_over_count¶

1秒あたりのカウントを計算します（count / 時間ウィンドウ（秒））。

構文：

rate_over_count(field)

説明： count(field) / 時間ウィンドウ（秒） と同等で、1秒あたりの発生回数を計算するために使用されます。

例：

// 1秒あたりのエラーログ行数を計算
L::error_logs:(rate_over_count(*)) [1h] BY error_type

差計算¶

このセクションでは、関数のセマンティクスについて説明します。同じ関数を Rollup として使用することも（例：[rate]、[increase]）、クエリ内の式として使用することもできます（例：rate(field)、increase(field)）。両方の実行フェーズが異なるため、ビジネス要件に応じて優先的に配置を選択してください。

rate / deriv¶

変化率（導関数）を計算します。rate は Counter タイプのメトリクスに使用され（負の値を無視）、deriv は Gauge タイプのメトリクスに使用されます（負の値を保持します）。

エイリアス： rate のエイリアスは non_negative_derivative です。deriv のエイリアスは derivative です（PromQL スタイル）。

構文：

// Counter メトリクス：非負の変化率を計算（リセットによる負の値を無視）
rate(field)

// Gauge メトリクス：完全な変化率を計算（負の値を含む）
deriv(field)

関数の選択：

例：

// Counter メトリクス：リクエスト QPS を計算
M::requests:(rate(count)) [1h::5m] BY service

// Gauge メトリクス：メモリ使用量の変化率を計算
M::memory:(deriv(used)) [1h::5m] BY host

increase / difference¶

隣接する値の差を計算します。increase は Counter タイプのメトリクスに使用され（負の値を無視）、difference は Gauge タイプのメトリクスに使用されます（負の値を保持します）。

説明： increase と difference は2つの独立した関数であり、動作が異なります。エイリアス関係ではありません。

構文：

// Counter メトリクス：非負の差を計算（リセットによる負の値を無視）
increase(field)

// Gauge メトリクス：完全な差を計算（負の値を含む）
difference(field)

関数の選択：

例：

// Counter メトリクス：リクエストの増加量を計算
M::requests:(increase(count)) [1h::5m] BY service

// Gauge メトリクス：リクエスト数の変化を計算（増加または減少の可能性あり）
M::requests:(difference(count)) [1h::5m] BY service

移動計算¶

moving_average¶

移動平均を計算します。

構文：

moving_average(field, n)

パラメータ：

• field: 数値フィールド
• n: ウィンドウサイズ（データポイント数）

例：

// 5 ポイント移動平均を計算
M::cpu:(moving_average(usage, 5)) [1h::1m] BY host

// Rollup 関数として呼び出し：各時系列で5ポイント移動平均を計算し、host で集約
M::cpu:(avg(usage)) [1h::1m:moving_average(5)] BY host

時系列分析集約¶

以下の関数は、クエリ内で集約関数として使用され、各時間ウィンドウとグループ内の数値シーケンスに対して1つの数値結果を計算します。

ewma¶

指数加重移動平均（Exponentially Weighted Moving Average）を計算します。alpha は平滑化係数で、明示的に渡す必要があります。

構文：

ewma(field, alpha)

パラメータ：

• field: 数値フィールド
• alpha: 平滑化係数、範囲 (0, 1]。値が大きいほど、最新のデータポイントの重みが高くなります。

説明：

• ewma には暗黙のデフォルト alpha はありません。ewma(field) はエラーになります。
• 時間句で Rollup として使用する場合、[...:ewma(alpha)] と記述します。時間句のパラメータは alpha のみを渡し、フィールド名は渡しません。
• ewma には alpha が必要なため、[...:ewma] のようなパラメータなしの Rollup 短縮形はサポートされていません。

例：

// 明示的な集約呼び出し：Select 集約フェーズで EWMA を計算
M::cpu:(ewma(usage, 0.3)) [1h::1m] BY host

// Rollup 関数呼び出し：各時系列で EWMA を計算し、host で集約
M::cpu:(avg(usage)) [1h::1m:ewma(0.3)] BY host

slope¶

時間の経過に伴うシーケンスの線形トレンドの傾きを計算します。時間単位は秒です。

構文：

slope(field)

説明：

• 少なくとも2つの有効なポイントが必要です。
• 時間に変化がない場合、または有効なポイントが不足している場合は、空の値を返します。

例：

// メモリ使用量の増加トレンドを計算
M::memory:(slope(used)) [1h::5m] BY host

zscore¶

ウィンドウ内の平均と標準偏差に対する最新ポイントの Z-Score を計算します。

構文：

zscore(field)

説明：

• 結果は (latest - mean) / stddev です。
• 少なくとも2つの有効なポイントが必要です。標準偏差が0の場合は空の値を返します。

例：

// 履歴ウィンドウに対する最新の応答時間の乖離度を評価
M::response_time:(zscore(duration)) [1h::5m] BY service

mad_score¶

最新ポイントの MAD（Median Absolute Deviation）異常スコアを計算します。

構文：

mad_score(field)

説明：

• 中央値と MAD を使用して最新ポイントの乖離度を測定します。平均/標準偏差よりも外れ値に対してロバストです。
• 少なくとも2つの有効なポイントが必要です。MAD が0の場合は空の値を返します。

例：

// ロバストな異常スコアを使用して最新のレイテンシポイントを検出
M::latency:(mad_score(p95)) [1h::5m] BY service

change_score¶

ウィンドウ内のシーケンスの変化スコアを計算します。平均に顕著な切り替わりが発生した時系列を見つけるために使用されます。

構文：

change_score(field)

説明：

• 可能な分割ポイントを列挙し、分割ポイントの左右のセグメントの平均値の差を比較し、プールされた標準偏差で正規化します。
• 少なくとも4つの有効なポイントが必要です。有効なポイントが不足している場合は空の値を返します。

例：

// エラー率がウィンドウ内で急変したかどうかを検出
M::error_rate:(change_score(value)) [1h::5m] BY service

corr¶

2つの数値フィールド間のピアソン相関係数を計算します。

構文：

corr(left_field, right_field)

説明：

• 戻り値の範囲は通常 [-1, 1] です。
• 少なくとも2組の有効なポイントが必要です。どちらかのフィールドに変化がない場合は空の値を返します。
• corr には2つの入力フィールドが必要なため、時間句の Rollup 記述はサポートされていません。

例：

// CPU 使用率とリクエスト数との間の相関を計算
M::service_metric:(corr(cpu_usage, request_count)) [1h::5m] BY service

cumsum¶

累積和を計算します。

構文：

cumsum(DQL_expression)

例：

// 累積リクエスト数を計算
cumsum(M::requests:(sum(count)) [1h::5m] BY service)

変換関数¶

変換関数は、フィールド値の数学演算、型変換、または文字列処理に使用されます。

数学関数¶

abs¶

絶対値を計算します。

構文：

abs(field)

例：

// 温度偏差の絶対値を計算
M::temperature:(abs(deviation)) [1h] BY sensor

round / ceil / floor¶

丸め関数。

構文：

round(field)          // 四捨五入して整数に
round(field, digits)  // 指定された小数位に四捨五入
ceil(field)           // 切り上げ
floor(field)          // 切り捨て

例：

// 応答時間を切り上げ
M::response_time:(ceil(duration)) [1h]

// パーセンテージを四捨五入
M::cpu:(round(usage)) [1h] BY host

// 平均応答時間を小数点第2位に四捨五入
L::log:(round(avg(duration), 2)) BY api

log / log2 / log10¶

対数関数。

構文：

log(field)    // 自然対数
log2(field)   // 底が2
log10(field)  // 底が10

例：

// 対数変換後の値を計算
M::metrics:(log(value)) [1h] BY metric_name

型変換¶

int / uint / float / string / bool¶

型変換関数。

構文：

int(field)    // 符号付き整数に変換
uint(field)   // 符号なし整数に変換
float(field)  // 浮動小数点に変換
string(field) // 文字列に変換
bool(field)   // ブール値に変換

例：

// 文字列を数値に変換
L::logs:(int(response_time)) [1h] BY service

// 数値を文字列に変換して連結
M::metrics:(string(value)) [1h] BY metric_name

文字列関数¶

lower¶

文字列を小文字に変換します。

構文：

lower(field)

パラメータ：

• field: 文字列フィールド

戻り値： 変換後の小文字の文字列を返します。

upper¶

文字列を大文字に変換します。

構文：

upper(field)

パラメータ：

• field: 文字列フィールド

戻り値： 変換後の大文字の文字列を返します。

trim¶

文字列の両端の空白文字を削除します。

構文：

trim(field)

パラメータ：

• field: 文字列フィールド

戻り値： 両端の空白を削除した文字列を返します。

ltrim¶

文字列の左側の空白文字を削除します。

構文：

ltrim(field)

パラメータ：

• field: 文字列フィールド

戻り値： 左側の空白を削除した文字列を返します。

rtrim¶

文字列の右側の空白文字を削除します。

構文：

rtrim(field)

パラメータ：

• field: 文字列フィールド

戻り値： 右側の空白を削除した文字列を返します。

length¶

文字列の長さを返します（文字数で計算）。

構文：

length(field)

パラメータ：

• field: 文字列フィールド

戻り値： 文字列の長さを返します。

substr¶

部分文字列を切り出します。

構文：

substr(field, start)
substr(field, start, length)

パラメータ：

• field: 文字列フィールド
• start: 開始位置（0から始まり、負の数は末尾からを意味します）
• length（オプション）: 部分文字列の長さ

戻り値： 切り出された部分文字列を返します。

例：

// メッセージの最初の100文字を切り出し
L::logs:(substr(message, 0, 100)) [1h]

// 最後の10文字を切り出し
L::logs:(substr(message, -10)) [1h]

結果例：

regexp_extract¶

正規表現による抽出。

構文：

regexp_extract(field, pattern)
regexp_extract(field, pattern, n)

パラメータ：

• field: 文字列フィールド
• pattern: 正規表現
• n（オプション）: 抽出する n 番目のキャプチャグループ。デフォルトは0（一致全体）。

戻り値： 単一の文字列を返します。n 番目のキャプチャグループの内容を抽出します。一致しない場合は null を返します。

例：

// エラーコードを抽出
L::logs:(regexp_extract(message, 'error_code: (\d+)', 1)) [1h]

// IP アドレスを抽出
L::nginx:(regexp_extract(message, '(\d+\.\d+\.\d+\.\d+)', 1)) [1h]

結果例：

regexp_extract_all¶

すべての一致結果を抽出します。

構文：

regexp_extract_all(field, pattern)
regexp_extract_all(field, pattern, n)

戻り値： すべての一致した部分文字列を含む文字列の配列を返します。

例：

// すべての数字を抽出
L::logs:(regexp_extract_all(message, '\d+', 0)) [1h]

// すべての IP アドレスを抽出
L::logs:(regexp_extract_all(message, '\d+\.\d+\.\d+\.\d+', 0)) [1h]

結果例：

regexp_replace¶

正規表現を使用して一致したテキストを置換します。

構文：

regexp_replace(field, pattern, replacement)

パラメータ：

• field: 文字列フィールド
• pattern: 正規表現
• replacement: 置換文字列。キャプチャグループを参照する必要がある場合は、$1、${1}、$2 などの記法を使用します。キャプチャグループの直後に英数字またはアンダースコアが続く場合は、${1} を使用して曖昧さを排除します（例：${1}_suffix）。リテラルの $ を出力する必要がある場合は $$ を使用します。

戻り値： 置換後の文字列を返します。一致しない場合は、元の文字列を返します。

例：

// メッセージ内の数字を削除してプレフィックスで集約
L::logs:(substr(regexp_replace(message, '\\d+', ''), 0, 20) AS prefix, count(*)) [1h] BY prefix

// キャプチャグループを使用してユーザー ID を正規化
L::logs:(regexp_replace(message, 'user=([0-9]+)', 'uid=$1') AS normalized) [1h]

md5¶

MD5 ハッシュ値を計算します。

構文：

md5(field)

戻り値： 32桁の16進文字列（小文字）を返します。

例：

// メッセージの MD5 を計算
L::logs:(md5(message)) [1h]

結果例：

concat¶

文字列の連結。

構文：

concat(field, ...)

戻り値： 連結された単一の文字列を返します。

例：

// 複数のフィールドを連結
L::logs:(concat(service, ":", level)) [1h]

// 結果例："api:error"、"web:info" など

結果例：

set¶

配列フィールドを重複排除して並べ替えます。

構文：

set(DQL_expression)

戻り値： 重複排除され、並べ替えられた配列を返します。

例：

// すべての異なるタグを取得
set(M::metrics:(tags) [1h] BY metric_name)

// collect の結果を重複排除
set(M::http:(collect(status)) [1h] BY endpoint)

結果例：

ログクラスタリング¶

drain¶

Drain アルゴリズムを使用して類似したログを同じクラスに分類し、そのクラスの代表的なログサンプルを返します。

構文：

drain(field, similarity_threshold)
drain(field, similarity_threshold, max_clusters)

パラメータ：

• field: 文字列フィールドまたは文字列式。通常は message です。
• similarity_threshold: 類似度しきい値。範囲 (0, 1]。値が大きいほど、より類似したログのみが同じクラスに分類されます。
• max_clusters: オプション。最大クラスタリング数。範囲 [1, 10000]。省略時はデフォルトで 1000 です。

戻り値：

文字列型の代表的なログサンプルを返します。このサンプルは、クラスタ作成時の元のログであり、Drain が内部で保持する汎化テンプレートではありません。

アルゴリズムの説明：

Drain は、解析ツリーに基づくログクラスタリングアルゴリズムです。関数は実行プロセスを通じて継続的にクラスタラをトレーニングします。新しいログが既存のクラスタにヒットした場合は、そのクラスタの代表的なサンプルを返します。ヒットしなかった場合は、新しいクラスタを作成し、現在のログをそのクラスタの代表的なサンプルとして設定します。

適用シナリオ：

• 類似ログのグループ化による統計
• 異常ログのクラスタリング分析
• ログのノイズ低減

例：

// 類似ログでクラスタリングして統計。類似度 0.7、最大 1000 クラスタ
L::logs:(count(*)) [1h] BY drain(message, 0.7, 1000) AS sample

// max_clusters を省略した場合、デフォルトで最大 1000 クラスタ
L::logs:(count(*)) [1h] BY drain(message, 0.9) AS sample

// 複数のフィールドを連結してからクラスタリングすることも可能
L::logs:(count(*)) [1h] BY drain(concat(service, " ", message), 0.7) AS sample

結果例：

マッチング関数¶

マッチング関数は、WHERE 句でのテキストマッチングに使用され、ブール値を返す式としても使用できます。

部分文字列マッチング¶

match¶

フィールドに指定された部分文字列が含まれているかどうかを確認します。

構文：

match(pattern)
match(field, pattern)

パラメータ：

• pattern: マッチングする部分文字列
• field: フィールド名（オプション。WHERE 句では省略可能）

例：

// WHERE で使用
L::logs:(message) {match(message, "error")} [1h]

// 短縮形
L::logs:(message) {match("error")} [1h]

// 式として使用
L::logs:(match(message, "timeout")) [1h] BY match_result

フレーズマッチング¶

search¶

トークン化されたフレーズマッチング。日本語と英語の混合をサポートします。

構文：

search(query)
search(field, query)

パラメータ：

• query: 検索フレーズ
• field: フィールド名（オプション）

マッチングルール：

• 日本語：文字単位でトークン化してマッチング
• 英語：単語境界でマッチング（スペース、句読点で区切る）
• 大文字と小文字を区別しない
• 空でない query がちょうど1組の二重引用符で構成され、二重引用符が値全体を囲んでいる場合、フレーズマッチングとして扱います：各トークンは隣接し、順序が一致している必要があります。二重引用符はマッチング内容に含まれません。
• 上記の二重引用符の特殊形式において、空白または句読点のみを含む内容は、引き続き連続リテラル値としてマッチングされます。
• 空のクエリ "" は上記の特殊形式に該当せず、通常のトークン化検索パラメータとして処理されます。
• 二重引用符を含むその他の形式は、すべて有効な通常のトークン化検索パラメータとして扱われ、特別な解釈は行われません。例えば、片側のみの二重引用符、値に追加の二重引用符が含まれる場合、または二重引用符が両端にない場合などです。

例：

// "connection timeout" を含むログをマッチング
L::logs:(message) {search("connection timeout")} [1h]

// 日本語マッチング
L::logs:(message) {search("接続タイムアウト")} [1h]

// 日本語と英語の混合
L::logs:(message) {search("error エラー")} [1h]

// 隣接し、順序が一致するフレーズマッチング。"build succeeded, parse error" はマッチしません
L::logs:(message) {search("\"build error\"")} [1h]

// 句読点のみを含む場合は、連続リテラル部分文字列として直接マッチング
L::logs:(message) {search("\"---\"")} [1h]

正規表現マッチング¶

re / regex / regexp¶

正規表現マッチング。大文字と小文字を区別します。

構文：

re(pattern)
re(field, pattern)
regex(pattern)
regex(field, pattern)
regexp(pattern)
regexp(field, pattern)

パラメータ：

• pattern: 正規表現（PromRegex 構文をサポート）
• field: フィールド名（オプション）

例：

// error で始まるログをマッチング。ERROR で始まるログはマッチしません
L::logs:(message) {re("error.*")} [1h]

// 特定の形式のエラーコードをマッチング
L::logs:(message) {regexp(message, "ERR-\d{4}")} [1h]

// データソースで正規表現を使用
M::re('cpu.*'):(usage) [1h]

ワイルドカードマッチング¶

wildcard¶

ワイルドカードパターンマッチング。大文字と小文字を区別します。

構文：

wildcard(pattern)
wildcard(field, pattern)

パラメータ：

• pattern: ワイルドカードパターン
• *: 任意の数の文字にマッチ
• ?: 1文字にマッチ
• field: フィールド名（オプション）

例：

// error で始まるメッセージをマッチング。ERROR で始まるメッセージはマッチしません
L::logs:(message) {wildcard("error*")} [1h]

// 特定の形式をマッチング
L::logs:(message) {wildcard(message, "ERR-????")} [1h]

CIDR マッチング¶

cidr¶

IP アドレスネットワークセグメントのマッチング。

構文：

cidr(cidr)
cidr(field, cidr)

パラメータ：

• cidr: CIDR 表記のネットワークセグメント。例：192.168.1.0/24
• field: IP アドレスフィールド（オプション）

例：

// 内部ネットワーク IP をマッチング
L::nginx:(*) {cidr(client_ip, "10.0.0.0/8")} [1h]

// 特定のネットワークセグメントをマッチング
L::nginx:(*) {cidr(client_ip, "192.168.1.0/24")} [1h]

フィールド存在確認¶

exists¶

フィールドが存在するかどうかを確認します。exists() は特別なプレースホルダであり、通常は比較式の右側で使用されます。

構文：

exists()

推奨される使用方法：

field = exists()   // フィールドが存在する（NULL でない）
field != exists()  // フィールドが存在しない、または NULL である

例：

// error_type フィールドがあるログを検索
L::logs:(message) {error_type = exists()} [1h]

// error_type フィールドがないログを検索
L::logs:(message) {error_type != exists()} [1h]

クエリ文字列構文¶

query_string¶

クエリ文字列構文を使用して複雑なマッチングを行います。

構文：

query_string(query)
query_string(field, query)

パラメータ：

• query: クエリ文字列
• field: フィールド名（オプション。デフォルトは全文マッチング）

クエリ文字列構文：

1. 語句マッチング¶

foo              # foo を含む内容にマッチ
"foo bar"        # 正確なフレーズマッチング。連続して出現する必要がある
foo\ bar         # スペースをエスケープし、"foo bar" という全体にマッチ

2. ワイルドカード¶

foo*             # foo で始まる内容にマッチ
foo?bar          # ? は1文字にマッチ
"foo*bar"        # 引用符内のワイルドカードは解釈されず、リテラルとしてマッチ

3. 正規表現¶

/foo.*bar/       # スラッシュで囲まれた正規表現
/joh?n(ath[oa]n)/  # 複雑な正規表現

4. ブール演算子¶

foo AND bar      # 論理積。両方とも含まれている必要がある
foo OR bar       # 論理和。少なくとも1つ含まれている
NOT foo          # 論理否定。foo を含まない

# 短縮形
foo && bar       # foo AND bar と同等
foo || bar       # foo OR bar と同等
!foo             # NOT foo と同等

5. グループ化¶

(foo OR bar) AND baz       # 括弧を使用して優先順位を変更
!(status 429 reading)      # 式全体を否定

6. デフォルト演算子¶

スペースで区切られた複数の語句は、デフォルトで OR で結合されます（AND に設定可能）。

foo bar          # foo OR bar と同等

7. トークン化ルール¶

queryString 関数の具体的な動作は、現在のワークスペースで使用されている基盤となるストレージエンジンによって異なります。

• ScopeDB 環境：queryString は大文字と小文字を区別しない包含検索を実行します。つまり、フィールド値にクエリ文字列の任意の部分文字列が含まれているかどうかをマッチングします。トークン化は伴いません。
• Doris 環境：queryString は全文インデックスのトークン化に基づいてマッチングを行います。そのセマンティクスはトークン化の結果に直接関連します。Doris が使用するトークナイザーは、Unicode Standard Annex #29 のデフォルトの単語境界仕様 に従います。

例¶

// 単純な語句マッチング
L::logs:(message) {query_string("error timeout")} [1h]

// ブール組み合わせ
L::logs:(message) {query_string("error AND NOT timeout")} [1h]

// 正規表現
L::logs:(message) {query_string("/ERR-\d{4}/")} [1h]

// 複雑なクエリ
L::logs:(message) {query_string("(error OR warn) AND service")} [1h]

// フィールドの指定
L::logs:(*) {query_string(message, "error AND timeout")} [1h]

// 日本語クエリ
L::logs:(message) {query_string("エラー AND タイムアウト")} [1h]

外側関数¶

使用上の推奨： 外側関数はレガシーな設計です。Rollup + 集約関数（例：[rate]、[last]、[increase] など）で解決できるシナリオでは、Rollup の方法を優先的に使用してください。外側関数は、Rollup が適用できないシナリオでのみ使用してください（例：集約結果に対して二次計算を行う必要がある場合）。dbscan、forecast など、完全なクエリ結果を必要とする中心検出/予測関数には、同等の Rollup 記述がないため、外側関数として使用します。

外側関数は、DQL クエリ結果全体に作用し、クエリ出力の時系列データに対して二次計算を行います。外側関数は、DQL 式全体をラップし、Select 句の内部には記述しません。

クエリ内関数と外側関数¶

• クエリ内関数：DQL 式の内部で使用されます。例：sum、avg、max など。
• 外側関数：DQL クエリ結果全体をラップし、出力された時系列を後処理します。

記述方法の比較：

// Rollup（時間句）：各時系列で増加率を計算してから集約
M::http_requests:(sum(request_count)) [rate] BY service

// 外側関数：クエリ結果を取得してから二次計算
rate(M::http_requests:(sum(request_count)) [1h::1m] BY service)

構文：

outer_function(DQL_expression)

例：

// クエリ内関数：元のデータの平均を計算
M::cpu:(avg(usage)) [1h::5m] BY host

// 外側関数：クエリ結果に対して移動平均を計算
moving_average(M::cpu:(avg(usage)) [1h::5m] BY host, 5)

累積計算¶

cumsum¶

累積和を計算します。時系列の各ポイントで、それ以前のすべてのポイントの累積値を計算します。

構文：

cumsum(DQL_expression)

例：

// 累積リクエスト数を計算
cumsum(M::requests:(sum(count)) [1h::5m] BY service)

差と導関数¶

推奨： これらの関数は、Rollup 関数として優先的に使用してください（例：[rate]、[deriv]）。外側関数形式は、集約結果に対する二次計算にのみ使用してください。

以下の関数は、外側関数として使用できます。

例：

// 外側関数：クエリ結果に対して導関数を計算
derivative(M::cpu:(avg(usage)) [1h::5m] BY host)

// 推奨：Rollup 方式を使用
M::cpu:(deriv(usage)) [1h::5m:last] BY host

移動計算¶

moving_average¶

クエリ結果に対して移動平均を計算します。

推奨： Rollup 方式の moving_average(field, n) を優先的に使用してください。外側関数形式は、集約結果に対する二次平滑化にのみ使用してください。

構文：

moving_average(DQL_expression, n)

パラメータ：

• DQL_expression: DQL クエリ式
• n: ウィンドウサイズ（データポイント数）

例：

// 外側関数：クエリ結果に対して移動平均を計算
moving_average(M::cpu:(avg(usage)) [1h::1m] BY host, 5)

// 推奨：Rollup 方式を使用
M::cpu:(moving_average(usage, 5)) [1h::1m] BY host

時系列分析と異常検知¶

dbscan¶

クエリ結果の数値時系列に対して DBSCAN 外れ値検出を実行し、数値型の異常マークを出力します。

構文：

dbscan(DQL_expression)
dbscan(DQL_expression, eps)

パラメータ：

• DQL_expression: DQL クエリ式。通常は、時間ウィンドウと BY グループ化を持つ複数系列のクエリ結果に使用されます。
• eps: 近傍距離しきい値。オプション。デフォルトは 0.5、範囲は (0, 3.0] です。

戻り値：

• 各数値列に対して、対応する dbscan(column) 数値列を出力します。
• 1 は外れ値ポイント、0 は非外れ値ポイントを示します。
• 有効な数値ポイントが5つ未満の場合は空の値を返し、サンプル不足で検出が実行されなかったことを示します。

説明：

• 少なくとも5つの有効な数値ポイントが必要です。有効なポイントが不足している場合は空の値を返します。
• 現在の実装では、入力テーブルの各数値列に対して個別に1次元 DBSCAN を実行し、時間列を保持します。

例：

// デフォルトの eps=0.5 を使用して CPU 使用率の外れ値を検出
dbscan(M::cpu:(avg(usage)) [1h::5m] BY host)

// eps を明示的に指定
dbscan(M::cpu:(avg(usage)) [1h::5m] BY host, 0.8)

forecast¶

クエリ結果の数値時系列に対して線形トレンド予測を実行し、将来の時点の予測値を出力します。

構文：

forecast(DQL_expression)
forecast(DQL_expression, steps)

パラメータ：

• DQL_expression: DQL クエリ式
• steps: 予測ステップ数。オプション。デフォルトは 5。正の整数である必要があります。

戻り値：

• 将来の steps 時点を出力します。
• 各数値列は、対応する forecast(column) 数値列を出力します。
• 非数値列は予測に参加しません。

説明：

• 現在の実装では、線形トレンド予測を使用します。
• 有効な数値ポイントが2つ未満の場合は空の値を返します。

例：

// 将来の5時点を予測
forecast(M::cpu:(avg(usage)) [1h::5m] BY host)

// 将来の3時点を予測
forecast(M::cpu:(avg(usage)) [1h::5m] BY host, 3)

TopN¶

top / bottom¶

推奨： Rollup 方式の top(field, n) または bottom(field, n) を優先的に使用してください。外側関数形式は、集約結果に対する二次フィルタリングにのみ使用してください。

クエリ結果から TopN または BottomN を取得します。

構文：

top(DQL_expression, n)
bottom(DQL_expression, n)

例：

// 外側関数：クエリ結果から TopN を取得
top(M::response_time:(max(duration)) [1h::5m] BY service, 5)

// 推奨：Rollup 方式を使用
M::response_time:(top(duration, 5)) [1h::5m] BY service

NULL 値補完¶

fill¶

クエリ結果の NULL 値を補完します。

詳細については、fill 関数 を参照してください。

例：

// NULL 値を0で補完
fill(M::cpu:(avg(usage)) [1h::5m] BY host, 0)

// 線形補間で補完
fill(M::cpu:(avg(usage)) [1h::5m] BY host, LINEAR)

その他の外側関数¶

以下の関数も外側関数として使用できます。

組み合わせて使用¶

外側関数は組み合わせて使用できます。

// 移動平均を計算してから四捨五入
round(moving_average(M::cpu:(avg(usage)) [1h::1m] BY host, 5))

// 増加率の移動平均を計算
moving_average(rate(M::requests:(sum(count)) [1h::5m] BY service), 3)

eval 式計算¶

eval は特別な関数であり、クエリの外部で式計算を実行できます。複数のサブクエリの結果を参照して組み合わせ演算を行うことができます。

構文¶

eval(expression, name1=(query1), name2=(query2), ..., alias="result_name")

パラメータ：

• expression: 数式。name.field を使用してサブクエリ結果を参照します。
• name=(query): 名前付きサブクエリ。
• alias: 結果のエイリアス（オプション）。

説明：eval は name="query" という過去の記法も互換性がありますが、型表現と可読性の観点から、name=(query) を使用することを推奨します。

動作原理¶

1. すべての名前付きサブクエリを実行します。
2. 各サブクエリの結果を時間で整列させます。
3. 各時点で式を計算します。
4. 計算結果を返します。

適用シナリオ¶

• 複数のメトリクスの比率を計算する（例：エラー率、使用率）。
• 異なる期間のメトリクスを比較する。
• 複数のデータソースの計算結果を組み合わせる。

例¶

エラー率の計算¶

// エラー率 = エラー数 / 総リクエスト数 * 100 を計算
eval(a / b * 100,
     a=(M::http:(sum(error_count)) [1h] BY service),
     b=(M::http:(sum(request_count)) [1h] BY service),
     alias="error_rate")

CPU 使用率の計算¶

// 使用率 = used / total * 100
eval(used / total * 100,
     used=(M::memory:(sum(used_bytes)) [1h] BY host),
     total=(M::memory:(sum(total_bytes)) [1h] BY host),
     alias="memory_usage_percent")

ベースライン比較増加率の計算¶

// 現在値のベースライン値に対する増加率を計算
eval(current / baseline - 1,
     current=(M::sales_current:(sum(amount)) [7d]),
     baseline=(M::sales_baseline:(sum(amount)) [7d]),
     alias="growth_rate")

サブクエリのフィールドを参照¶

// サブクエリの特定のフィールドを参照
eval(a.usage / b.total * 100,
     a=(M::cpu:(avg(usage) as usage) [1h] BY host),
     b=(M::cpu:(avg(total) as total) [1h] BY host),
     alias="cpu_percent")

注意事項¶

• すべてのサブクエリの時間ウィンドウは互換性がある必要があります。
• サブクエリのグループ化ディメンションは一貫している必要があります。
• 式で参照されるフィールド名は name.field 形式を使用します。
• サブクエリが1つだけの場合は、フィールド名を直接使用できます。

その他の関数¶

fill¶

クエリ結果の NULL 値を指定された値で補完します。

推奨される使用方法： fill は外側関数として使用し、クエリ結果全体に作用させることをお勧めします。

fill(M::cpu:(avg(usage)) [1h::5m] BY host, 0)

Select 句でも fill(avg(usage), 0) という記述が可能ですが、fill は実際には集約完了後に結果を補完するため、外側関数形式の方がその動作メカニズムに適しています。

構文（外側関数）：

fill(DQL_expression, value)
fill(DQL_expression, LINEAR)
fill(DQL_expression, PREVIOUS)

パラメータ：

• DQL_expression: DQL クエリ式
• value: 補完値。複数のモードをサポートします。
• 具体的な値：数値、文字列、null
• LINEAR：線形補間
• PREVIOUS：前の非NULL値を補完

例：

// 推奨：外側関数として使用
fill(M::cpu:(avg(usage)) [1h::5m] BY host, 0)

// 線形補間で補完
fill(M::cpu:(avg(usage)) [1h::5m] BY host, LINEAR)

// 前の値で補完
fill(M::cpu:(avg(usage)) [1h::5m] BY host, PREVIOUS)

now¶

現在のタイムスタンプ（ミリ秒）を返します。

構文：

now()

例：

// 最近更新されたデータをクエリ
O::HOST:(*) {last_update_time > now() - 600000}  // 10分以内に更新

unwrap¶

集約結果のラップを展開します。

構文：

unwrap(field)

例：

// 集約後のフィールドを展開
M::cpu:(unwrap(usage)) [1h] BY host

Show 関数¶

Show 関数は、メタデータ（measurement、tag、field、カーディナリティ、シリーズカウントなど）を表示するために使用されます。モデリングの調査やクエリ前のプロービングによく使用されます。

共通構文¶

show_xxx(arg1=..., arg2=...){ where_conditions } [time_window] LIMIT n OFFSET m

• where、time_window、LIMIT、OFFSET はすべてオプションです。
• LIMIT/OFFSET は負の数にできません。

M 名前空間の組み込み Show 関数¶

カーディナリティ関連の関数は、内部的に HyperLogLog マージを使用しており、戻り値は推定値です。

非 M 名前空間の Show 関数（サフィックスモード）¶

非 M 名前空間の場合、以下のサフィックスモードをサポートします。

• show_<namespace>_source
• show_<namespace>_class
• show_<namespace>_type
• show_<namespace>_field
• show_<namespace>_label

ここで、<namespace> は関数名の中間セグメントから自動的にマッピングされます。例えば、以下のようになります。

• show_logging_source -> L
• show_tracing_field -> T
• show_object_source -> O

一般的な例：

show_logging_source()
show_tracing_field('mysql')
show_logging_field('*')
show_logging_label(name='env')
show_logging_label(names=['env', 'team'])

パラメータと動作の説明¶

• from：measurement のリスト。文字列または文字列の配列をサポートします。
• keyin：tag key のリスト。文字列または文字列の配列をサポートします。
• field：field のリスト。文字列または文字列の配列をサポートします（メトリック show のフィールドフィルタリングに使用）。
• show_*_field の場合：
• 無名パラメータ（例：'mysql'）は通常、source フィルタとして使用されます。
• '*' は source を指定しないことと同等です。
• 名前付きパラメータは where フィルタ条件に変換されます。
• show_*_label の場合：
• 名前付きパラメータが必要です。names は name のエイリアスとして扱われます。

制約と注意事項¶

• show_tag_value と show_tag_value_cardinality には keyin を指定する必要があります。
• show_series_count_by_tag_value には keyin を指定する必要があります。
• show_series_count_by_* には from を指定するか、where 句で同等の source 制約（例：@__source__ 条件）を指定する必要があります。
• show_<namespace>_source、show_<namespace>_class、show_<namespace>_type は現在、同じ実行パスを共有し、source の重複排除リストを返します。
• 現在、パーサーは show_<namespace>_index 構文をサポートしていません（実行レイヤーに対応するブランチが存在する場合でも）。
• Query API で show の時間範囲が指定されていない場合、一部のログ show クエリは直近30分のウィンドウにフォールバックして実行されます。

戻り値の例¶

以下の例は、典型的な列構造とサンプル行のみを示しています。実際の結果は、テナントデータ、フィルタ条件、時間範囲、および LIMIT/OFFSET によって異なります。

関数分類クイックリファレンス¶

基本集約¶

統計集約¶

時系列分析集約¶

フィルタリング集約¶

ヒストグラム関数¶

集合関数¶

補助関数¶

時系列関数¶

Rollup 関数¶

変換関数¶

マッチング関数¶

外側関数¶

式計算¶