介绍 Python Elasticsearch Client 的 ES|QL 查询构建器

原创于 2025-09-10 09:40:36 发布 · 690 阅读

18 ·

CC 4.0 BY-SA版权

本文为博主原创文章，未经博主允许不得转载。

文章标签：

#elasticsearch #大数据 #搜索引擎 #全文检索 #数据库 #python #开发语言

Elastic 同时被 3 个专栏收录

2028 篇文章

订阅专栏

Elasticsearch

1363 篇文章

订阅专栏

ESQL

51 篇文章

订阅专栏

作者：来自 Elastic Miguel Grinberg

学习如何使用 ES|QL 查询构建器，这是一个新的 Python Elasticsearch client 功能，可以更轻松地使用熟悉的 Python 语法构建 ES|QL 查询。

想要获得 Elastic 认证吗？快来了解下一期 Elasticsearch Engineer 培训什么时候开始！

Elasticsearch 拥有大量新功能，可以帮助你根据使用场景构建最佳搜索解决方案。深入学习我们的示例笔记本，了解更多内容，开始免费云试用，或者立即在本地机器上尝试 Elastic。

我们很高兴地宣布 Python Elasticsearch client 的新 ES|QL 查询构建器模块。有了它，你可以使用熟悉的 Python 语法为 ES|QL 引擎构建查询。

介绍

ES|QL 是一种专门为数据分析设计的查询语言。新的 Python 查询构建器让你可以在 Python 应用中轻松构建和运行 ES|QL 查询。

查询构建器功能在当前版本的 Python Elasticsearch client 中已经可用，从 8.19 版本开始。这个包叫做 elasticsearch，可以用你喜欢的 Python 安装工具安装。例如，下面是使用 pip 安装的方法：

pip install elasticsearch

如果你的应用使用的 Python Elasticsearch client 版本低于 8.19，那么你需要升级它才能使用查询构建器。

在 Python 中创建 ES|QL 查询

下面的示例使用 Python 查询构建器创建一个 ES|QL 查询对象：

from elasticsearch.esql import ESQL

query = (
    ESQL.from_("employees")
    .keep("first_name", "last_name", "height")
    .eval(
        height_feet="height * 3.281",
        height_cm="height * 100",
    )
    .sort("date_hired DESC")
    .limit(3)
)

当打印或转换为字符串时，该对象会生成一个标准的 ES|QL 查询：

>>> print(query)
FROM employees
| KEEP first_name, last_name, height
| EVAL height_feet = height * 3.281, height_cm = height * 100
| SORT date_hired DESC
| LIMIT 3

你可以将 query 对象直接传递给 Python Elasticsearch client 的 ES|QL 端点来执行查询：

from elasticsearch import Elasticsearch
client = Elasticsearch(hosts=[os.environ['ELASTICSEARCH_URL']])
response = client.esql.query(query=str(query))

响应对象包含所有返回列的描述以及结果行：

>>> from pprint import pprint
>>> pprint(response.body)
{'columns': [{'name': 'first_name', 'type': 'text'},
             {'name': 'last_name', 'type': 'text'},
             {'name': 'height', 'type': 'double'},
             {'name': 'height_feet', 'type': 'double'},
             {'name': 'height_cm', 'type': 'double'}],
 'is_partial': False,
 'took': 11,
 'values': [['Adrian', 'Wells', 2.424, 7.953144, 242.4],
            ['Aaron', 'Gonzalez', 1.584, 5.1971, 158.4],
            ['Miranda', 'Kramer', 1.55, 5.08555, 155]]}

Python ES|QL 模块包含所有 ES|QL 命令、函数和操作符的 Python 封装。下一个示例展示了一个使用 LENGTH 函数和条件子句的更高级查询：

from elasticsearch.esql import ESQL, functions

query = (
    ESQL.from_("employees")
    .keep("first_name", "last_name", "height")
    .where(functions.length(E("first_name")) < 4)
)

这是生成的 ES|QL 查询：

>>> print(query)
FROM employees
| KEEP first_name, last_name, height
| WHERE LENGTH(first_name) < 4

想尝试这个功能吗？可以查看 Python Elasticsearch client 文档中关于创建 ES|QL 查询的内容以获取更多信息。

使用 DSL 模块的 ES|QL 查询

ES|QL 查询构建器也集成在 Python Elasticsearch client 的 DSL 模块中。所有文档类都包含 esql_from() 便捷方法来创建基本的 ES|QL 查询。例如，假设已定义 Employee 文档类，可以创建一个查询以返回所有员工（默认情况下 ES|QL 允许的最大结果数为 1000），如下所示：

query = Employee.esql_from()

这个查询对象可以根据需要与额外的 ES|QL 命令链式调用。为了减少查询出错的可能，每当需要引用字段时，可以使用文档类的类属性，而不是使用字符串：

query = (
    Employee.esql_from()
    .where(functions.length(Employee.first_name) < 4)
    .sort(Employee.date_hired.desc())
    .limit(100)
)

如果需要，该查询可以像上面一样进行评估，但文档类提供了 esql_execute() 方法，该方法使用 DSL 模块的管理连接运行查询。此方法还会将原始结果转换为返回文档实例的迭代器：

for emp in Employee.esql_execute(query):
    print(f"{emp.first_name} {emp.last_name} is {emp.height:.2f}m tall")

如果你想了解更多关于 ES|QL 查询构建器与 DSL 模块集成的信息，可以查看我们的 Elastic 文档。

结论

我们希望你在下次需要在 Python 应用中使用 ES|QL 时尝试新的 ES|QL 查询构建器。请注意，该功能目前以技术预览形式发布。如果你有任何问题、反馈或遇到问题，请在 GitHub 上的 Python Elasticsearch client 仓库中创建一个 issue。

原文：https://www.elastic.co/search-labs/blog/esql-query-builder-python-elasticsearch-client