ES|QL 查询构建器

命令

class elasticsearch.esql.ESQL

ESQL 类的静态方法提供了对 ES|QL 源命令的访问，用于创建 ES|QL 查询。

这些方法返回 ESQLBase 类的实例，该实例提供了对 ES|QL 处理命令的访问。

static branch()

此方法只能在 FORK 命令内部使用来创建每个分支。

示例:

query = ESQL.from_("employees").fork(
    ESQL.branch().where("emp_no == 10001"),
    ESQL.branch().where("emp_no == 10002"),
)

Return type:: Branch

static from_(*indices)

FROM 源命令返回一个包含来自数据流、索引或别名数据的表。

Parameters:: indices (Type[DocumentBase] | str) – 索引、数据流或别名列表。支持通配符和日期数学表达式。
Return type:: From

示例:

query1 = ESQL.from_("employees")
query2 = ESQL.from_("<logs-{now/d}>")
query3 = ESQL.from_("employees-00001", "other-employees-*")
query4 = ESQL.from_("cluster_one:employees-00001", "cluster_two:other-employees-*")
query5 = ESQL.from_("employees").metadata("_id")

static row(**params)

ROW 源命令生成包含一个或多个指定值列的行。这在测试时很有用。

Parameters:: params (Any) – 要生成的列值，以关键字参数形式给出。
Return type:: Row

示例:

query1 = ESQL.row(a=1, b="two", c=None)
query2 = ESQL.row(a=[1, 2])
query3 = ESQL.row(a=functions.round(1.23, 0))

static show(item)

SHOW 源命令返回有关部署及其功能的信息。

Parameters:: item (str) – 只能是 INFO。
Return type:: Show

示例:

query = ESQL.show("INFO")

class elasticsearch.esql.esql.ESQLBase

ESQLBase 类的方法提供了对 ES|QL 处理命令的访问，用于构建 ES|QL 查询。

change_point(value)

CHANGE_POINT 用于检测指标中的峰值、谷值及变化点。

Parameters:: value (InstrumentedField | str) – 需要检测变化点的指标列。
Return type:: ChangePoint

Examples:

query = (
    ESQL.row(key=list(range(1, 26)))
    .mv_expand("key")
    .eval(value=functions.case("key<13", 0, 42))
    .change_point("value")
    .on("key")
    .where("type IS NOT NULL")
)

completion(*prompt, **named_prompt)

COMPLETION 命令允许您直接在 ES|QL 查询中向大型语言模型 (LLM) 发送提示和上下文，以执行文本生成任务。

Parameters:

prompt (Any) – 用于提示 LLM 的输入文本或表达式。可以是字符串字面量或引用包含文本的列。
named_prompt (Any) – 作为关键字参数提供的输入文本或表达式。参数名将用作列名。若未指定，结果将存储在名为 completion 的列中。若指定列已存在，则会被新结果覆盖。

Return type:

Completion

Examples:

query1 = (
    ESQL.row(question="What is Elasticsearch?")
    .completion("question").with_("test_completion_model")
    .keep("question", "completion")
)
query2 = (
    ESQL.row(question="What is Elasticsearch?")
    .completion(answer="question").with_("test_completion_model")
    .keep("question", "answer")
)
query3 = (
    ESQL.from_("movies")
    .sort("rating DESC")
    .limit(10)
    .eval(prompt="""CONCAT(
        "Summarize this movie using the following information: \n",
        "Title: ", title, "\n",
        "Synopsis: ", synopsis, "\n",
        "Actors: ", MV_CONCAT(actors, ", "), "\n",
    )""")
    .completion(summary="prompt").with_("test_completion_model")
    .keep("title", "summary", "rating")
)

dissect(input, pattern)

DISSECT 允许您从字符串中提取结构化数据。

Parameters:

input (InstrumentedField | str) – 包含待结构化字符串的列。若列含多个值，DISSECT 将处理每个值。
pattern (str) – 解析模式。若字段名与现有列冲突，则丢弃原列。若字段名重复使用，仅最右侧的重复项会创建列。

Return type:

Dissect

Examples:

query = (
    ESQL.row(a="2023-01-23T12:15:00.000Z - some text - 127.0.0.1")
    .dissect("a", "%{date} - %{msg} - %{ip}")
    .keep("date", "msg", "ip")
    .eval(date="TO_DATETIME(date)")
)

drop(*columns)

DROP 处理命令用于移除一个或多个列。

Parameters:: columns (InstrumentedField | str) – 要删除的列，以位置参数形式提供。支持通配符。
Return type:: Drop

Examples:

query1 = ESQL.from_("employees").drop("height")
query2 = ESQL.from_("employees").drop("height*")

enrich(policy)

ENRICH 允许您使用富化策略从现有索引添加数据作为新列。

Parameters:: policy (str) – 富化策略名称。需先创建并执行该富化策略。
Return type:: Enrich

Examples:

query1 = (
    ESQL.row(a="1")
    .enrich("languages_policy").on("a").with_("language_name")
)
query2 = (
    ESQL.row(a="1")
    .enrich("languages_policy").on("a").with_(name="language_name")
)

eval(*columns, **named_columns)

EVAL 处理命令允许您通过计算值添加新列。

Parameters:

columns (Any) – 列的值，作为位置参数提供。可以是字面量、表达式或函数。可以使用在此列左侧定义的列。
named_columns (Any) – 新列的值，作为关键字参数提供。参数名称将用作列名。如果已存在同名列，则现有列将被丢弃。如果列名重复使用，只有最右侧的重复项会创建列。

Return type:

Eval

Examples:

query1 = (
    ESQL.from_("employees")
    .sort("emp_no")
    .keep("first_name", "last_name", "height")
    .eval(height_feet="height * 3.281", height_cm="height * 100")
)
query2 = (
    ESQL.from_("employees")
    .eval("height * 3.281")
    .stats(avg_height_feet=functions.avg("`height * 3.281`"))
)

fork(fork1, fork2=None, fork3=None, fork4=None, fork5=None, fork6=None, fork7=None, fork8=None)

FORK 处理命令创建多个执行分支，对相同输入数据进行操作，并将结果合并到单个输出表中。

Parameters:

fork<n> – 最多8个执行分支，使用 ESQL.branch() 方法创建。
fork1 (ESQLBase)
fork2 (ESQLBase | None)
fork3 (ESQLBase | None)
fork4 (ESQLBase | None)
fork5 (ESQLBase | None)
fork6 (ESQLBase | None)
fork7 (ESQLBase | None)
fork8 (ESQLBase | None)

Return type:

Fork

Examples:

query = (
    ESQL.from_("employees")
    .fork(
        ESQL.branch().where("emp_no == 10001"),
        ESQL.branch().where("emp_no == 10002"),
    )
    .keep("emp_no", "_fork")
    .sort("emp_no")
)

grok(input, pattern)

GROK 允许您从字符串中提取结构化数据。

Parameters:

input (InstrumentedField | str) – 包含待结构化字符串的列。如果该列有多个值， GROK 将处理每个值。
pattern (str) – grok模式。如果字段名与现有列冲突，则现有列将被丢弃。如果字段名重复使用，将创建一个多值列，每个字段名出现对应一个值。

Return type:

Grok

Examples:

query1 = (
    ESQL.row(a="2023-01-23T12:15:00.000Z 127.0.0.1 some.email@foo.com 42")
    .grok("a", "%{TIMESTAMP_ISO8601:date} %{IP:ip} %{EMAILADDRESS:email} %{NUMBER:num}")
    .keep("date", "ip", "email", "num")
)
query2 = (
    ESQL.row(a="2023-01-23T12:15:00.000Z 127.0.0.1 some.email@foo.com 42")
    .grok(
        "a",
        "%{TIMESTAMP_ISO8601:date} %{IP:ip} %{EMAILADDRESS:email} %{NUMBER:num:int}",
    )
    .keep("date", "ip", "email", "num")
    .eval(date=functions.to_datetime("date"))
)
query3 = (
    ESQL.from_("addresses")
    .keep("city.name", "zip_code")
    .grok("zip_code", "%{WORD:zip_parts} %{WORD:zip_parts}")
)

keep(*columns)

KEEP 处理命令允许您指定返回哪些列及其返回顺序。

Parameters:: columns (InstrumentedField | str) – 要保留的列，作为位置参数提供。支持通配符。
Return type:: Keep

Examples:

query1 = ESQL.from_("employees").keep("emp_no", "first_name", "last_name", "height")
query2 = ESQL.from_("employees").keep("h*")
query3 = ESQL.from_("employees").keep("h*", "*")

limit(max_number_of_rows)

LIMIT 处理命令允许您限制返回的行数。

Parameters:: max_number_of_rows (int) – 要返回的最大行数。
Return type:: Limit

Examples:

query1 = ESQL.from_("employees").sort("emp_no ASC").limit(5)
query2 = ESQL.from_("index").stats(functions.avg("field1")).by("field2").limit(20000)

lookup_join(lookup_index)

LOOKUP JOIN 允许您将另一个索引（称为’查找’索引）中的数据添加到 ES|QL 查询结果中，从而简化数据丰富和分析工作流程。

Parameters:: lookup_index (Type[DocumentBase] | str) – 查找索引的名称。必须指定具体的索引名称—— 不支持通配符、别名和远程集群引用。用于查找的索引必须配置为查找索引模式。
Return type:: LookupJoin

Examples:

query1 = (
    ESQL.from_("firewall_logs")
    .lookup_join("threat_list").on("source.IP")
    .where("threat_level IS NOT NULL")
)
query2 = (
    ESQL.from_("system_metrics")
    .lookup_join("host_inventory").on("host.name")
    .lookup_join("ownerships").on("host.name")
)
query3 = (
    ESQL.from_("app_logs")
    .lookup_join("service_owners").on("service_id")
)
query4 = (
    ESQL.from_("employees")
    .eval(language_code="languages")
    .where("emp_no >= 10091 AND emp_no < 10094")
    .lookup_join("languages_lookup").on("language_code")
)

mv_expand(column)

MV_EXPAND 处理命令将多值列展开为每个值一行，其他列会被复制。

Parameters:: column (InstrumentedField | str) – 要展开的多值列。
Return type:: MvExpand

Examples:

query = ESQL.row(a=[1, 2, 3], b="b", j=["a", "b"]).mv_expand("a")

rename(**columns)

RENAME 处理命令用于重命名一个或多个列。

Parameters:: columns (InstrumentedField | str) – 新旧列名对，以关键字参数形式给出。如果名称与现有列名冲突，则现有列会被删除。如果多个列被重命名为相同名称，则除最右侧的同名列外，其他列都会被删除。
Return type:: Rename

Examples:

query = (
    ESQL.from_("employees")
    .keep("first_name", "last_name", "still_hired")
    .rename(still_hired="employed")
)

sample(probability)

SAMPLE 命令对表行进行抽样。

Parameters:: probability (float) – 行被包含在样本中的概率。该值必须在0到1之间（不包括0和1）。
Return type:: Sample

Examples:

query = ESQL.from_("employees").keep("emp_no").sample(0.05)

sort(*columns)

SORT 处理命令根据一个或多个列对表进行排序。

Parameters:: columns (Any) – 用于排序的列。
Return type:: Sort

Examples:

query1 = (
    ESQL.from_("employees")
    .keep("first_name", "last_name", "height")
    .sort("height")
)
query2 =  (
    ESQL.from_("employees")
    .keep("first_name", "last_name", "height")
    .sort("height DESC")
)
query3 = (
    ESQL.from_("employees")
    .keep("first_name", "last_name", "height")
    .sort("height DESC", "first_name ASC")
)
query4 = (
    ESQL.from_("employees")
    .keep("first_name", "last_name", "height")
    .sort("first_name ASC NULLS FIRST")
)

stats(*expressions, **named_expressions)

STATS 处理命令根据共同值对行进行分组，并计算分组行上的一个或多个聚合值。

Parameters:

expressions (Any) – 作为位置参数提供的表达式列表。
named_expressions (Any) – 作为关键字参数提供的表达式列表。参数名称将用作返回的聚合值名称。

Return type:

Stats

注意 expressions 和 named_expressions 只能提供其中一个。

示例:

query1 = (
    ESQL.from_("employees")
    .stats(count=functions.count("emp_no")).by("languages")
    .sort("languages")
)
query2 = (
    ESQL.from_("employees")
    .stats(avg_lang=functions.avg("languages"))
)
query3 = (
    ESQL.from_("employees")
    .stats(
        avg_lang=functions.avg("languages"),
        max_lang=functions.max("languages")
    )
)
query4 = (
    ESQL.from_("employees")
    .stats(
        avg50s=functions.avg("salary").where('birth_date < "1960-01-01"'),
        avg60s=functions.avg("salary").where('birth_date >= "1960-01-01"'),
    ).by("gender")
    .sort("gender")
)
query5 = (
    ESQL.from_("employees")
    .eval(Ks="salary / 1000")
    .stats(
        under_40K=functions.count("*").where("Ks < 40"),
        inbetween=functions.count("*").where("40 <= Ks AND Ks < 60"),
        over_60K=functions.count("*").where("60 <= Ks"),
        total=f.count("*")
    )
)
query6 = (
    ESQL.row(i=1, a=["a", "b"])
    .stats(functions.min("i")).by("a")
    .sort("a ASC")
)
query7 = (
    ESQL.from_("employees")
    .eval(hired=functions.date_format("hire_date", "yyyy"))
    .stats(avg_salary=functions.avg("salary")).by("hired", "languages.long")
    .eval(avg_salary=functions.round("avg_salary"))
    .sort("hired", "languages.long")

)

where(*expressions)

WHERE 处理命令生成一个表，其中包含输入表中满足所提供条件（评估为 true）的所有行。

Parameters:: expressions (Any) – 作为位置参数提供的布尔表达式列表。这些表达式将通过 AND 逻辑运算符组合。
Return type:: Where

示例:

query1 = (
    ESQL.from_("employees")
    .keep("first_name", "last_name", "still_hired")
    .where("still_hired == true")
)
query2 = (
    ESQL.from_("sample_data")
    .where("@timestamp > NOW() - 1 hour")
)
query3 = (
    ESQL.from_("employees")
    .keep("first_name", "last_name", "height")
    .where("LENGTH(first_name) < 4")
)

class elasticsearch.esql.esql.From

FROM 源命令的实现。

此类继承自 ESQLBase，使得可以将属于 ES|QL 查询的所有命令链接在单个表达式中。

metadata(*fields)

FROM 源命令的延续。

Parameters:: fields (InstrumentedField | str) – 要检索的元数据字段，作为位置参数提供。
Return type:: From

class elasticsearch.esql.esql.Row

ROW 源命令的实现。

此类继承自 ESQLBase，使得可以将属于 ES|QL 查询的所有命令链接在单个表达式中。

class elasticsearch.esql.esql.Show

SHOW 源命令的实现。

此类继承自 ESQLBase，使得可以将属于 ES|QL 查询的所有命令链接在单个表达式中。

class elasticsearch.esql.esql.ChangePoint

CHANGE POINT 处理命令的实现。

此类继承自 ESQLBase，使得可以将属于 ES|QL 查询的所有命令链式组合在单个表达式中。

as_(type_name, pvalue_name)

CHANGE_POINT 命令的延续。

Parameters:

type_name (str) – 包含变化点类型的输出列名称。如果未指定，则使用 type。
pvalue_name (str) – 包含表示变化点显著程度的 p 值的输出列名称。如果未指定，则使用 pvalue。

Return type:

ChangePoint

on(key)

CHANGE_POINT 命令的延续。

Parameters:: key (InstrumentedField | str) – 用于排序值的键列。如果未指定，则使用 @timestamp。
Return type:: ChangePoint

class elasticsearch.esql.esql.Completion

COMPLETION 处理命令的实现。

此类继承自 ESQLBase，使得可以将属于 ES|QL 查询的所有命令链式组合在单个表达式中。

with_(inference_id)

COMPLETION 命令的延续。

Parameters:: inference_id (str) – 用于任务推理的端点ID。该推理端点必须配置为完成任务类型。
Return type:: Completion

class elasticsearch.esql.esql.Dissect

DISSECT 处理命令的实现。

此类继承自 ESQLBase，使得可以将属于 ES|QL 查询的所有命令链式组合在单个表达式中。

append_separator(separator)

DISSECT 命令的延续。

Parameters:: separator (str) – 当使用追加修饰符时，用作追加值之间分隔符的字符串。
Return type:: Dissect

class elasticsearch.esql.esql.Drop

DROP 处理命令的实现。

此类继承自 ESQLBase，使得可以将属于 ES|QL 查询的所有命令链式组合在单个表达式中。

class elasticsearch.esql.esql.Enrich

ENRICH 处理命令的实现。

此类继承自 ESQLBase，以便能够将属于 ES|QL 查询的所有命令链接在单个表达式中。

on(match_field)

ENRICH 命令的延续。

Parameters:: match_field (InstrumentedField | str) – 匹配字段。ENRICH 使用其值在富化索引中查找记录。如果未指定，将在与富化策略中定义的 match_field 同名的列上执行匹配。
Return type:: Enrich

with_(*fields, **named_fields)

ENRICH 命令的延续。

Parameters:

fields (InstrumentedField | str) – 从富化索引中添加至结果的新列（作为位置参数给出）。如果已存在与富化字段同名的列，现有列将被新列替换。如果未指定，则添加策略中定义的每个富化字段。除非重命名富化字段，否则与富化字段同名的列将被丢弃。
named_fields (InstrumentedField | str) – 从富化索引中添加至结果的新列（作为关键字参数给出）。关键字参数的名称用作列名。如果列名与新名称相同，该列将被丢弃。如果名称（新名称或原始名称）出现多次，只有最右侧的重复项会创建新列。

Return type:

Enrich

class elasticsearch.esql.esql.Eval

EVAL 处理命令的实现。

此类继承自 ESQLBase，以便能够将属于 ES|QL 查询的所有命令链接在单个表达式中。

class elasticsearch.esql.esql.Fork

FORK 处理命令的实现。

此类继承自 ESQLBase，以便能够将属于 ES|QL 查询的所有命令链接在单个表达式中。

class elasticsearch.esql.esql.Grok

GROK 处理命令的实现。

此类继承自 ESQLBase，以便能够将属于 ES|QL 查询的所有命令链接在单个表达式中。

class elasticsearch.esql.esql.Keep

KEEP 处理命令的实现。

此类继承自 ESQLBase，以便能够将属于 ES|QL 查询的所有命令链接在单个表达式中。

class elasticsearch.esql.esql.Limit

实现 LIMIT 处理命令。

此类继承自 ESQLBase，以便能够将属于 ES|QL 查询的所有命令链接在单个表达式中。

class elasticsearch.esql.esql.LookupJoin

实现 LOOKUP JOIN 处理命令。

此类继承自 ESQLBase，以便能够将属于 ES|QL 查询的所有命令链接在单个表达式中。

on(field)

LOOKUP_JOIN 命令的延续。

Parameters:: field (InstrumentedField | str) – 连接字段。该字段必须同时存在于当前查询结果和查找索引中。如果字段包含多值条目，这些条目将不会匹配任何内容（添加的字段将在这些行中包含空值）。
Return type:: LookupJoin

class elasticsearch.esql.esql.MvExpand

实现 MV_EXPAND 处理命令。

此类继承自 ESQLBase，以便能够将属于 ES|QL 查询的所有命令链接在单个表达式中。

class elasticsearch.esql.esql.Rename

实现 RENAME 处理命令。

此类继承自 ESQLBase，以便能够将属于 ES|QL 查询的所有命令链接在单个表达式中。

class elasticsearch.esql.esql.Sample

实现 SAMPLE 处理命令。

此类继承自 ESQLBase，以便能够将属于 ES|QL 查询的所有命令链接在单个表达式中。

class elasticsearch.esql.esql.Sort

SORT 处理命令的实现。

此类继承自 ESQLBase，使得可以将属于 ES|QL 查询的所有命令链接在单个表达式中。

class elasticsearch.esql.esql.Stats

STATS 处理命令的实现。

此类继承自 ESQLBase，使得可以将属于 ES|QL 查询的所有命令链接在单个表达式中。

class elasticsearch.esql.esql.Where

WHERE 处理命令的实现。

此类继承自 ESQLBase，使得可以将属于 ES|QL 查询的所有命令链接在单个表达式中。

Functions

elasticsearch.esql.functions.abs(number)

返回数值的绝对值。

Parameters:: number (Any) – 数值表达式。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.acos(number)

返回 n 的反余弦值，以弧度表示的角度。

Parameters:: number (Any) – 介于 -1 和 1 之间的数值。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.asin(number)

返回输入数值表达式的反正弦值，以弧度表示的角度。

Parameters:: number (Any) – 介于 -1 和 1 之间的数值。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.atan(number)

返回输入数值表达式的反正切值，以弧度表示的角度。

Parameters:: number (Any) – 数值表达式。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.atan2(y_coordinate, x_coordinate)

返回笛卡尔平面中正x轴与从原点到点(x,y)的射线之间的夹角，以弧度表示。

Parameters:

y_coordinate (Any) – y坐标。如果为 null，函数返回 null。
x_coordinate (Any) – x坐标。如果为 null，函数返回 null。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.avg(number)

数值字段的平均值。

Parameters:: number (Any) – 输出待计算平均值的表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.avg_over_time(number)

数值字段随时间变化的平均值。

Parameters:: number (Any) – 输出待计算平均值的表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.bit_length(string)

返回字符串的比特长度。

Parameters:: string (Any) – 字符串表达式。若为`null`，函数返回`null`。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.bucket(field, buckets, from_, to)

根据日期时间或数值输入创建分组值（桶）。桶的大小可直接指定，或根据推荐数量和值范围自动选择。

Parameters:

field (Any) – 用于生成桶的数值或日期表达式。
buckets (Any) – 目标桶数量，若省略`from`和`to`参数则表示期望的桶大小。
from – 范围起始值。可以是数字、日期或以字符串表示的日期。
to (Any) – 范围结束值。可以是数字、日期或以字符串表示的日期。
from_ (Any)

Return type:

InstrumentedExpression

elasticsearch.esql.functions.byte_length(string)

返回字符串的字节长度。

Parameters:: string (Any) – 字符串表达式。若为`null`，函数返回`null`。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.case(*conditions)

接受条件与值的配对。该函数返回第一个评估为`true`的条件对应的值。如果参数数量为奇数，最后一个参数将作为默认值，在没有条件匹配时返回。如果参数数量为偶数且没有条件匹配，函数返回`null`。

Parameters:: conditions (Any)
Return type:: InstrumentedExpression

elasticsearch.esql.functions.categorize(field)

将文本消息分组为具有相似格式的文本值类别。

Parameters:: field (Any) – 用于分类的表达式
Return type:: InstrumentedExpression

elasticsearch.esql.functions.cbrt(number)

返回数值的立方根。输入可以是任意数值类型，返回值始终为双精度浮点数。无穷大的立方根返回null。

Parameters:: number (Any) – 数值表达式。若为`null`，函数返回`null`。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.ceil(number)

将数值向上取整到最接近的整数。

Parameters:: number (Any) – 数值表达式。若为`null`，函数返回`null`。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.cidr_match(ip, block_x)

如果提供的IP地址包含在任意一个CIDR地址块中则返回true。

Parameters:

ip (Any) – 类型为`ip`的IP地址（支持IPv4和IPv6）。
block_x (Any) – 用于测试IP的CIDR地址块。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.coalesce(first, rest)

返回第一个非 null 的参数。如果所有参数都为 null，则返回 null。

Parameters:

first (Any) – 要评估的表达式。
rest (Any) – 其他要评估的表达式。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.concat(*strings)

连接两个或多个字符串。

Parameters:: strings (Any)
Return type:: InstrumentedExpression

elasticsearch.esql.functions.cos(angle)

返回角度的余弦值。

Parameters:: angle (Any) – 以弧度表示的角度。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.cosh(number)

返回数字的双曲余弦值。

Parameters:: number (Any) – 数值表达式。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.count(field)

返回输入值的总数（计数）。

Parameters:: field (Any) – 输出待计数值的表达式。如果省略，等同于 `COUNT(*)`（行数）。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.count_distinct(field, precision)

返回近似唯一值数量。

Parameters:

field (Any) – 需要计算唯一值数量的列或字面量。
precision (Any) – 精度阈值。最大支持值为40000。超过此数值的阈值将等同于40000阈值。默认值为3000。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.count_distinct_over_time(field, precision)

字段随时间变化的唯一值计数。

Parameters:

field (Any)
precision (Any) – 精度阈值。最大支持值为40000。超过此数值的阈值将等同于40000阈值。默认值为3000。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.count_over_time(field)

字段随时间变化的计数值。

Parameters:: field (Any)
Return type:: InstrumentedExpression

elasticsearch.esql.functions.date_diff(unit, start_timestamp, end_timestamp)

从`endTimestamp`中减去`startTimestamp`并返回以`unit`为单位的差值。如果`startTimestamp`晚于`endTimestamp`，则返回负值。

Parameters:

unit (Any) – 时间差单位
start_timestamp (Any) – 表示开始时间戳的字符串
end_timestamp (Any) – 表示结束时间戳的字符串

Return type:

InstrumentedExpression

elasticsearch.esql.functions.date_extract(date_part, date)

提取日期的部分信息，如年、月、日、小时等。

Parameters:

date_part (Any) – 要提取的日期部分。可以是： 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。如果为`null`，函数返回`null`。
date (Any) – 日期表达式。如果为`null`，函数返回`null`。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.date_format(date, date_format=None)

返回指定格式的日期字符串表示。

Parameters:

date_format (Any) – 日期格式（可选）。如果未指定格式，则使用 yyyy-MM-dd’T’HH:mm:ss.SSSZ`格式。如果为`null，函数返回`null`。
date (Any) – 日期表达式。如果为`null`，函数返回`null`。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.date_parse(date_pattern, date_string)

通过使用第一个参数指定的格式解析第二个参数来返回日期。

Parameters:

date_pattern (Any) – 日期格式。如果为`null`，函数返回`null`。
date_string (Any) – 字符串形式的日期表达式。如果为`null`或空字符串，函数返回`null`。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.date_trunc(interval, date)

将日期向下舍入到自纪元（起始于`0001-01-01T00:00:00Z`）以来最接近的时间间隔。

Parameters:

interval (Any) – 时间间隔；使用时段时间字面量语法表示。
date (Any) – 日期表达式

Return type:

InstrumentedExpression

elasticsearch.esql.functions.e()

返回欧拉数。

Return type:: InstrumentedExpression

elasticsearch.esql.functions.ends_with(str, suffix)

返回一个布尔值，指示关键字字符串是否以另一个字符串结尾。

Parameters:

str (Any) – 字符串表达式。如果为`null`，函数返回`null`。
suffix (Any) – 字符串表达式。如果为`null`，函数返回`null`。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.exp(number)

返回 e 的给定数字次幂的值。

Parameters:: number (Any) – 数值表达式。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.first_over_time(field)

字段的最早值，由 @timestamp 字段确定时间顺序。

Parameters:: field (Any)
Return type:: InstrumentedExpression

elasticsearch.esql.functions.floor(number)

将数字向下舍入到最接近的整数。

Parameters:: number (Any) – 数值表达式。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.from_base64(string)

解码 base64 字符串。

Parameters:: string (Any) – 一个 base64 字符串。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.greatest(first, rest)

返回多列中的最大值。这与 MV_MAX 类似，但旨在同时对多列进行计算。

Parameters:

first (Any) – 要评估的第一列。
rest (Any) – 要评估的其余列。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.hash(algorithm, input)

使用多种算法（如MD5、SHA、SHA-224、SHA-256、SHA-384、SHA-512）计算输入值的哈希值。

Parameters:

algorithm (Any) – 使用的哈希算法。
input (Any) – 待哈希的输入值。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.hypot(number1, number2)

返回两个数字的斜边长度。输入可以是任意数值，返回值始终为双精度浮点数。无限大的斜边长度返回null。

Parameters:

number1 (Any) – 数值表达式。若为`null`，函数返回`null`。
number2 (Any) – 数值表达式。若为`null`，函数返回`null`。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.ip_prefix(ip, prefix_length_v4, prefix_length_v6)

将IP地址截断至指定前缀长度。

Parameters:

ip (Any) – 类型为`ip`的IP地址（支持IPv4和IPv6）。
prefix_length_v4 (Any) – IPv4地址的前缀长度。
prefix_length_v6 (Any) – IPv6地址的前缀长度。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.knn(field, query, options=None)

通过相似度度量查找与查询向量最接近的k个向量。knn函数通过对已索引的dense_vectors进行近似搜索来查找最近邻向量。

Parameters:

field (Any) – 查询目标字段。
query (Any) – 需要查找最近邻的向量值。
options (Any) – (可选) 作为函数命名参数的kNN附加选项。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.kql(query)

执行KQL查询。如果提供的KQL查询字符串匹配该行，则返回true。

Parameters:: query (Any) – KQL查询字符串格式的查询语句。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.last_over_time(field)

字段的最新值，其时效性由 @timestamp 字段决定。

Parameters:: field (Any)
Return type:: InstrumentedExpression

elasticsearch.esql.functions.least(first, rest)

返回多列中的最小值。这与 MV_MIN 类似，但旨在同时对多列进行计算。

Parameters:

first (Any) – 要评估的第一列。
rest (Any) – 要评估的其余列。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.left(string, length)

返回从字符串左侧开始提取指定长度的子串。

Parameters:

string (Any) – 要提取子串的原始字符串。
length (Any) – 要返回的字符数。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.length(string)

返回字符串的字符长度。

Parameters:: string (Any) – 字符串表达式。若为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.locate(string, substring, start)

返回表示子串在字符串中位置的整数值。若未找到则返回 0。注意字符串位置从 1 开始计数。

Parameters:

string (Any) – 输入字符串
substring (Any) – 要在输入字符串中定位的子串
start (Any) – 起始索引

Return type:

InstrumentedExpression

elasticsearch.esql.functions.log(base, number)

返回一个数值的对数结果，以指定基数为底。输入可以是任意数值，返回值始终为双精度浮点数。对零、负数取对数或以1为底时，函数会返回`null`并发出警告。

Parameters:

base (Any) – 对数的底数。如果为`null`，函数返回`null`。如果未提供此参数，函数将返回数值的自然对数（以e为底）。
number (Any) – 数值表达式。如果为`null`，函数返回`null`。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.log10(number)

返回一个数值的常用对数（以10为底）。输入可以是任意数值，返回值始终为双精度浮点数。对0和负数取对数时，函数会返回`null`并发出警告。

Parameters:: number (Any) – 数值表达式。如果为`null`，函数返回`null`。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.ltrim(string)

移除字符串前导的空白字符。

Parameters:: string (Any) – 字符串表达式。如果为`null`，函数返回`null`。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.match(field, query, options=None)

使用`MATCH`对指定字段执行匹配查询。使用`MATCH`相当于在Elasticsearch Query DSL中使用`match`查询。

Parameters:

field (Any) – 查询目标字段。
query (Any) – 在指定字段中查找的值。
options (Any) – (可选) 以函数命名参数形式提供的额外匹配选项。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.match_phrase(field, query, options=None)

使用`MATCH_PHRASE`对指定字段执行短语匹配查询。使用`MATCH_PHRASE`相当于在Elasticsearch Query DSL中使用`match_phrase`查询。

Parameters:

field (Any) – 查询目标字段。
query (Any) – 在指定字段中查找的值。
options (Any) – (可选) 以函数命名参数形式提供的短语匹配额外选项。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.max(field)

字段的最大值。

Parameters:: field (Any)
Return type:: InstrumentedExpression

elasticsearch.esql.functions.max_over_time(field)

字段随时间变化的最大值。

Parameters:: field (Any)
Return type:: InstrumentedExpression

elasticsearch.esql.functions.md5(input)

计算输入数据的 MD5 哈希值。

Parameters:: input (Any) – 需要哈希的输入数据。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.median(number)

大于一半数值且小于另一半数值的值，也称为50%百分位数（PERCENTILE）。

Parameters:: number (Any) – 用于计算中位数的数值表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.median_absolute_deviation(number)

返回中位数绝对偏差，一种衡量数据离散程度的指标。它是一种稳健统计量，适用于描述可能存在异常值或非正态分布的数据。对于此类数据，它比标准差更具描述性。计算方式为：每个数据点与样本中位数偏差的绝对值的中位数。即对于随机变量`X`，中位数绝对偏差为`median(|median(X) - X|)`。

Parameters:: number (Any)
Return type:: InstrumentedExpression

elasticsearch.esql.functions.min(field)

字段的最小值。

Parameters:: field (Any)
Return type:: InstrumentedExpression

elasticsearch.esql.functions.min_over_time(field)

字段随时间变化的最小值。

Parameters:: field (Any)
Return type:: InstrumentedExpression

elasticsearch.esql.functions.multi_match(query, fields, options=None)

使用 MULTI_MATCH 在指定字段上执行多字段匹配查询。多字段匹配查询基于 match 查询，允许进行多字段查询。

Parameters:

query (Any) – 要在提供字段中查找的值。
fields (Any) – 用于匹配的字段
options (Any) – (可选) MultiMatch 的附加选项，作为函数的命名参数传递

Return type:

InstrumentedExpression

elasticsearch.esql.functions.mv_append(field1, field2)

连接两个多值字段的值。

Parameters:

field1 (Any)
field2 (Any)

Return type:

InstrumentedExpression

elasticsearch.esql.functions.mv_avg(number)

将多值字段转换为包含所有值平均值的单值字段。

Parameters:: number (Any) – 多值表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.mv_concat(string, delim)

将多值字符串表达式转换为单值列，包含由分隔符连接的所有值。

Parameters:

string (Any) – 多值表达式。
delim (Any) – 分隔符。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.mv_count(field)

将多值表达式转换为单值列，包含值的数量统计。

Parameters:: field (Any) – 多值表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.mv_dedupe(field)

从多值字段中移除重复值。

Parameters:: field (Any) – 多值表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.mv_first(field)

将多值表达式转换为单值列，仅包含第一个值。这在从类似`SPLIT`等按已知顺序生成多值列的函数读取时特别有用。

Parameters:: field (Any) – 多值表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.mv_last(field)

将多值表达式转换为单值列，仅包含最后一个值。这在从类似`SPLIT`等按已知顺序生成多值列的函数读取时特别有用。

Parameters:: field (Any) – 多值表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.mv_max(field)

将多值表达式转换为包含最大值的单值列。

Parameters:: field (Any) – 多值表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.mv_median(number)

将多值字段转换为包含中位数的单值字段。

Parameters:: number (Any) – 多值表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.mv_median_absolute_deviation(number)

将多值字段转换为包含中位数绝对偏差的单值字段。计算方式为每个数据点与整个样本中位数的偏差的中位数。即对于随机变量`X`，中位数绝对偏差为`median(|median(X) - X|)`。

Parameters:: number (Any) – 多值表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.mv_min(field)

将多值表达式转换为包含最小值的单值列。

Parameters:: field (Any) – 多值表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.mv_percentile(number, percentile)

将多值字段转换为包含指定百分位观测值的单值字段。

Parameters:

number (Any) – 多值表达式。
percentile (Any) – 要计算的百分位数。必须是0到100之间的数字。超出范围的数值将返回null。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.mv_pseries_weighted_sum(number, p)

通过将输入列表中的每个元素乘以其在P级数中的对应项并计算总和，将多值表达式转换为单值列。

Parameters:

number (Any) – 多值表达式。
p (Any) – 表示P级数中*p*参数的常数。它影响每个元素对加权总和的贡献。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.mv_slice(field, start, end=None)

使用起始和结束索引值返回多值字段的子集。这在从按已知顺序（如`SPLIT`或`MV_SORT`）生成多值列的函数中读取时特别有用。

Parameters:

field (Any) – 多值表达式。如果为`null`，函数返回`null`。
start (Any) – 起始位置。如果为`null`，函数返回`null`。 start参数可以为负数。索引-1表示列表中的最后一个值。
end (Any) – 结束位置（包含）。可选；如果省略，则返回`start`位置的值。 end参数可以为负数。索引-1表示列表中的最后一个值。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.mv_sort(field, order)

按字典序对多值字段进行排序。

Parameters:

field (Any) – 多值表达式。如果为`null`，函数返回`null`。
order (Any) – 排序顺序。有效选项为ASC和DESC，默认为ASC。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.mv_sum(number)

将多值字段转换为包含所有值总和的单值字段。

Parameters:: number (Any) – 多值表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.mv_zip(string1, string2, delim=None)

使用分隔符将两个多值字段的值组合在一起。

Parameters:

string1 (Any) – 多值表达式。
string2 (Any) – 多值表达式。
delim (Any) – 分隔符。可选；如果省略，默认使用`,`作为分隔符。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.now()

返回当前日期和时间。

Return type:: InstrumentedExpression

elasticsearch.esql.functions.percentile(number, percentile)

返回观测值中某个百分位对应的数值。例如，第95百分位是大于95%观测值的数值，第50百分位就是`中位数`。

Parameters:

number (Any)
percentile (Any)

Return type:

InstrumentedExpression

elasticsearch.esql.functions.pi()

返回圆周率π，即圆的周长与直径之比。

Return type:: InstrumentedExpression

elasticsearch.esql.functions.pow(base, exponent)

返回`base`的`exponent`次幂值。

Parameters:

base (Any) – 底数的数值表达式。若为`null`，函数返回`null`。
exponent (Any) – 指数的数值表达式。若为`null`，函数返回`null`。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.qstr(query, options=None)

执行查询字符串搜索。如果提供的查询字符串匹配该行，则返回true。

Parameters:

query (Any) – 采用Lucene查询字符串格式的查询语句。
options (Any) – (可选) 查询字符串函数的附加选项，以命名参数形式传入。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.rate(field)

计数器字段的速率。

Parameters:: field (Any)
Return type:: InstrumentedExpression

elasticsearch.esql.functions.repeat(string, number)

返回通过将`string`与自身连接指定`number`次构造的字符串。

Parameters:

string (Any) – 字符串表达式。
number (Any) – 重复次数。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.replace(string, regex, new_string)

该函数将字符串`str`中正则表达式`regex`的任何匹配项替换为替换字符串`newStr`。

Parameters:

string (Any) – 字符串表达式。
regex (Any) – 正则表达式。
new_string (Any) – 替换字符串。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.reverse(str)

返回表示输入字符串逆序的新字符串。

Parameters:: str (Any) – 字符串表达式。如果为`null`，函数返回`null`。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.right(string, length)

返回从右侧开始从*str*中提取*length*个字符的子字符串。

Parameters:

string (Any) – 要提取子字符串的源字符串。
length (Any) – 要返回的字符数。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.round(number, decimals=None)

将数字四舍五入到指定的小数位数。默认为 0，即返回最接近的整数。如果精度为负数，则舍入到小数点左侧的指定位数。

Parameters:

number (Any) – 要舍入的数值。如果为 null，函数返回 null。
decimals (Any) – 要保留的小数位数。默认为 0。如果为 null，函数返回 null。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.round_to(field, points)

向下舍入到固定点列表中的某个值。

Parameters:

field (Any) – 要舍入的数值。如果为 null，函数返回 null。
points (Any) – 剩余的舍入点。必须为常量。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.rtrim(string)

移除字符串末尾的空白字符。

Parameters:: string (Any) – 字符串表达式。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.sample(field, limit)

收集字段的样本值。

Parameters:

field (Any) – 要收集样本值的字段。
limit (Any) – 要收集的最大样本值数量。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.scalb(d, scale_factor)

返回 d * 2 ^ scaleFactor 的结果，类似于 Java 的 scalb 函数。结果会进行舍入，如同执行了一次正确舍入的浮点乘法运算到双精度值集合中的某个成员。

Parameters:

d (Any) – 乘数的数值表达式。如果为 null，函数返回 null。
scale_factor (Any) – 比例因子的数值表达式。如果为 null，函数返回 null。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.sha1(input)

计算输入数据的 SHA1 哈希值。

Parameters:: input (Any) – 需要哈希的输入数据。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.sha256(input)

计算输入数据的 SHA256 哈希值。

Parameters:: input (Any) – 需要哈希的输入数据。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.signum(number)

返回给定数字的符号。负数返回`-1`，0`返回`0，正数返回`1`。

Parameters:: number (Any) – 数值表达式。如果为`null`，函数返回`null`。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.sin(angle)

返回角度的正弦值。

Parameters:: angle (Any) – 以弧度表示的角度。如果为`null`，函数返回`null`。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.sinh(number)

返回数值的双曲正弦值。

Parameters:: number (Any) – 数值表达式。如果为`null`，函数返回`null`。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.space(number)

返回由`number`个空格组成的字符串。

Parameters:: number (Any) – 结果中的空格数量。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.split(string, delim)

将单值字符串拆分为多个字符串。

Parameters:

string (Any) – 字符串表达式。如果为`null`，函数返回`null`。
delim (Any) – 分隔符。目前仅支持单字节分隔符。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.sqrt(number)

返回数字的平方根。输入可以是任意数值类型，返回值始终为双精度浮点数。负数及无穷大的平方根返回null。

Parameters:: number (Any) – 数值表达式。如果为`null`，函数返回`null`。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.st_centroid_agg(field)

计算空间点几何类型字段的空间质心。

Parameters:: field (Any)
Return type:: InstrumentedExpression

elasticsearch.esql.functions.st_contains(geom_a, geom_b)

返回第一个几何图形是否包含第二个几何图形。这是 ST_WITHIN 函数的逆运算。

Parameters:

geom_a (Any) – 类型为 geo_point、cartesian_point、geo_shape 或 cartesian_shape 的表达式。如果为 null，函数返回 null。
geom_b (Any) – 类型为 geo_point、cartesian_point、geo_shape 或 cartesian_shape 的表达式。如果为 null，函数返回 null。第二个参数必须与第一个参数具有相同的坐标系，这意味着不能混合使用 geo_* 和 cartesian_* 参数。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.st_disjoint(geom_a, geom_b)

返回两个几何图形或几何列是否不相交。这是 ST_INTERSECTS 函数的逆运算。用数学术语表示为： ST_Disjoint(A, B) ⇔ A ⋂ B = ∅

Parameters:

geom_a (Any) – 类型为 geo_point、cartesian_point、geo_shape 或 cartesian_shape 的表达式。如果为 null，函数返回 null。
geom_b (Any) – 类型为 geo_point、cartesian_point、geo_shape 或 cartesian_shape 的表达式。如果为 null，函数返回 null。第二个参数必须与第一个参数具有相同的坐标系，这意味着不能混合使用 geo_* 和 cartesian_* 参数。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.st_distance(geom_a, geom_b)

计算两点之间的距离。对于笛卡尔几何，这是原始坐标相同单位的毕达哥拉斯距离。对于地理几何，这是沿大圆的圆弧距离（以米为单位）。

Parameters:

geom_a (Any) – 类型为 geo_point 或 cartesian_point 的表达式。如果为 null，函数返回 null。
geom_b (Any) – 类型为 geo_point 或 cartesian_point 的表达式。如果为 null，函数返回 null。第二个参数必须与第一个参数具有相同的坐标系，这意味着不能混合使用 geo_point 和 cartesian_point 参数。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.st_envelope(geometry)

确定所提供几何图形的最小边界框。

Parameters:: geometry (Any) – 类型为 geo_point、geo_shape、cartesian_point 或 cartesian_shape 的表达式。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.st_extent_agg(field)

计算具有几何类型字段的空间范围。返回该字段所有值的边界框。

Parameters:: field (Any)
Return type:: InstrumentedExpression

elasticsearch.esql.functions.st_geohash(geometry, precision, bounds=None)

计算指定精度下所提供geo_point的`geohash`。结果为长整型编码。使用ST_GEOHASH_TO_STRING将结果转换为字符串。这些函数与`geo_grid`查询和`geohash_grid`聚合相关。

Parameters:

geometry (Any) – 类型为`geo_point`的表达式。如果为`null`，函数返回`null`。
precision (Any) – 类型为`integer`的表达式。如果为`null`，函数返回`null`。有效值范围为1到12。
bounds (Any) – 可选边界，用于过滤网格瓦片，类型为`BBOX`的`geo_shape`。如果`geo_shape`是其他类型，请使用`ST_ENVELOPE`。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.st_geohash_to_long(grid_id)

将字符串格式的geohash网格ID输入值转换为长整型。

Parameters:: grid_id (Any) – 输入的geohash网格ID。可以是单值或多值列或表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.st_geohash_to_string(grid_id)

将长整型格式的geohash网格ID输入值转换为字符串。

Parameters:: grid_id (Any) – 输入的geohash网格ID。可以是单值或多值列或表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.st_geohex(geometry, precision, bounds=None)

计算指定精度下所提供geo_point的`geohex`（H3单元格ID）。结果为长整型编码。使用ST_GEOHEX_TO_STRING将结果转换为字符串。这些函数与`geo_grid`查询和`geohex_grid`聚合相关。

Parameters:

geometry (Any) – 类型为`geo_point`的表达式。如果为`null`，函数返回`null`。
precision (Any) – 类型为`integer`的表达式。如果为`null`，函数返回`null`。有效值范围为0到15。
bounds (Any) – 可选边界，用于过滤网格瓦片，类型为`BBOX`的`geo_shape`。如果`geo_shape`是其他类型，请使用`ST_ENVELOPE`。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.st_geohex_to_long(grid_id)

将表示字符串格式的geohex网格ID的输入值转换为长整型。

Parameters:: grid_id (Any) – 输入的geohex网格ID。输入可以是单值或多值列或表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.st_geohex_to_string(grid_id)

将表示长整型格式的Geohex网格ID的输入值转换为字符串。

Parameters:: grid_id (Any) – 输入的Geohex网格ID。输入可以是单值或多值列或表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.st_geotile(geometry, precision, bounds=None)

计算指定精度下所提供geo_point的`geotile`。结果为长整型编码。使用ST_GEOTILE_TO_STRING将结果转换为字符串。这些函数与`geo_grid`查询和`geotile_grid`聚合相关。

Parameters:

geometry (Any) – 类型为`geo_point`的表达式。如果为`null`，函数返回`null`。
precision (Any) – 类型为`integer`的表达式。如果为`null`，函数返回`null`。有效值在0到29之间。
bounds (Any) – 可选边界，用于过滤网格瓦片，类型为`BBOX`的`geo_shape`。如果`geo_shape`是其他类型，请使用`ST_ENVELOPE`。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.st_geotile_to_long(grid_id)

将表示字符串格式的geotile网格ID的输入值转换为长整型。

Parameters:: grid_id (Any) – 输入的geotile网格ID。输入可以是单值或多值列或表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.st_geotile_to_string(grid_id)

将表示长整型格式的geotile网格ID的输入值转换为字符串。

Parameters:: grid_id (Any) – 输入的geotile网格ID。输入可以是单值或多值列或表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.st_intersects(geom_a, geom_b)

如果两个几何图形相交则返回 true。当它们有任何共同点（包括内部点，如线上的点或多边形内的点）时即视为相交。这是 ST_DISJOINT 函数的逆运算。用数学术语表示：ST_Intersects(A, B) ⇔ A ⋂ B ≠ ∅

Parameters:

geom_a (Any) – 类型为 geo_point、cartesian_point、geo_shape 或 cartesian_shape 的表达式。如果为 null，函数返回 null。
geom_b (Any) – 类型为 geo_point、cartesian_point、geo_shape 或 cartesian_shape 的表达式。如果为 null，函数返回 null。第二个参数必须与第一个参数使用相同的坐标系，这意味着不能混合使用 geo_* 和 cartesian_* 参数。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.st_within(geom_a, geom_b)

判断第一个几何图形是否完全位于第二个几何图形内部。这是 ST_CONTAINS 函数的逆运算。

Parameters:

geom_a (Any) – 类型为 geo_point、cartesian_point、geo_shape 或 cartesian_shape 的表达式。如果为 null，函数返回 null。
geom_b (Any) – 类型为 geo_point、cartesian_point、geo_shape 或 cartesian_shape 的表达式。如果为 null，函数返回 null。第二个参数必须与第一个参数使用相同的坐标系，这意味着不能混合使用 geo_* 和 cartesian_* 参数。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.st_x(point)

从给定点中提取 x 坐标值。如果点是 geo_point 类型，则等同于提取 longitude 值。

Parameters:: point (Any) – 类型为 geo_point 或 cartesian_point 的表达式。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.st_xmax(point)

从给定几何图形中提取所有 x 坐标的最大值。如果几何图形是 geo_point 或 geo_shape 类型，则等同于提取最大 longitude 值。

Parameters:: point (Any) – 类型为 geo_point、geo_shape、cartesian_point 或 cartesian_shape 的表达式。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.st_xmin(point)

从给定几何图形中提取所有 x 坐标的最小值。如果几何图形是 geo_point 或 geo_shape 类型，则等同于提取最小 longitude 值。

Parameters:: point (Any) – 类型为 geo_point、geo_shape、cartesian_point 或 cartesian_shape 的表达式。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.st_y(point)

从提供的点中提取 y 坐标。如果点是 geo_point 类型，则等同于提取 latitude 值。

Parameters:: point (Any) – 类型为 geo_point 或 cartesian_point 的表达式。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.st_ymax(point)

从提供的几何体中提取 y 坐标的最大值。如果几何体是 geo_point 或 geo_shape 类型，则等同于提取最大 latitude 值。

Parameters:: point (Any) – 类型为 geo_point、geo_shape、cartesian_point 或 cartesian_shape 的表达式。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.st_ymin(point)

从提供的几何体中提取 y 坐标的最小值。如果几何体是 geo_point 或 geo_shape 类型，则等同于提取最小 latitude 值。

Parameters:: point (Any) – 类型为 geo_point、geo_shape、cartesian_point 或 cartesian_shape 的表达式。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.starts_with(str, prefix)

返回一个布尔值，表示关键字字符串是否以另一个字符串开头。

Parameters:

str (Any) – 字符串表达式。如果为`null`，函数返回`null`。
prefix (Any) – 字符串表达式。如果为`null`，函数返回`null`。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.std_dev(number)

数值字段的总体标准差。

Parameters:: number (Any)
Return type:: InstrumentedExpression

elasticsearch.esql.functions.substring(string, start, length=None)

返回字符串的子串，由起始位置和可选长度指定。

Parameters:

string (Any) – 字符串表达式。如果为 null，函数返回 null。
start (Any) – 起始位置。
length (Any) – 从起始位置开始的子串长度。可选；如果省略，则返回 start 之后的所有位置。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.sum(number)

数值表达式的总和。

Parameters:: number (Any)
Return type:: InstrumentedExpression

elasticsearch.esql.functions.tan(angle)

返回角度的正切值。

Parameters:: angle (Any) – 以弧度表示的角度。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.tanh(number)

返回数字的双曲正切值。

Parameters:: number (Any) – 数值表达式。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.tau()

返回圆的周长与半径之比。

Return type:: InstrumentedExpression

elasticsearch.esql.functions.term(field, query)

在指定字段上执行术语查询。如果提供的术语匹配行则返回 true。

Parameters:

field (Any) – 查询将针对的字段。
query (Any) – 希望在指定字段中查找的术语。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.to_aggregate_metric_double(number)

将数值编码为 aggregate_metric_double 类型。

Parameters:: number (Any) – 输入值。可以是单值或多值列，或一个表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_base64(string)

将字符串编码为 base64 字符串。

Parameters:: string (Any) – 字符串。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_boolean(field)

将输入值转换为布尔值。字符串值 true`（不区分大小写）将被转换为布尔值 `true。其他任何值（包括空字符串）都将返回 false。数值 0 会转换为 false，其他数值会转换为 true。

Parameters:: field (Any) – 输入值。可以是单值或多值列，或一个表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_cartesianpoint(field)

将输入值转换为 cartesian_point 值。只有当字符串符合 WKT Point 格式时，才能成功转换。

Parameters:: field (Any) – 输入值。可以是单值或多值列，或一个表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_cartesianshape(field)

将输入值转换为 cartesian_shape 值。只有当字符串符合 WKT 格式时，才能成功转换。

Parameters:: field (Any) – 输入值。可以是单值或多值列，或一个表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_date_nanos(field)

将输入转换为纳秒级精度的日期值（即 date_nanos）。

Parameters:: field (Any) – 输入值。输入可以是单值或多值列或表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_dateperiod(field)

将输入值转换为 date_period 值。

Parameters:: field (Any) – 输入值。输入必须是一个有效的常量日期周期表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_datetime(field)

将输入值转换为日期值。字符串只有在符合 yyyy-MM-dd’T’HH:mm:ss.SSS’Z’ 格式时才能成功转换。要转换其他格式的日期，请使用 DATE_PARSE。

Parameters:: field (Any) – 输入值。输入可以是单值或多值列或表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_degrees(number)

将弧度值转换为角度值。

Parameters:: number (Any) – 输入值。输入可以是单值或多值列或表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_double(field)

将输入值转换为双精度值。如果输入参数是日期类型，其值将被解释为自 Unix 纪元以来的毫秒数并转换为双精度。布尔值 true 将转换为双精度 1.0，false 转换为 0.0。

Parameters:: field (Any) – 输入值。输入可以是单值或多值列或表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_geopoint(field)

将输入值转换为 geo_point 值。字符串只有在符合 WKT Point 格式时才能成功转换。

Parameters:: field (Any) – 输入值。可以是单值或多值列，或表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_geoshape(field)

将输入值转换为 geo_shape 值。字符串只有在符合 WKT 格式时才能成功转换。

Parameters:: field (Any) – 输入值。可以是单值或多值列，或表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_integer(field)

将输入值转换为整数值。如果输入参数是日期类型，其值将被解释为自 Unix 纪元以来的毫秒数并转换为整数。布尔值 true 将转换为整数 1，false 转换为 0。

Parameters:: field (Any) – 输入值。可以是单值或多值列，或表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_ip(field, options=None)

将输入字符串转换为 IP 值。

Parameters:

field (Any) – 输入值。可以是单值或多值列，或表达式。
options (Any) – (可选) 附加选项。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.to_long(field)

将输入值转换为长整型值。如果输入参数是日期类型，其值将被解释为自 Unix 纪元以来的毫秒数并转换为长整型。布尔值 true 将转换为长整型 1，false 转换为 0。

Parameters:: field (Any) – 输入值。可以是单值或多值列，或表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_lower(str)

返回一个新字符串，表示输入字符串转换为小写后的结果。

Parameters:: str (Any) – 字符串表达式。如果为 null，函数返回 null。输入可以是单值列/表达式或多值列/表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_radians(number)

将角度值转换为弧度值。

Parameters:: number (Any) – 输入值。输入可以是单值或多值列，或表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_string(field)

将输入值转换为字符串。

Parameters:: field (Any) – 输入值。输入可以是单值或多值列，或表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_timeduration(field)

将输入值转换为 time_duration 类型值。

Parameters:: field (Any) – 输入值。输入必须是一个有效的时间间隔常量表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_unsigned_long(field)

将输入值转换为无符号长整型值。如果输入参数是日期类型，其值将被解释为自Unix纪元以来的毫秒数并转换为无符号长整型。布尔值 true 将转换为无符号长整型 1，false 转换为 0。

Parameters:: field (Any) – 输入值。输入可以是单值或多值列，或表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_upper(str)

返回一个新字符串，表示转换为大写的输入字符串。

Parameters:: str (Any) – 字符串表达式。如果为 null，函数返回 null。输入可以是单值列或表达式，也可以是多值列或表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.to_version(field)

将输入字符串转换为版本值。

Parameters:: field (Any) – 输入值。输入可以是单值或多值列，或一个表达式。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.top(field, limit, order)

收集字段的顶部值。包含重复值。

Parameters:

field (Any) – 要收集顶部值的字段。
limit (Any) – 要收集的最大值数量。
order (Any) – 计算顶部值的顺序。可选 asc 或 desc。

Return type:

InstrumentedExpression

elasticsearch.esql.functions.trim(string)

移除字符串开头和结尾的空白字符。

Parameters:: string (Any) – 字符串表达式。如果为 null，函数返回 null。
Return type:: InstrumentedExpression

elasticsearch.esql.functions.values(field)

以多值字段形式返回唯一值。返回值的顺序不保证。如果需要有序返回值，请使用 MV_SORT。

Parameters:: field (Any)
Return type:: InstrumentedExpression

elasticsearch.esql.functions.weighted_avg(number, weight)

数值表达式的加权平均值。

Parameters:

number (Any) – 数值。
weight (Any) – 数值权重。

Return type:

InstrumentedExpression