作者：来自 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`AI写代码
如果你的应用使用的 Python Elasticsearch client 版本低于 8.19，那么你需要升级它才能使用查询构建器。
在 Python 中创建 ES|QL 查询
下面的示例使用 Python 查询构建器创建一个 ES|QL 查询对象：
`
1. from elasticsearch.esql import ESQL
3. query = (
4. ESQL.from_("employees")
5. .keep("first_name", "last_name", "height")
6. .eval(
7. height_feet="height * 3.281",
8. height_cm="height * 100",
9. )
10. .sort("date_hired DESC")
11. .limit(3)
12. )
`AI写代码
当打印或转换为字符串时，该对象会生成一个标准的 ES|QL 查询：
`
1. >>> print(query)
2. FROM employees
3. | KEEP first_name, last_name, height
4. | EVAL height_feet = height * 3.281, height_cm = height * 100
5. | SORT date_hired DESC
6. | LIMIT 3
`AI写代码
你可以将 query 对象直接传递给 Python Elasticsearch client 的 ES|QL 端点来执行查询：
`
1. from elasticsearch import Elasticsearch
2. client = Elasticsearch(hosts=[os.environ['ELASTICSEARCH_URL']])
3. response = client.esql.query(query=str(query))
`AI写代码
响应对象包含所有返回列的描述以及结果行：
`
1. >>> from pprint import pprint
2. >>> pprint(response.body)
3. {'columns': [{'name': 'first_name', 'type': 'text'},
4. {'name': 'last_name', 'type': 'text'},
5. {'name': 'height', 'type': 'double'},
6. {'name': 'height_feet', 'type': 'double'},
7. {'name': 'height_cm', 'type': 'double'}],
8. 'is_partial': False,
9. 'took': 11,
10. 'values': [['Adrian', 'Wells', 2.424, 7.953144, 242.4],
11. ['Aaron', 'Gonzalez', 1.584, 5.1971, 158.4],
12. ['Miranda', 'Kramer', 1.55, 5.08555, 155]]}
`AI写代码
Python ES|QL 模块包含所有 ES|QL 命令、函数和操作符的 Python 封装。下一个示例展示了一个使用 LENGTH 函数和条件子句的更高级查询：
`
1. from elasticsearch.esql import ESQL, functions
3. query = (
4. ESQL.from_("employees")
5. .keep("first_name", "last_name", "height")
6. .where(functions.length(E("first_name")) < 4)
7. )
`AI写代码
这是生成的 ES|QL 查询：
`
1. >>> print(query)
2. FROM employees
3. | KEEP first_name, last_name, height
4. | WHERE LENGTH(first_name) < 4
`AI写代码
想尝试这个功能吗？可以查看 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()`AI写代码
这个查询对象可以根据需要与额外的 ES|QL 命令链式调用。为了减少查询出错的可能，每当需要引用字段时，可以使用文档类的类属性，而不是使用字符串：
`
1. query = (
2. Employee.esql_from()
3. .where(functions.length(Employee.first_name) < 4)
4. .sort(Employee.date_hired.desc())
5. .limit(100)
6. )
`AI写代码
如果需要，该查询可以像上面一样进行评估，但文档类提供了 esql_execute() 方法，该方法使用 DSL 模块的管理连接运行查询。此方法还会将原始结果转换为返回文档实例的迭代器：
`
1. for emp in Employee.esql_execute(query):
2. print(f"{emp.first_name} {emp.last_name} is {emp.height:.2f}m tall")
`AI写代码
如果你想了解更多关于 ES|QL 查询构建器与 DSL 模块集成的信息，可以查看我们的 Elastic 文档。
结论
我们希望你在下次需要在 Python 应用中使用 ES|QL 时尝试新的 ES|QL 查询构建器。请注意，该功能目前以技术预览形式发布。如果你有任何问题、反馈或遇到问题，请在 GitHub 上的 Python Elasticsearch client 仓库中创建一个 issue。
