関数と演算子（Functions and operators）

ES|QL 関数と演算子

ES|QL はデータを操作するための包括的な関数と演算子のセットを提供します。リファレンスドキュメントは以下のカテゴリに分かれています：

関数の概要

集約関数

• AVG
• COUNT
• COUNT_DISTINCT
• MAX
• MEDIAN
• MEDIAN_ABSOLUTE_DEVIATION
• MIN
• PERCENTILE
• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elastic は問題を修正するために取り組みますが、技術プレビューの機能は公式 GA 機能のサポート SLA の対象外です。 ST_CENTROID_AGG
• SUM
• TOP
• VALUES
• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elastic は問題を修正するために取り組みますが、技術プレビューの機能は公式 GA 機能のサポート SLA の対象外です。 WEIGHTED_AVG

グループ化関数

• BUCKET

条件付き関数と式

• CASE
• COALESCE
• GREATEST
• LEAST

日付と時間の関数

• DATE_DIFF
• DATE_EXTRACT
• DATE_FORMAT
• DATE_PARSE
• DATE_TRUNC
• NOW

IP 関数

• CIDR_MATCH
• IP_PREFIX

数学関数

• ABS
• ACOS
• ASIN
• ATAN
• ATAN2
• CBRT
• CEIL
• COS
• COSH
• E
• FLOOR
• LOG
• LOG10
• PI
• POW
• ROUND
• SIGNUM
• SIN
• SINH
• SQRT
• TAN
• TANH
• TAU

空間関数

• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elastic は問題を修正するために取り組みますが、技術プレビューの機能は公式 GA 機能のサポート SLA の対象外です。 ST_INTERSECTS
• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elastic は問題を修正するために取り組みますが、技術プレビューの機能は公式 GA 機能のサポート SLA の対象外です。 ST_DISJOINT
• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elastic は問題を修正するために取り組みますが、技術プレビューの機能は公式 GA 機能のサポート SLA の対象外です。 ST_CONTAINS
• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elastic は問題を修正するために取り組みますが、技術プレビューの機能は公式 GA 機能のサポート SLA の対象外です。 ST_WITHIN
• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elastic は問題を修正するために取り組みますが、技術プレビューの機能は公式 GA 機能のサポート SLA の対象外です。 ST_X
• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elastic は問題を修正するために取り組みますが、技術プレビューの機能は公式 GA 機能のサポート SLA の対象外です。 ST_Y
• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elastic は問題を修正するために取り組みますが、技術プレビューの機能は公式 GA 機能のサポート SLA の対象外です。 ST_DISTANCE

文字列関数

• CONCAT
• ENDS_WITH
• FROM_BASE64
• LEFT
• LENGTH
• LOCATE
• LTRIM
• REPEAT
• REPLACE
• RIGHT
• RTRIM
• SPLIT
• STARTS_WITH
• SUBSTRING
• TO_BASE64
• TO_LOWER
• TO_UPPER
• TRIM

型変換関数

• TO_BOOLEAN
• TO_CARTESIANPOINT
• TO_CARTESIANSHAPE
• TO_DATETIME
• TO_DEGREES
• TO_DOUBLE
• TO_GEOPOINT
• TO_GEOSHAPE
• TO_INTEGER
• TO_IP
• TO_LONG
• TO_RADIANS
• TO_STRING
• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elastic は問題を修正するために取り組みますが、技術プレビューの機能は公式 GA 機能のサポート SLA の対象外です。 TO_UNSIGNED_LONG
• TO_VERSION

マルチバリュー関数

• MV_APPEND
• MV_AVG
• MV_CONCAT
• MV_COUNT
• MV_DEDUPE
• MV_FIRST
• MV_LAST
• MV_MAX
• MV_MEDIAN
• MV_MIN
• MV_SORT
• MV_SLICE
• MV_SUM
• MV_ZIP

演算子の概要

演算子

• バイナリ演算子
• 単項演算子
• 論理演算子
• IS NULL と IS NOT NULL の述語
• Cast (::)
• IN
• LIKE
• RLIKE

ES|QL 集約関数

STATS ... BY コマンドは次の集約関数をサポートしています：

• AVG
• COUNT
• COUNT_DISTINCT
• MAX
• MEDIAN
• MEDIAN_ABSOLUTE_DEVIATION
• MIN
• PERCENTILE
• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elastic は問題を修正するために取り組みますが、技術プレビューの機能は公式 GA 機能のサポート SLA の対象外です。 ST_CENTROID_AGG
• SUM
• TOP
• VALUES
• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elastic は問題を修正するために取り組みますが、技術プレビューの機能は公式 GA 機能のサポート SLA の対象外です。 WEIGHTED_AVG

AVG

構文

Esql

AVG(expression)

• expression
• 数値式。

説明

数値式の平均。

サポートされる型

結果は常に double であり、入力型に関係ありません。

例

Esql

FROM employees
| STATS AVG(height)

この式はインライン関数を使用できます。たとえば、マルチバリュー列の平均を計算するには、まず MV_AVG を使用して行ごとの複数の値の平均を計算し、その結果を AVG 関数と共に使用します：

Esql

FROM employees
| STATS avg_salary_change = ROUND(AVG(MV_AVG(salary_change)), 10)

COUNT

構文

Esql

COUNT([expression])

パラメータ

• expression
• カウントされる値を出力する式。省略した場合、COUNT(*)（行数）と同等です。

説明

入力値の合計数（カウント）を返します。

サポートされる型

任意のフィールド型を入力として受け取ることができます。

例

Esql

FROM employees
| STATS COUNT(height)

行数をカウントするには、COUNT() または COUNT(*) を使用します：

Esql

FROM employees
| STATS count = COUNT(*) BY languages
| SORT languages DESC

この式はインライン関数を使用できます。この例では、SPLIT 関数を使用して文字列を複数の値に分割し、その値をカウントします：

Esql

ROW words="foo;bar;baz;qux;quux;foo"
| STATS word_count = COUNT(SPLIT(words, ";"))

COUNT_DISTINCT

構文

Esql

COUNT_DISTINCT(expression[, precision_threshold])

パラメータ

• expression
• 一意のカウントを実行する値を出力する式。
• precision_threshold
• 精度の閾値。カウントは近似値ですを参照してください。サポートされる最大値は 40000 です。この数値を超える閾値は、40000 の閾値と同じ効果を持ちます。デフォルト値は 3000 です。

説明

近似的な一意の値の数を返します。

サポートされる型

任意のフィールド型を入力として受け取ることができます。

例

Esql

FROM hosts
| STATS COUNT_DISTINCT(ip0), COUNT_DISTINCT(ip1)

オプションの第二パラメータを使用して精度の閾値を設定します：

Esql

FROM hosts
| STATS COUNT_DISTINCT(ip0, 80000), COUNT_DISTINCT(ip1, 5)

この式はインライン関数を使用できます。この例では、SPLIT 関数を使用して文字列を複数の値に分割し、一意の値をカウントします：

Esql

ROW words="foo;bar;baz;qux;quux;foo"
| STATS distinct_word_count = COUNT_DISTINCT(SPLIT(words, ";"))

カウントは近似値です

正確なカウントを計算するには、値をセットに読み込み、そのサイズを返す必要があります。これは、高カーディナリティのセットや大きな値を扱う場合にはスケールしません。必要なメモリ使用量と、ノード間でそれらのシャードごとのセットを通信する必要があるため、クラスターのリソースを過剰に使用します。

この COUNT_DISTINCT 関数は、HyperLogLog++ アルゴリズムに基づいており、値のハッシュに基づいてカウントを行い、いくつかの興味深い特性を持っています：

• 設定可能な精度、メモリと精度のトレードオフを決定します、
• 低カーディナリティのセットに対して優れた精度、
• 固定メモリ使用量：ユニークな値が数十または数十億であっても、メモリ使用量は設定された精度のみに依存します。

c の精度の閾値の場合、私たちが使用している実装は約 c * 8 バイトを必要とします。

以下のチャートは、閾値の前後でエラーがどのように変化するかを示しています：

すべての 3 つの閾値に対して、カウントは設定された閾値まで正確でした。保証はされていませんが、これはその可能性が高いです。実際の精度は、問題のデータセットに依存します。一般的に、ほとんどのデータセットは一貫して良好な精度を示します。また、閾値が 100 のように低くても、エラーは非常に低く（上記のグラフで見られるように 1-6%）、数百万のアイテムをカウントする場合でも同様です。

HyperLogLog++ アルゴリズムは、ハッシュ値の先頭のゼロに依存しており、データセット内のハッシュの正確な分布がカーディナリティの精度に影響を与える可能性があります。

COUNT_DISTINCT 関数は、精度の閾値を設定するためのオプションの第二パラメータを受け取ります。precision_threshold オプションは、メモリと精度のトレードオフを可能にし、カウントが正確に近いと期待される一意のカウントを定義します。この値を超えると、カウントは少しあいまいになる可能性があります。サポートされる最大値は 40000 であり、この数値を超える閾値は 40000 の閾値と同じ効果を持ちます。デフォルト値は 3000 です。

MAX

構文

Esql

MAX(expression)

パラメータ

• expression
• 最大値を返す式。

説明

数値式の最大値を返します。

例

Esql

FROM employees
| STATS MAX(languages)

この式はインライン関数を使用できます。たとえば、マルチバリュー列の平均の最大値を計算するには、MV_AVG を使用して行ごとの複数の値の平均を計算し、その結果を MAX 関数と共に使用します：

Esql

FROM employees
| STATS max_avg_salary_change = MAX(MV_AVG(salary_change))

MEDIAN

構文

Esql

MEDIAN(expression)

パラメータ

• expression
• 中央値を返す式。

説明

すべての値の半分より大きく、すべての値の半分より小さい値を返します。これは 50% PERCENTILE としても知られています。

PERCENTILE と同様に、MEDIAN は 通常近似値 です。

MEDIAN も 非決定的 です。これは、同じデータを使用してもわずかに異なる結果が得られることを意味します。

例

Esql

FROM employees
| STATS MEDIAN(salary), PERCENTILE(salary, 50)

この式はインライン関数を使用できます。たとえば、マルチバリュー列の最大値の中央値を計算するには、まず MV_MAX を使用して行ごとの最大値を取得し、その結果を MEDIAN 関数と共に使用します：

Esql

FROM employees
| STATS median_max_salary_change = MEDIAN(MV_MAX(salary_change))

MEDIAN_ABSOLUTE_DEVIATION

構文

Esql

MEDIAN_ABSOLUTE_DEVIATION(expression)

パラメータ

• expression
• 中位数絶対偏差を返すための式。

説明

中位数絶対偏差を返します。これは変動性の指標です。ロバストな統計量であり、外れ値があるか、正規分布していないデータを記述するのに役立ちます。このようなデータに対しては、標準偏差よりも説明的であることがあります。

これは、各データポイントの中央値からの偏差の中央値として計算されます。すなわち、ランダム変数 X に対して、中位数絶対偏差は median(|median(X) - X|) です。

PERCENTILE のように、MEDIAN_ABSOLUTE_DEVIATION は 通常近似的 です。

MEDIAN_ABSOLUTE_DEVIATION は 非決定的 でもあります。これは、同じデータを使用してもわずかに異なる結果が得られることを意味します。

例

Esql

FROM employees
| STATS MEDIAN(salary), MEDIAN_ABSOLUTE_DEVIATION(salary)

式はインライン関数を使用できます。たとえば、多値列の最大値の中位数絶対偏差を計算するには、まず MV_MAX を使用して行ごとの最大値を取得し、その結果を MEDIAN_ABSOLUTE_DEVIATION 関数と共に使用します:

Esql

FROM employees
| STATS m_a_d_max_salary_change = MEDIAN_ABSOLUTE_DEVIATION(MV_MAX(salary_change))

MIN

構文

Esql

MIN(expression)

パラメータ

• expression
• 最小値を返すための式。

説明

数値式の最小値を返します。

例

Esql

FROM employees
| STATS MIN(languages)

式はインライン関数を使用できます。たとえば、多値列の平均の最小値を計算するには、まず MV_AVG を使用して行ごとの複数の値の平均を計算し、その結果を MIN 関数と共に使用します:

Esql

FROM employees
| STATS min_avg_salary_change = MIN(MV_AVG(salary_change))

PERCENTILE

構文

Esql

PERCENTILE(expression, percentile)

パラメータ

• expression
• パーセンタイルを返すための式。
• percentile
• 定数数値式。

説明

観測された値の特定の割合が発生する値を返します。たとえば、95パーセンタイルは観測された値の95％より大きい値であり、50パーセンタイルは MEDIAN です。

例

Esql

FROM employees
| STATS p0 = PERCENTILE(salary,  0)
   , p50 = PERCENTILE(salary, 50)
   , p99 = PERCENTILE(salary, 99)

式はインライン関数を使用できます。たとえば、多値列の最大値のパーセンタイルを計算するには、まず MV_MAX を使用して行ごとの最大値を取得し、その結果を PERCENTILE 関数と共に使用します:

Esql

FROM employees
| STATS p80_max_salary_change = PERCENTILE(MV_MAX(salary_change), 80)

PERCENTILE is (usually) approximate

パーセンタイルを計算するためのさまざまなアルゴリズムがあります。単純な実装は、すべての値をソートされた配列に保存します。50パーセンタイルを見つけるには、my_array[count(my_array) * 0.5] にある値を見つけるだけです。

明らかに、単純な実装はスケールしません。ソートされた配列は、データセット内の値の数に対して線形に成長します。Elasticsearchクラスター内の数十億の値にわたってパーセンタイルを計算するために、近似パーセンタイルが計算されます。

percentile メトリクスで使用されるアルゴリズムは、TDigest（Computing Accurate Quantiles using T-DigestsでTed Dunningによって導入されました）と呼ばれます。

このメトリクスを使用する際には、いくつかのガイドラインを考慮する必要があります：

• 精度は q(1-q) に比例します。これは、極端なパーセンタイル（例：99％）が中央値などのあまり極端でないパーセンタイルよりも正確であることを意味します。
• 小さな値のセットでは、パーセンタイルは非常に正確です（データが十分に小さい場合、潜在的に100％正確です）。
• バケット内の値の量が増えるにつれて、アルゴリズムはパーセンタイルを近似し始めます。これは、精度をメモリの節約と引き換えにしていることを意味します。正確な不正確さのレベルは一般化するのが難しいです。なぜなら、それはデータ分布と集約されるデータの量に依存するからです。

次のチャートは、収集された値の数と要求されたパーセンタイルに応じた均一分布の相対誤差を示しています：

これは、精度が極端なパーセンタイルに対してより良いことを示しています。多くの値に対して誤差が減少する理由は、大数の法則が値の分布をますます均一にし、t-digestツリーがそれを要約するのにより良い仕事をするからです。より歪んだ分布ではそうではありません。

PERCENTILE は 非決定的 でもあります。これは、同じデータを使用してもわずかに異なる結果が得られることを意味します。

ST_CENTROID_AGG

この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elasticは問題を修正するために取り組みますが、技術プレビューの機能は公式GA機能のサポートSLAの対象ではありません。

空間ポイントジオメトリタイプのフィールドに対して空間セントロイドを計算します。

Esql

FROM airports
| STATS centroid=ST_CENTROID_AGG(location)

サポートされているタイプ:

SUM

構文

Esql

SUM(expression)

• expression
• 数値式。

説明

数値式の合計を返します。

例

Esql

FROM employees
| STATS SUM(languages)

式はインライン関数を使用できます。たとえば、各従業員の最大給与の変化の合計を計算するには、MV_MAX 関数を各行に適用し、その後結果を合計します:

Esql

FROM employees
| STATS total_salary_changes = SUM(MV_MAX(salary_change))

TOP

構文

パラメータ

• field
• トップ値を収集するフィールド。
• limit
• 収集する最大値の数。
• order
• トップ値を計算する順序。 asc または desc のいずれか。

説明

フィールドのトップ値を収集します。繰り返し値を含みます。

サポートされる型

例

Esql

FROM employees
| STATS top_salaries = TOP(salary, 3, "desc"), top_salary = MAX(salary)

VALUES

本番環境で VALUES を使用しないでください。この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elastic は問題を修正するために取り組みますが、技術プレビューの機能は公式 GA 機能のサポート SLA の対象ではありません。

構文

Esql

VALUES(expression)

• expression
• geo_point、cartesian_point、geo_shape、または cartesian_shape 以外の任意の型の式。

説明

グループ内のすべての値を多値フィールドとして返します。返される値の順序は保証されません。順序で返される値が必要な場合は、MV_SORT を使用してください。

これはかなりのメモリを使用する可能性があり、ES|QL はまだメモリを超えて集計を成長させません。したがって、この集計は、メモリに収まる以上の値を収集するために使用されるまで機能します。あまりにも多くの値を収集すると、サーキットブレイカーエラー でクエリが失敗します。

例

Esql

FROM employees
| EVAL first_letter = SUBSTRING(first_name, 0, 1)
| STATS first_name=MV_SORT(VALUES(first_name)) BY first_letter
| SORT first_letter

WEIGHTED_AVG

構文

Esql

WEIGHTED_AVG(expression, weight)

• expression
• 数値式。
• weight
• 数値の重み。

説明

数値式の加重平均。

サポートされる型

結果は常に double であり、入力型に関係ありません。

例

Esql

FROM employees
| STATS w_avg = WEIGHTED_AVG(salary, height) by languages
| EVAL w_avg = ROUND(w_avg)
| KEEP w_avg, languages
| SORT languages

ES|QL grouping functions

STATS ... BY コマンドは、これらのグループ化関数をサポートしています:

• BUCKET

BUCKET

構文

パラメータ

• field
• バケットを導出するための数値または日付の式。
• buckets
• バケットの目標数。
• from
• 範囲の開始。数値または文字列として表現された日付である可能性があります。
• to
• 範囲の終了。数値または文字列として表現された日付である可能性があります。

説明

日付時刻または数値入力から値のグループ - バケット - を作成します。バケットのサイズは、直接提供するか、推奨されるカウントと値の範囲に基づいて選択できます。

サポートされる型

例

BUCKET は二つのモードで動作できます: 一つはバケットのサイズがバケット数の推奨に基づいて計算されるモード（四つのパラメータ）で、もう一つはバケットサイズが直接提供されるモード（二つのパラメータ）です。

目標バケット数、範囲の開始、範囲の終了を使用して、BUCKET は目標バケット数またはそれ以下の適切なバケットサイズを選択します。たとえば、1年で最大20のバケットを要求すると、月ごとのバケットが得られます:

Esql

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS hire_date = MV_SORT(VALUES(hire_date)) BY month = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
| SORT hire_date

目標は、正確に目標バケット数を提供することではなく、人々が快適に感じる範囲を選択し、最大で目標バケット数を提供することです。

[BUCKET] と 集計 を組み合わせてヒストグラムを作成します:

Esql

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS hires_per_month = COUNT(*) BY month = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
| SORT month

BUCKET は、ドキュメントに一致しないバケットを作成しません。これが、この例で 1985-03-01 や他の日付が欠落している理由です。

より多くのバケットを要求すると、より小さな範囲になる可能性があります。たとえば、1年で最大100のバケットを要求すると、週ごとのバケットが得られます:

Esql

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 100, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
| SORT week

BUCKET は、行をフィルタリングしません。提供された範囲を使用して適切なバケットサイズを選択するだけです。範囲外の値を持つ行には、範囲外のバケットに対応するバケット値が返されます。BUCKET を WHERE と組み合わせて行をフィルタリングします。

希望するバケットサイズが事前にわかっている場合は、単にそれを第二引数として提供し、範囲を省略します:

Esql

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 1 week)
| SORT week

バケットサイズを第二引数として提供する場合、それは時間の長さまたは日付の期間でなければなりません。

BUCKET は数値フィールドでも動作できます。たとえば、給与のヒストグラムを作成するには:

Esql

FROM employees
| STATS COUNT(*) by bs = BUCKET(salary, 20, 25324, 74999)
| SORT bs

以前の例とは異なり、日付範囲で意図的にフィルタリングすることはほとんどありません。数値範囲でフィルタリングする必要があります。min と max を別々に見つける必要があります。ES|QL には、まだ自動的にそれを行う簡単な方法がありません。

希望するバケットサイズが事前にわかっている場合は、単にそれを第二引数として提供します:

Esql

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS c = COUNT(1) BY b = BUCKET(salary, 5000.)
| SORT b

バケットサイズを第二引数として提供する場合、それは浮動小数点型でなければなりません。

過去24時間の時間ごとのバケットを作成し、時間ごとのイベント数を計算します:

Esql

FROM sample_data
| WHERE @timestamp >= NOW() - 1 day and @timestamp < NOW()
| STATS COUNT(*) BY bucket = BUCKET(@timestamp, 25, NOW() - 1 day, NOW())

1985年の月ごとのバケットを作成し、採用月ごとの平均給与を計算します

Esql

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS AVG(salary) BY bucket = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
| SORT bucket

BUCKET は、BUCKET コマンドの集計部分とグループ化部分の両方で使用できます。ただし、集計部分では、関数がグループ化部分で定義されたエイリアスによって参照されるか、正確に同じ式で呼び出される必要があります:

Esql

FROM employees
| STATS s1 = b1 + 1, s2 = BUCKET(salary / 1000 + 999, 50.) + 2 BY b1 = BUCKET(salary / 100 + 99, 50.), b2 = BUCKET(salary / 1000 + 999, 50.)
| SORT b1, b2
| KEEP s1, b1, s2, b2

ES|QL conditional functions and expressions

条件関数は、if-else の方法で評価することによって引数の一つを返します。ES|QL はこれらの条件関数をサポートしています:

• CASE
• COALESCE
• GREATEST
• LEAST

CASE

構文

パラメータ

• condition
• 条件。
• trueValue
• 対応する条件が最初に true に評価されるときに返される値。条件が一致しない場合はデフォルト値が返されます。

説明

条件と値のペアを受け入れます。この関数は、最初に true に評価される条件に属する値を返します。引数の数が奇数の場合、最後の引数はデフォルト値であり、条件が一致しない場合に返されます。引数の数が偶数で、条件が一致しない場合、関数は null を返します。

サポートされる型

例

従業員が単言語話者、バイリンガル、または多言語話者であるかどうかを判断します:

Esql

FROM employees
| EVAL type = CASE(
   languages <= 1, "monolingual",
   languages <= 2, "bilingual",
   "polyglot")
| KEEP emp_no, languages, type

ログメッセージに基づいて接続成功率の合計を計算します:

Esql

FROM sample_data
| EVAL successful = CASE(
   STARTS_WITH(message, "Connected to"), 1,
   message == "Connection error", 0
  )
| STATS success_rate = AVG(successful)

ログメッセージの総数に対する時間ごとのエラー率を計算します:

Esql

FROM sample_data
| EVAL error = CASE(message LIKE "*error*", 1, 0)
| EVAL hour = DATE_TRUNC(1 hour, @timestamp)
| STATS error_rate = AVG(error) by hour
| SORT hour

COALESCE

構文

パラメータ

• first
• 評価する式。
• rest
• 評価する他の式。

説明

最初の引数が null でないものを返します。すべての引数が null の場合、null を返します。

サポートされる型

例

Esql

ROW a=null, b="b"
| EVAL COALESCE(a, b)

ES|QL 関数と演算子

ES|QL はデータを操作するための包括的な関数と演算子のセットを提供します。リファレンスドキュメントは以下のカテゴリに分かれています：

Esql

ROW a = 10, b = 20
| EVAL g = GREATEST(a, b)

LEAST

構文

パラメータ

• first
• 評価する最初の列。
• rest
• 評価する残りの列。

説明

複数の列から最小値を返します。これはMV_MINに似ていますが、複数の列を同時に実行することを目的としています。

サポートされる型

例

Esql

ROW a = 10, b = 20
| EVAL l = LEAST(a, b)

ES|QL date-time functions

ES|QLは次の日時関数をサポートしています:

• DATE_DIFF
• DATE_EXTRACT
• DATE_FORMAT
• DATE_PARSE
• DATE_TRUNC
• NOW

DATE_DIFF

構文

パラメータ

• unit
• 時間差の単位
• startTimestamp
• 開始タイムスタンプを表す文字列
• endTimestamp
• 終了タイムスタンプを表す文字列

説明

| 日付時刻の差の単位 |
| :-: |
| **単位** | **略語** |
| 年 | 年、yy、yyyy |
| 四半期 | 四半期、qq、q |
| 月 | 月、mm、m |
| 年の日 | dy、y |
| 日 | 日、dd、d |
| 週 | 週、wk、ww |
| 曜日 | 曜日、dw |
| 時間 | 時間、hh |
| 分 | 分、mi、n |
| 秒 | 秒、ss、s |
| ミリ秒 | ミリ秒、ms |
| マイクロ秒 | マイクロ秒、mcs |
| ナノ秒 | ナノ秒、ns |
関数がサポートする単位とES|QLがサポートする時間範囲リテラルの間には重複がありますが、これらのセットは異なり、相互に交換可能ではありません。同様に、サポートされている略語は、この関数の他の確立された製品での実装と便利に共有されており、Elasticsearchで使用される日時の命名法と必ずしも共通ではありません。  
**サポートされる型**  
| unit | startTimestamp | endTimestamp | result |
| :-- | :-- | :-- | :-- |
| keyword | date | date | integer |
| text | date | date | integer |
**例**
#### Esql
``````esql
ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"), date2 = TO_DATETIME("2023-12-02T11:00:00.001Z")
| EVAL dd_ms = DATE_DIFF("microseconds", date1, date2)
`

DATE_EXTRACT

構文

パラメータ

• datePart
• 抽出する日付の部分。可能な値: aligned_day_of_week_in_month, aligned_day_of_week_in_year, aligned_week_of_month, aligned_week_of_year, ampm_of_day, clock_hour_of_ampm, clock_hour_of_day, day_of_month, day_of_week, day_of_year, epoch_day, era, hour_of_ampm, hour_of_day, instant_seconds, micro_of_day, micro_of_second, milli_of_day, milli_of_second, minute_of_day, minute_of_hour, month_of_year, nano_of_day, nano_of_second, offset_seconds, proleptic_month, second_of_day, second_of_minute, year, または year_of_era。これらの値の説明についてはjava.time.temporal.ChronoFieldを参照してください。nullの場合、関数はnullを返します。
• date
• 日付式。nullの場合、関数はnullを返します。

説明

年、月、日、時などの部分を抽出します。

サポートされる型

例

Esql

ROW date = DATE_PARSE("yyyy-MM-dd", "2022-05-06")
| EVAL year = DATE_EXTRACT("year", date)

営業時間外（午前9時前または午後5時以降）に発生したすべてのイベントを特定します。

Esql

FROM sample_data
| WHERE DATE_EXTRACT("hour_of_day", @timestamp) < 9 AND DATE_EXTRACT("hour_of_day", @timestamp) >= 17

DATE_FORMAT

構文

パラメータ

• dateFormat
• 日付形式（オプション）。形式が指定されていない場合、yyyy-MM-dd'T'HH:mm:ss.SSSZ形式が使用されます。nullの場合、関数はnullを返します。
• date
• 日付式。nullの場合、関数はnullを返します。

説明

指定された形式で日付の文字列表現を返します。

サポートされる型

例

Esql

FROM employees
| KEEP first_name, last_name, hire_date
| EVAL hired = DATE_FORMAT("yyyy-MM-dd", hire_date)

DATE_PARSE

構文

パラメータ

• datePattern
• 日付形式。構文についてはDateTimeFormatterのドキュメントを参照してください。nullの場合、関数はnullを返します。
• dateString
• 文字列としての日付式。nullまたは空の文字列の場合、関数はnullを返します。

説明

指定された形式を使用して2番目の引数を解析することにより、日付を返します。

サポートされる型

例

Esql

ROW date_string = "2022-05-06"
| EVAL date = DATE_PARSE("yyyy-MM-dd", date_string)

DATE_TRUNC

構文

パラメータ

• interval
• インターバル; タイムスパンリテラル構文を使用して表現されます。
• date
• 日付式

説明

最も近いインターバルに日付を切り捨てます。

サポートされる型

例

Esql

FROM employees
| KEEP first_name, last_name, hire_date
| EVAL year_hired = DATE_TRUNC(1 year, hire_date)

DATE_TRUNCをSTATS ... BYと組み合わせて日付ヒストグラムを作成します。たとえば、年ごとの雇用数:

Esql

FROM employees
| EVAL year = DATE_TRUNC(1 year, hire_date)
| STATS hires = COUNT(emp_no) BY year
| SORT year

または、時間ごとのエラーレート:

Esql

FROM sample_data
| EVAL error = CASE(message LIKE "*error*", 1, 0)
| EVAL hour = DATE_TRUNC(1 hour, @timestamp)
| STATS error_rate = AVG(error) by hour
| SORT hour

NOW

構文

パラメータ

説明

現在の日付と時刻を返します。

サポートされる型

例

Esql

ROW current_date = NOW()

最後の1時間のログを取得するには:

Esql

FROM sample_data
| WHERE @timestamp > NOW() - 1 hour

ES|QL IP functions

ES|QLは次のIP関数をサポートしています:

• CIDR_MATCH
• IP_PREFIX

CIDR_MATCH

構文

パラメータ

• ip
• ip型のIPアドレス（IPv4とIPv6の両方がサポートされています）。
• blockX
• IPをテストするCIDRブロック。

説明

提供されたIPが提供されたCIDRブロックのいずれかに含まれている場合はtrueを返します。

サポートされる型

例

Esql

FROM hosts
| WHERE CIDR_MATCH(ip1, "127.0.0.2/32", "127.0.0.3/32")
| KEEP card, host, ip0, ip1

IP_PREFIX

構文

パラメータ

• ip
• ip型のIPアドレス（IPv4とIPv6の両方がサポートされています）。
• prefixLengthV4
• IPv4アドレスのプレフィックス長。
• prefixLengthV6
• IPv6アドレスのプレフィックス長。

説明

指定されたプレフィックス長にIPを切り捨てます。

サポートされる型

例

Esql

row ip4 = to_ip("1.2.3.4"), ip6 = to_ip("fe80::cae2:65ff:fece:feb9")
| eval ip4_prefix = ip_prefix(ip4, 24, 0), ip6_prefix = ip_prefix(ip6, 0, 112);

ES|QL mathematical functions

ES|QLは次の数学関数をサポートしています:

• ABS
• ACOS
• ASIN
• ATAN
• ATAN2
• CBRT
• CEIL
• COS
• COSH
• E
• FLOOR
• LOG
• LOG10
• PI
• POW
• ROUND
• SIGNUM
• SIN
• SINH
• SQRT
• TAN
• TANH
• TAU

ABS

構文

パラメータ

• number
• 数値式。nullの場合、関数はnullを返します。

説明

絶対値を返します。

サポートされる型

例

Esql

ROW number = -1.0
| EVAL abs_number = ABS(number)

Esql

FROM employees
| KEEP first_name, last_name, height
| EVAL abs_height = ABS(0.0 - height)

ACOS

構文

パラメータ

• number
• -1から1の間の数値。nullの場合、関数はnullを返します。

説明

**サポートされる型**  
| number | result |
| :-- | :-- |
| double | double |
| integer | double |
| long | double |
| unsigned\_long | double |
**例**
#### Esql
``````esql
ROW a=.9
| EVAL acos=ACOS(a)
`

ASIN

構文

パラメータ

• number
• -1から1の間の数値。nullの場合、関数はnullを返します。

説明

入力数値式の逆正弦をラジアンで表した角度として返します。

サポートされる型

例

Esql

ROW a=.9
| EVAL asin=ASIN(a)

ATAN

構文

パラメータ

• number
• 数値式。nullの場合、関数はnullを返します。

説明

入力数値式の逆正接をラジアンで表した角度として返します。

サポートされる型

例

Esql

ROW a=12.9
| EVAL atan=ATAN(a)

ATAN2

構文

パラメータ

• y_coordinate
• y座標。nullの場合、関数はnullを返します。
• x_coordinate
• x座標。nullの場合、関数はnullを返します。

説明

正のx軸と原点から点(x, y)への線分との間の角度をラジアンで表します。

サポートされる型

例

Esql

ROW y=12.9, x=.6
| EVAL atan2=ATAN2(y, x)

CBRT

構文

パラメータ

• number
• 数値式。nullの場合、関数はnullを返します。

説明

数値の立方根を返します。入力は任意の数値で、返り値は常にdoubleです。無限の立方根はnullです。

サポートされる型

例

Esql

ROW d = 1000.0
| EVAL c = cbrt(d)

CEIL

構文

パラメータ

• number
• 数値式。nullの場合、関数はnullを返します。

説明

最も近い整数に数値を切り上げます。

これはlong（符号なしを含む）およびintegerに対しては何もしません。doubleの場合、これはMath.ceilに似て、整数に最も近いdouble値を選択します。

サポートされる型

例

Esql

ROW a=1.8
| EVAL a=CEIL(a)

COS

構文

パラメータ

• angle
• ラジアンでの角度。nullの場合、関数はnullを返します。

説明

角度のコサインを返します。

サポートされる型

例

Esql

ROW a=1.8
| EVAL cos=COS(a)

COSH

構文

パラメータ

• angle
• ラジアンでの角度。nullの場合、関数はnullを返します。

説明

角度の双曲線コサインを返します。

サポートされる型

例

Esql

ROW a=1.8
| EVAL cosh=COSH(a)

E

構文

パラメータ

説明

https://en.wikipedia.org/wiki/E_(mathematical_constantを返します。

サポートされる型

例

Esql

ROW E()

FLOOR

構文

パラメータ

• number
• 数値式。nullの場合、関数はnullを返します。

説明

最も近い整数に数値を切り捨てます。

これはlong（符号なしを含む）およびintegerに対しては何もしません。doubleの場合、これはMath.floorに似て、整数に最も近いdouble値を選択します。

サポートされる型

例

Esql

ROW a=1.8
| EVAL a=FLOOR(a)

LOG

構文

パラメータ

• base
• 対数の底。nullの場合、関数はnullを返します。指定されていない場合、この関数は値の自然対数（底e）を返します。
• number
• 数値式。nullの場合、関数はnullを返します。

説明

指定された底の値の対数を返します。入力は任意の数値で、返り値は常にdoubleです。ゼロ、負の数、および底が1の対数はnullを返し、警告も表示されます。

サポートされる型

例

Esql

ROW base = 2.0, value = 8.0
| EVAL s = LOG(base, value)

Esql

row value = 100
| EVAL s = LOG(value);

LOG10

構文

パラメータ

• number
• 数値式。nullの場合、関数はnullを返します。

説明

値の底10の対数を返します。入力は任意の数値で、返り値は常にdoubleです。0および負の数の対数はnullを返し、警告も表示されます。

サポートされる型

例

Esql

ROW d = 1000.0
| EVAL s = LOG10(d)

PI

構文

パラメータ

説明

円周と直径の比率である Pi を返します。

サポートされる型

例

Esql

ROW PI()

POW

構文

パラメータ

• base
• 基数の数値式。もし null の場合、関数は null を返します。
• exponent
• 指数の数値式。もし null の場合、関数は null を返します。

説明

base の値を exponent の累乗にしたものを返します。

ここでダブル結果がオーバーフローする可能性があります。その場合、null が返されます。

サポートされる型

例

Esql

ROW base = 2.0, exponent = 2
| EVAL result = POW(base, exponent)

指数は分数であることができ、これは根を計算するのと似ています。例えば、0.5 の指数は基数の平方根を与えます：

Esql

ROW base = 4, exponent = 0.5
| EVAL s = POW(base, exponent)

ROUND

構文

パラメータ

• number
• 丸める数値。もし null の場合、関数は null を返します。
• decimals
• 丸める小数点以下の桁数。デフォルトは 0 です。もし null の場合、関数は null を返します。

説明

指定された小数点以下の桁数に数値を丸めます。デフォルトは 0 で、最も近い整数を返します。精度が負の数の場合、小数点の左側の桁数に丸めます。

サポートされる型

例

Esql

FROM employees
| KEEP first_name, last_name, height
| EVAL height_ft = ROUND(height * 3.281, 1)

SIGNUM

構文

パラメータ

• number
• 数値式。nullの場合、関数はnullを返します。

説明

与えられた数の符号を返します。負の数の場合は -1 を、ゼロの場合は 0 を、正の数の場合は 1 を返します。

サポートされる型

例

Esql

ROW d = 100.0
| EVAL s = SIGNUM(d)

SIN

構文

パラメータ

• angle
• ラジアンでの角度。nullの場合、関数はnullを返します。

説明

角度の サイン 三角関数を返します。

サポートされる型

例

Esql

ROW a=1.8
| EVAL sin=SIN(a)

SINH

構文

パラメータ

• angle
• ラジアンでの角度。nullの場合、関数はnullを返します。

説明

角度の 双曲線サイン を返します。

サポートされる型

例

Esql

ROW a=1.8
| EVAL sinh=SINH(a)

SQRT

構文

パラメータ

• number
• 数値式。nullの場合、関数はnullを返します。

説明

数の平方根を返します。入力は任意の数値で、返り値は常にダブルです。負の数や無限大の平方根は null です。

サポートされる型

例

Esql

ROW d = 100.0
| EVAL s = SQRT(d)

TAN

構文

パラメータ

• angle
• ラジアンでの角度。nullの場合、関数はnullを返します。

説明

角度の タンジェント 三角関数を返します。

サポートされる型

例

Esql

ROW a=1.8
| EVAL tan=TAN(a)

TANH

構文

パラメータ

• angle
• ラジアンでの角度。nullの場合、関数はnullを返します。

説明

角度の 双曲線タンジェント を返します。

サポートされる型

例

Esql

ROW a=1.8
| EVAL tanh=TANH(a)

TAU

構文

パラメータ

説明

円周と半径の 比率 を返します。

サポートされる型

例

Esql

ROW TAU()

ES|QL spatial functions

ES|QL はこれらの空間関数をサポートしています：

• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elasticは問題を修正するために取り組みますが、技術プレビューの機能は公式GA機能のサポートSLAの対象ではありません。 ST_INTERSECTS
• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elasticは問題を修正するために取り組みますが、技術プレビューの機能は公式GA機能のサポートSLAの対象ではありません。 ST_DISJOINT
• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elasticは問題を修正するために取り組みますが、技術プレビューの機能は公式GA機能のサポートSLAの対象ではありません。 ST_CONTAINS
• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elasticは問題を修正するために取り組みますが、技術プレビューの機能は公式GA機能のサポートSLAの対象ではありません。 ST_WITHIN
• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elastic は問題を修正するために取り組みますが、技術プレビューの機能は公式 GA 機能のサポート SLA の対象外です。 ST_X
• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elastic は問題を修正するために取り組みますが、技術プレビューの機能は公式 GA 機能のサポート SLA の対象外です。 ST_Y
• [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elasticは問題を修正するために取り組みますが、技術プレビューの機能は公式GA機能のサポートSLAの対象ではありません。 ST_DISTANCE

ST_INTERSECTS

構文

パラメータ

• geomA
• geo_point、cartesian_point、geo_shape、または cartesian_shape の型の式。もし null の場合、関数は null を返します。
• geomB
• geo_point、cartesian_point、geo_shape、または cartesian_shape の型の式。もし null の場合、関数は null を返します。第二のパラメータは第一のものと同じ座標系を持つ必要があります。これは geo_* と cartesian_* のパラメータを組み合わせることができないことを意味します。

説明

二つのジオメトリが交差する場合は true を返します。交差するとは、共通の点がある場合、内部点（線上の点や多角形内の点を含む）を含みます。これは ST_DISJOINT 関数の逆です。数学的には： ST_Intersects(A, B) ⇔ A ⋂ B ≠ ∅

サポートされる型

例

Esql

FROM airports
| WHERE ST_INTERSECTS(location, TO_GEOSHAPE("POLYGON((42 14, 43 14, 43 15, 42 15, 42 14))"))

ST_DISJOINT

構文

パラメータ

• geomA
• geo_point、cartesian_point、geo_shape、または cartesian_shape の型の式。もし null の場合、関数は null を返します。
• geomB
• geo_point、cartesian_point、geo_shape、または cartesian_shape の型の式。もし null の場合、関数は null を返します。第二のパラメータは第一のものと同じ座標系を持つ必要があります。これは geo_* と cartesian_* のパラメータを組み合わせることができないことを意味します。

説明

二つのジオメトリまたはジオメトリ列が離れているかどうかを返します。これは ST_INTERSECTS 関数の逆です。数学的には： ST_Disjoint(A, B) ⇔ A ⋂ B = ∅

サポートされる型

例

Esql

FROM airport_city_boundaries
| WHERE ST_DISJOINT(city_boundary, TO_GEOSHAPE("POLYGON((-10 -60, 120 -60, 120 60, -10 60, -10 -60))"))
| KEEP abbrev, airport, region, city, city_location

ST_CONTAINS

構文

パラメータ

• geomA
• geo_point、cartesian_point、geo_shape、または cartesian_shape の型の式。もし null の場合、関数は null を返します。
• geomB
• geo_point、cartesian_point、geo_shape、または cartesian_shape の型の式。もし null の場合、関数は null を返します。第二のパラメータは第一のものと同じ座標系を持つ必要があります。これは geo_* と cartesian_* のパラメータを組み合わせることができないことを意味します。

説明

第一のジオメトリが第二のジオメトリを含むかどうかを返します。これは ST_WITHIN 関数の逆です。

サポートされる型

例

Esql

FROM airport_city_boundaries
| WHERE ST_CONTAINS(city_boundary, TO_GEOSHAPE("POLYGON((109.35 18.3, 109.45 18.3, 109.45 18.4, 109.35 18.4, 109.35 18.3))"))
| KEEP abbrev, airport, region, city, city_location

ST_WITHIN

構文

パラメータ

• geomA
• geo_point、cartesian_point、geo_shape、または cartesian_shape の型の式。もし null の場合、関数は null を返します。
• geomB
• geo_point、cartesian_point、geo_shape、または cartesian_shape の型の式。もし null の場合、関数は null を返します。第二のパラメータは第一のものと同じ座標系を持つ必要があります。これは geo_* と cartesian_* のパラメータを組み合わせることができないことを意味します。

説明

第一のジオメトリが第二のジオメトリの中にあるかどうかを返します。これは ST_CONTAINS 関数の逆です。

サポートされる型

例

Esql

FROM airport_city_boundaries
| WHERE ST_WITHIN(city_boundary, TO_GEOSHAPE("POLYGON((109.1 18.15, 109.6 18.15, 109.6 18.65, 109.1 18.65, 109.1 18.15))"))
| KEEP abbrev, airport, region, city, city_location

ST_X

構文

パラメータ

• point
• geo_point または cartesian_point の型の式。もし null の場合、関数は null を返します。

説明

提供された点から x 座標を抽出します。点が geo_point 型の場合、これは longitude 値を抽出することに相当します。

サポートされる型

例

Esql

ROW point = TO_GEOPOINT("POINT(42.97109629958868 14.7552534006536)")
| EVAL x =  ST_X(point), y = ST_Y(point)

ST_Y

構文

パラメータ

• point
• geo_point または cartesian_point の型の式。もし null の場合、関数は null を返します。

説明

提供された点から y 座標を抽出します。点が geo_point 型の場合、これは latitude 値を抽出することに相当します。

サポートされる型

例

Esql

ROW point = TO_GEOPOINT("POINT(42.97109629958868 14.7552534006536)")
| EVAL x =  ST_X(point), y = ST_Y(point)

ST_DISTANCE

構文

パラメータ

• geomA
• geo_point または cartesian_point の型の式。もし null の場合、関数は null を返します。
• geomB
• geo_point または cartesian_point の型の式。もし null の場合、関数は null を返します。第二のパラメータは第一のものと同じ座標系を持つ必要があります。これは geo_point と cartesian_point のパラメータを組み合わせることができないことを意味します。

説明

二つの点の間の距離を計算します。直交ジオメトリの場合、これは元の座標と同じ単位でのピタゴラス距離です。地理的ジオメトリの場合、これはメートル単位の大円に沿った円距離です。

サポートされる型

例

Esql

FROM airports
| WHERE abbrev == "CPH"
| EVAL distance = ST_DISTANCE(location, city_location)
| KEEP abbrev, name, location, city_location, distance

ES|QL string functions

ES|QL はこれらの文字列関数をサポートしています：

• CONCAT
• ENDS_WITH
• FROM_BASE64
• LEFT
• LENGTH
• LOCATE
• LTRIM
• REPEAT
• REPLACE
• RIGHT
• RTRIM
• SPLIT
• STARTS_WITH
• SUBSTRING
• TO_BASE64
• TO_LOWER
• TO_UPPER
• TRIM

CONCAT

構文

パラメータ

• string1
• 連結する文字列。
• string2
• 連結する文字列。

説明

二つ以上の文字列を連結します。

サポートされる型

例

Esql

FROM employees
| KEEP first_name, last_name
| EVAL fullname = CONCAT(first_name, " ", last_name)