Logo
Project Icon

elasticsearch-dsl-py

简化Elasticsearch查询和文档操作的Python高级库

Elasticsearch DSLPython搜索数据库查询Github开源项目

elasticsearch-dsl-py是一个基于官方低级客户端构建的Python高级库，旨在简化Elasticsearch查询的编写和执行。该库提供了更便捷的方式来编写和操作查询，紧密贴合Elasticsearch JSON DSL的术语和结构。它还包含一个可选的文档处理包装器，支持将文档作为Python对象进行操作，包括定义映射、检索和保存等功能。elasticsearch-dsl-py兼容多个Elasticsearch版本，并提供了丰富的示例和详细文档供参考。

访问官网访问官网GithubGithub文档文档
介绍相关项目

Elasticsearch DSL

Elasticsearch DSL是一个高级库，旨在帮助编写和运行针对Elasticsearch的查询。它建立在官方的低级客户端（elasticsearch-py <https://github.com/elastic/elasticsearch-py>_）之上。

它提供了一种更便捷和惯用的方式来编写和操作查询。它紧密贴近Elasticsearch JSON DSL，反映其术语和结构。它通过定义的类或类似查询集的表达式，从Python直接暴露了DSL的全部范围。

它还提供了一个可选的包装器，用于将文档作为Python对象处理：定义映射、检索和保存文档、将文档数据包装在用户定义的类中。

要使用其他Elasticsearch API（如集群健康状况），只需使用底层客户端即可。

安装

::

pip install elasticsearch-dsl

反馈 🗣️

Elastic的工程团队正在寻找开发者参与研究和反馈会议，以了解更多关于您如何使用我们的Python客户端以及我们可以如何改进其设计和您的工作流程。如果您有兴趣分享您对开发者体验和语言客户端设计的见解，请填写这个简短表单_。根据我们收到的回复数量，我们可能会联系您进行一对一对话或与使用相同客户端的其他开发者进行焦点小组讨论。提前感谢您 - 您的反馈对改善所有Elasticsearch开发者的用户体验至关重要！

.. _简短表单: https://forms.gle/bYZwDQXijfhfwshn9

示例

请查看示例目录<https://github.com/elastic/elasticsearch-dsl-py/tree/master/examples>_以查看使用elasticsearch-dsl的一些复杂示例。

兼容性

该库与自2.x以来的所有Elasticsearch版本兼容，但您必须使用匹配的主要版本：

对于Elasticsearch 8.0及更高版本，使用库的主要版本8（8.x.y）。

对于Elasticsearch 7.0及更高版本，使用库的主要版本7（7.x.y）。

对于Elasticsearch 6.0及更高版本，使用库的主要版本6（6.x.y）。

对于Elasticsearch 5.0及更高版本，使用库的主要版本5（5.x.y）。

对于Elasticsearch 2.0及更高版本，使用库的主要版本2（2.x.y）。

在setup.py或requirements.txt中设置要求的推荐方式是：

# Elasticsearch 8.x
elasticsearch-dsl>=8.0.0,<9.0.0

# Elasticsearch 7.x
elasticsearch-dsl>=7.0.0,<8.0.0

# Elasticsearch 6.x
elasticsearch-dsl>=6.0.0,<7.0.0

# Elasticsearch 5.x
elasticsearch-dsl>=5.0.0,<6.0.0

# Elasticsearch 2.x
elasticsearch-dsl>=2.0.0,<3.0.0

开发正在main分支上进行，旧分支只获得错误修复版本。

搜索示例

让我们看一个直接作为dict编写的典型搜索请求：

.. code:: python

from elasticsearch import Elasticsearch
client = Elasticsearch("https://localhost:9200")

response = client.search(
    index="my-index",
    body={
      "query": {
        "bool": {
          "must": [{"match": {"title": "python"}}],
          "must_not": [{"match": {"description": "beta"}}],
          "filter": [{"term": {"category": "search"}}]
        }
      },
      "aggs" : {
        "per_tag": {
          "terms": {"field": "tags"},
          "aggs": {
            "max_lines": {"max": {"field": "lines"}}
          }
        }
      }
    }
)

for hit in response['hits']['hits']:
    print(hit['_score'], hit['_source']['title'])

for tag in response['aggregations']['per_tag']['buckets']:
    print(tag['key'], tag['max_lines']['value'])

这种方法的问题是它非常冗长，容易出现语法错误（如嵌套不正确），难以修改（例如添加另一个过滤器），而且显然不太好写。

让我们使用Python DSL重写这个示例：

.. code:: python

from elasticsearch import Elasticsearch
from elasticsearch_dsl import Search

client = Elasticsearch("https://localhost:9200")

s = Search(using=client, index="my-index") \
    .filter("term", category="search") \
    .query("match", title="python")   \
    .exclude("match", description="beta")

s.aggs.bucket('per_tag', 'terms', field='tags') \
    .metric('max_lines', 'max', field='lines')

response = s.execute()

for hit in response:
    print(hit.meta.score, hit.title)

for tag in response.aggregations.per_tag.buckets:
    print(tag.key, tag.max_lines.value)

如您所见，这个库处理了：

  • 按名称创建适当的Query对象（例如"match"）
  • 将查询组合成一个复合bool查询
  • 将term查询放在bool查询的过滤器上下文中
  • 提供便捷的方式访问响应数据
  • 没有到处使用大括号或方括号

持久化示例

让我们看一个简单的Python类，表示博客系统中的一篇文章：

.. code:: python

from datetime import datetime
from elasticsearch_dsl import Document, Date, Integer, Keyword, Text, connections

# 定义一个默认的Elasticsearch客户端
connections.create_connection(hosts="https://localhost:9200")

class Article(Document):
    title = Text(analyzer='snowball', fields={'raw': Keyword()})
    body = Text(analyzer='snowball')
    tags = Keyword()
    published_from = Date()
    lines = Integer()

    class Index:
        name = 'blog'
        settings = {
          "number_of_shards": 2,
        }

    def save(self, ** kwargs):
        self.lines = len(self.body.split())
        return super(Article, self).save(** kwargs)

    def is_published(self):
        return datetime.now() > self.published_from

# 在elasticsearch中创建映射
Article.init()

# 创建并保存一篇文章
article = Article(meta={'id': 42}, title='Hello world!', tags=['test'])
article.body = ''' 长文本 '''
article.published_from = datetime.now()
article.save()

article = Article.get(id=42)
print(article.is_published())

# 显示集群健康状况
print(connections.get_connection().cluster.health())

在这个示例中，您可以看到：

  • 提供默认连接
  • 定义带有映射配置的字段
  • 设置索引名称
  • 定义自定义方法
  • 重写内置的 .save() 方法以钩入持久化生命周期
  • 将对象检索并保存到 Elasticsearch
  • 访问底层客户端以使用其他 API

您可以在文档的持久化章节中了解更多内容。

从 elasticsearch-py 迁移

您无需移植整个应用程序就能获得 Python DSL 的好处，您可以通过从现有的 dict 创建 Search 对象，使用 API 修改它，然后将其序列化回 dict 来逐步开始：

.. code:: python

body = {...} # 在此插入复杂查询

# 转换为 Search 对象
s = Search.from_dict(body)

# 添加一些过滤器、聚合、查询等
s.filter("term", tags="python")

# 转换回 dict 以插入现有代码中
body = s.to_dict()

开发

激活虚拟环境（virtualenvs <http://docs.python-guide.org/en/latest/dev/virtualenvs/>_）：

.. code:: bash

$ virtualenv venv
$ source venv/bin/activate

要安装开发所需的所有依赖项，请运行：

.. code:: bash

$ pip install -e '.[develop]'

要运行 elasticsearch-dsl-py 的所有测试，请运行：

.. code:: bash

$ python setup.py test

或者，可以使用 test_elasticsearch_dsl 中的 run_tests.py 脚本，它包装了 pytest <http://doc.pytest.org/en/latest/>_，以运行测试套件的子集。以下是一些示例：

.. code:: bash

# 运行 `test_elasticsearch_dsl/test_analysis.py` 中的所有测试
$ ./run_tests.py test_analysis.py

# 仅运行 `test_analyzer_serializes_as_name` 测试
$ ./run_tests.py test_analysis.py::test_analyzer_serializes_as_name

除非有可以连接的 Elasticsearch 实例，否则 pytest 将跳过 test_elasticsearch_dsl/test_integration 中的测试。默认情况下，测试连接尝试在 localhost:9200，基于 elasticsearch-py Connection <https://github.com/elastic/elasticsearch-py/blob/master/elasticsearch/connection/base.py#L29>_ 类中指定的默认值。由于运行集成测试会对 Elasticsearch 集群造成破坏性更改，因此仅在关联集群为空时运行它们。 因此，如果 localhost:9200 的 Elasticsearch 实例不满足这些要求，可以通过 TEST_ES_SERVER 环境变量指定不同的测试 Elasticsearch 服务器。

.. code:: bash

$ TEST_ES_SERVER=my-test-server:9201 ./run_tests

文档

文档可在 https://elasticsearch-dsl.readthedocs.io 获取。

贡献指南

想要参与 Elasticsearch DSL 的开发吗？太棒了！我们有 贡献指南 <https://github.com/elastic/elasticsearch-dsl-py/blob/master/CONTRIBUTING.rst>_。

许可证

版权所有 2013 Elasticsearch

根据 Apache License 2.0 版获得许可（"许可证"）； 除非遵守许可证，否则您不得使用此文件。 您可以在以下位置获取许可证副本：

http://www.apache.org/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则根据许可证分发的软件是基于"按原样"分发的， 不附带任何明示或暗示的担保或条件。 有关许可证下的特定语言管理权限和限制，请参阅许可证。

相关项目
项目侧边栏1项目侧边栏2
推荐项目
Project Cover

豆包MarsCode

豆包 MarsCode 是一款革命性的编程助手，通过AI技术提供代码补全、单测生成、代码解释和智能问答等功能，支持100+编程语言，与主流编辑器无缝集成，显著提升开发效率和代码质量。

Project Cover

AI写歌

Suno AI是一个革命性的AI音乐创作平台，能在短短30秒内帮助用户创作出一首完整的歌曲。无论是寻找创作灵感还是需要快速制作音乐，Suno AI都是音乐爱好者和专业人士的理想选择。

Project Cover

有言AI

有言平台提供一站式AIGC视频创作解决方案，通过智能技术简化视频制作流程。无论是企业宣传还是个人分享，有言都能帮助用户快速、轻松地制作出专业级别的视频内容。

Project Cover

Kimi

Kimi AI助手提供多语言对话支持，能够阅读和理解用户上传的文件内容，解析网页信息，并结合搜索结果为用户提供详尽的答案。无论是日常咨询还是专业问题，Kimi都能以友好、专业的方式提供帮助。

Project Cover

阿里绘蛙

绘蛙是阿里巴巴集团推出的革命性AI电商营销平台。利用尖端人工智能技术，为商家提供一键生成商品图和营销文案的服务，显著提升内容创作效率和营销效果。适用于淘宝、天猫等电商平台，让商品第一时间被种草。

Project Cover

吐司

探索Tensor.Art平台的独特AI模型，免费访问各种图像生成与AI训练工具，从Stable Diffusion等基础模型开始，轻松实现创新图像生成。体验前沿的AI技术，推动个人和企业的创新发展。

Project Cover

SubCat字幕猫

SubCat字幕猫APP是一款创新的视频播放器，它将改变您观看视频的方式！SubCat结合了先进的人工智能技术，为您提供即时视频字幕翻译，无论是本地视频还是网络流媒体，让您轻松享受各种语言的内容。

Project Cover

美间AI

美间AI创意设计平台，利用前沿AI技术，为设计师和营销人员提供一站式设计解决方案。从智能海报到3D效果图，再到文案生成，美间让创意设计更简单、更高效。

Project Cover

稿定AI

稿定设计 是一个多功能的在线设计和创意平台，提供广泛的设计工具和资源，以满足不同用户的需求。从专业的图形设计师到普通用户，无论是进行图片处理、智能抠图、H5页面制作还是视频剪辑，稿定设计都能提供简单、高效的解决方案。该平台以其用户友好的界面和强大的功能集合，帮助用户轻松实现创意设计。

使用协议隐私政策广告服务
投诉举报邮箱: service@vectorlightyear.com
@2024 懂AI·鲁ICP备2024100362号-6·鲁公网安备37021002001498号