API 文档

以下是 elasticsearch_dsl 公共类和函数的文档。 异步 API 类在单独的文档中进行说明。

class elasticsearch_dsl.Search(**kwargs: Any)

发送到 Elasticsearch 的搜索请求。

参数：:

• using – 要使用的 Elasticsearch 实例

• index – 将搜索限制为索引

• doc_type – 只查询此类型。

在创建类型时提供（或省略）的所有参数都可以通过方法（分别为 using、index 和 doc_type）在以后进行覆盖。

collapse(field: str | InstrumentedField | None = None, inner_hits: Dict[str, Any] | None = None, max_concurrent_group_searches: int | None = None) → Self

向搜索请求添加折叠信息。如果在不提供 field 的情况下调用，它将删除所有折叠要求，否则它将用提供的参数替换它们。API 返回 Search 对象的副本，因此可以进行链接。

count() → int

返回与查询和过滤器匹配的命中次数。请注意，只返回实际数量。

delete() executes the query by delegating to delete_by_query()

doc_type(*doc_type: type | str, **kwargs: Callable[[AttrDict[Any]], Any]) → Self

设置要搜索的类型。您可以提供单个值或多个值。值可以是字符串或 Document 的子类。

您还可以传递任何关键字参数，将 doc_type 映射到一个回调函数，该回调函数应用于 Hit 类而不是 Hit 类。

如果未提供 doc_type，则将擦除实例上存储的任何信息。

示例

s = Search().doc_type(‘product’, ‘store’, User, custom=my_callback)

execute(ignore_cache: bool = False) → Response[_R]

执行搜索并返回一个 Response 实例，该实例包装所有数据。

参数：:

ignore_cache – 如果设置为 True，连续调用将命中 ES，而缓存结果将被忽略。默认为 False

extra(**kwargs: Any) → Self

向请求主体添加额外的键。主要用于向后兼容。

classmethod from_dict(d: Dict[str, Any]) → Self

从包含搜索主体的原始字典构造一个新的 Search 实例。在从原始字典迁移时很有用。

示例

s = Search.from_dict({
    "query": {
        "bool": {
            "must": [...]
        }
    },
    "aggs": {...}
})
s = s.filter('term', published=True)

highlight(*fields: str | InstrumentedField, **kwargs: Any) → Self

请求突出显示某些字段。传递的所有关键字参数将用作 fields 参数中所有字段的参数。示例

Search().highlight('title', 'body', fragment_size=50)

将生成与以下等效的内容

{
    "highlight": {
        "fields": {
            "body": {"fragment_size": 50},
            "title": {"fragment_size": 50}
        }
    }
}

如果要为不同的字段设置不同的选项，可以调用 highlight 两次

Search().highlight('title', fragment_size=50).highlight('body', fragment_size=100)

这将生成

{
    "highlight": {
        "fields": {
            "body": {"fragment_size": 100},
            "title": {"fragment_size": 50}
        }
    }
}

highlight_options(**kwargs: Any) → Self

更新此请求使用的全局高亮选项。例如

s = Search()
s = s.highlight_options(order='score')

index(*index: str | List[str] | Tuple[str, ...]) → Self

设置搜索的索引。如果为空调用，它将删除所有信息。

示例

s = Search()
s = s.index('twitter-2015.01.01', 'twitter-2015.01.02')
s = s.index(['twitter-2015.01.01', 'twitter-2015.01.02'])

iterate(keep_alive: str = '1m') → Iterator[_R]

返回一个生成器，它迭代所有匹配查询的文档。

此方法使用时间点来提供一致的结果，即使索引正在更改。它应该优先于 scan()。

参数：:

keep_alive – 时间点的生存时间，每次新的搜索请求都会更新

knn(field: str | InstrumentedField, k: int, num_candidates: int, query_vector: List[float] | None = None, query_vector_builder: Dict[str, Any] | None = None, boost: float | None = None, filter: Query | None = None, similarity: float | None = None, inner_hits: Dict[str, Any] | None = None) → Self

添加一个 k-最近邻 (kNN) 搜索。

参数：:

• field – 要搜索的向量字段，作为字符串或文档类属性

• k – 要返回的最近邻数量作为热门结果

• num_candidates – 每个分片要考虑的最近邻候选数量

• query_vector – 要搜索的向量

• query_vector_builder – 指示如何构建查询向量的字典

• boost – kNN 分数的浮点提升因子

• filter – 查询以过滤可以匹配的文档

• similarity – 文档被视为匹配所需的最小相似度，作为浮点值

• inner_hits – 从嵌套字段检索命中

示例

s = Search()
s = s.knn(field='embedding', k=5, num_candidates=10, query_vector=vector,
          filter=Q('term', category='blog')))

params(**kwargs: Any) → Self

指定在执行搜索时要使用的查询参数。所有关键字参数将覆盖当前值。有关所有可用参数，请参见 https://elasticsearch-py.elastic.ac.cn/en/latest/api/elasticsearch.html#elasticsearch.Elasticsearch.search。

示例

s = Search()
s = s.params(routing='user-1', preference='local')

point_in_time(keep_alive: str = '1m') → Iterator[Self]

打开可以在多个搜索中使用的 时间点 (pit)。

此方法实现了一个上下文管理器，它返回一个配置为在创建的 pit 中运行的搜索对象。

参数：:

keep_alive – 时间点的生存时间，每次搜索请求都会更新

rank(rrf: bool | Dict[str, Any] | None = None) → Self

定义了一种方法，用于组合和对来自多个搜索组合的结果集进行排名。需要至少 2 个结果集。

参数：:

rrf – 设置为 True 或选项字典以将排名方法设置为互惠排名融合 (RRF)。

示例

s = Search()
s = s.query('match', content='search text')
s = s.knn(field='embedding', k=5, num_candidates=10, query_vector=vector)
s = s.rank(rrf=True)

注意：此选项处于技术预览阶段，将来可能会更改。语法可能会在 GA 之前更改。

response_class(cls: Type[Response[_R]]) → Self

覆盖用于响应的默认包装器。

scan() → Iterator[_R]

将搜索变成扫描搜索，并返回一个生成器，它将迭代所有匹配查询的文档。

使用 params 方法指定要传递给来自 elasticsearch-py 的底层 scan 帮助程序的任何其他参数 - https://elasticsearch-py.elastic.ac.cn/en/master/helpers.html#elasticsearch.helpers.scan

应该优先使用 iterate() 方法，因为它使用 Elasticsearch 时间点提供类似的功能。

script_fields(**kwargs: Any) → Self

定义要在命中结果上计算的脚本字段。有关更多详细信息，请参见 https://elastic.ac.cn/guide/en/elasticsearch/reference/current/search-request-script-fields.html。

示例

s = Search()
s = s.script_fields(times_two="doc['field'].value * 2")
s = s.script_fields(
    times_three={
        'script': {
            'lang': 'painless',
            'source': "doc['field'].value * params.n",
            'params': {'n': 3}
        }
    }
)

search_after() → Self

返回一个 Search 实例，该实例检索结果的下一页。

此方法提供了一种使用 search_after 选项对长结果列表进行分页的简便方法。例如

page_size = 20
s = Search()[:page_size].sort("date")

while True:
    # get a page of results
    r = await s.execute()

    # do something with this page of results

    # exit the loop if we reached the end
    if len(r.hits) < page_size:
        break

    # get a search object with the next page of results
    s = s.search_after()

请注意，search_after 选项要求搜索具有显式的 sort 顺序。

sort(*keys: str | InstrumentedField | Dict[str, Dict[str, str]]) → Self

向搜索请求添加排序信息。如果在不带参数的情况下调用，它将删除所有排序要求。否则，它将替换它们。可接受的参数是

'some.field'
'-some.other.field'
{'different.field': {'any': 'dict'}}

例如

s = Search().sort(
    'category',
    '-title',
    {"price" : {"order" : "asc", "mode" : "avg"}}
)

将按 category、title（降序）和 price（使用 avg 模式）升序排序。

API 返回 Search 对象的副本，因此可以进行链接。

source(fields: bool | str | InstrumentedField | List[str | InstrumentedField] | Dict[str, List[str | InstrumentedField]] | None = None, **kwargs: Any) → Self

选择性地控制如何返回 _source 字段。

参数：:

• fields – 字段名称、通配符字符串、字段名称或通配符列表，或包含和排除的字典

• kwargs – includes 或 excludes 参数，当 fields 为 None 时。

当没有给出参数时，将为每个命中结果返回整个文档。如果 fields 是字符串或字符串列表，则将包含给定的字段名称或字段通配符。如果 fields 是一个字典，其键为 ‘includes’ 和/或 ‘excludes’，则将相应地包含或排除字段。

使用相同的命名参数多次调用此方法将用新值覆盖先前的值。

示例

s = Search()
s = s.source(includes=['obj1.*'], excludes=["*.description"])

s = Search()
s = s.source(includes=['obj1.*']).source(excludes=["*.description"])

suggest(name: str, text: str | None = None, regex: str | None = None, **kwargs: Any) → Self

向搜索添加建议请求。

参数：:

• name – 建议的名称

• text – 要建议的文本

所有关键字参数都将添加到建议主体中。例如

s = Search()
s = s.suggest('suggestion-1', 'Elasticsearch', term={'field': 'body'})

# Completion Suggester 的正则表达式查询

s = Search() s = s.suggest(‘suggestion-1’, regex=’py[thon|py]’, completion={‘field’: ‘body’})

to_dict(count: bool = False, **kwargs: Any) → Dict[str, Any]

将搜索序列化为将作为请求主体发送的字典。

参数：:

count – 一个标志，用于指定我们是否对计数的正文感兴趣 - 没有聚合、没有分页边界等。

所有额外的关键字参数都将包含在字典中。

update_from_dict(d: Dict[str, Any]) → Self

将序列化主体中的选项应用于当前实例。就地修改对象。主要由 from_dict 使用。

using(client: str | Elasticsearch | AsyncElasticsearch) → Self

将搜索请求与 Elasticsearch 客户端关联。将返回一个新的副本，而当前实例保持不变。

参数：:

client – elasticsearch.Elasticsearch 的实例，或在 elasticsearch_dsl.connections 中查找的别名

class elasticsearch_dsl.MultiSearch(**kwargs: Any)

将多个 Search 对象组合到单个请求中。

add(search: SearchBase[_R]) → Self

向请求添加新的 Search 对象

ms = MultiSearch(index='my-index')
ms = ms.add(Search(doc_type=Category).filter('term', category='python'))
ms = ms.add(Search(doc_type=Blog))

doc_type(*doc_type: type | str, **kwargs: Callable[[AttrDict[Any]], Any]) → Self

设置要搜索的类型。您可以提供单个值或多个值。值可以是字符串或 Document 的子类。

您还可以传递任何关键字参数，将 doc_type 映射到一个回调函数，该回调函数应用于 Hit 类而不是 Hit 类。

如果未提供 doc_type，则将擦除实例上存储的任何信息。

示例

s = Search().doc_type(‘product’, ‘store’, User, custom=my_callback)

execute(ignore_cache: bool = False, raise_on_error: bool = True) → List[Response[_R]]

执行多搜索请求并返回搜索结果列表。

extra(**kwargs: Any) → Self

向请求主体添加额外的键。主要用于向后兼容。

index(*index: str | List[str] | Tuple[str, ...]) → Self

设置搜索的索引。如果为空调用，它将删除所有信息。

示例

s = Search()
s = s.index('twitter-2015.01.01', 'twitter-2015.01.02')
s = s.index(['twitter-2015.01.01', 'twitter-2015.01.02'])

params(**kwargs: Any) → Self

指定在执行搜索时要使用的查询参数。所有关键字参数将覆盖当前值。有关所有可用参数，请参见 https://elasticsearch-py.elastic.ac.cn/en/latest/api/elasticsearch.html#elasticsearch.Elasticsearch.search。

示例

s = Search()
s = s.params(routing='user-1', preference='local')

using(client: str | Elasticsearch | AsyncElasticsearch) → Self

将搜索请求与 Elasticsearch 客户端关联。将返回一个新的副本，而当前实例保持不变。

参数：:

client – elasticsearch.Elasticsearch 的实例，或在 elasticsearch_dsl.connections 中查找的别名

class elasticsearch_dsl.Document(meta: Dict[str, Any] | None = None, **kwargs: Any)

用于在 Elasticsearch 中持久化文档的模型类。

delete(using: str | Elasticsearch | None = None, index: str | None = None, **kwargs: Any) → None

在 Elasticsearch 中删除实例。

参数：:

• index – 要使用的 Elasticsearch 索引，如果 Document 与索引关联，则可以省略。

• using – 要使用的连接别名，默认为 'default'

任何其他关键字参数将被传递给 Elasticsearch.delete 不变。

classmethod exists(id: str, using: str | Elasticsearch | None = None, index: str | None = None, **kwargs: Any) → bool

使用其 id 检查 Elasticsearch 中是否存在单个文档。

参数：:

• id – 要检查是否存在文档的 id

• index – 要使用的 Elasticsearch 索引，如果 Document 与索引关联，则可以省略。

• using – 要使用的连接别名，默认为 'default'

任何其他关键字参数将被传递给 Elasticsearch.exists 不变。

classmethod get(id: str, using: str | Elasticsearch | None = None, index: str | None = None, **kwargs: Any) → Self | None

使用其 id 从 Elasticsearch 中检索单个文档。

参数：:

• id – 要检索的文档的 id

• index – 要使用的 Elasticsearch 索引，如果 Document 与索引关联，则可以省略。

• using – 要使用的连接别名，默认为 'default'

任何其他关键字参数将被传递给 Elasticsearch.get 不变。

classmethod init(index: str | None = None, using: str | Elasticsearch | None = None) → None

在 Elasticsearch 中创建索引并填充映射。

classmethod mget(docs: List[Dict[str, Any]], using: str | Elasticsearch | None = None, index: str | None = None, raise_on_error: bool = True, missing: str = 'none', **kwargs: Any) → List[Self | None]

通过它们的 id 获取多个文档。返回与请求顺序相同的实例列表。

参数：:

• docs – 要检索的文档的 id 列表，或文档规范列表，如 https://elastic.ac.cn/guide/en/elasticsearch/reference/current/docs-multi-get.html 所示

• index – 要使用的 Elasticsearch 索引，如果 Document 与索引关联，则可以省略。

• using – 要使用的连接别名，默认为 'default'

• missing – 当请求的文档之一未找到时该怎么办。有效选项为 'none'（使用 None）、'raise'（引发 NotFoundError）或 'skip'（忽略缺失的文档）。

任何其他关键字参数将被直接传递给 Elasticsearch.mget。

save(using: str | Elasticsearch | None = None, index: str | None = None, validate: bool = True, skip_empty: bool = True, return_doc_meta: bool = False, **kwargs: Any) → Any

将文档保存到 Elasticsearch 中。如果文档不存在，则创建它，否则覆盖它。如果此操作导致创建新文档，则返回 True。

参数：:

• index – 要使用的 Elasticsearch 索引，如果 Document 与索引关联，则可以省略。

• using – 要使用的连接别名，默认为 'default'

• validate – 设置为 False 以跳过验证文档

• skip_empty – 如果设置为 False，将导致空值 (None、[]、{}) 保留在文档上。否则，这些值将被剥离，因为它们在 Elasticsearch 中没有区别。

• return_doc_meta – 设置为 True 以返回更新 API 调用的所有元数据，而不仅仅是操作结果

任何其他关键字参数将被直接传递给 Elasticsearch.index。

返回:

操作结果创建/更新

classmethod search(using: str | Elasticsearch | None = None, index: str | None = None) → Search[Self]

创建一个 Search 实例，它将在这个 Document 上进行搜索。

to_dict(include_meta: bool = False, skip_empty: bool = True) → Dict[str, Any]

将实例序列化为字典，以便它可以保存在 Elasticsearch 中。

参数：:

• include_meta – 如果设置为 True，将包括所有元数据 (_index、_id 等)。否则，只序列化文档的数据。这在将多个实例传递给 elasticsearch.helpers.bulk 时很有用。

• skip_empty – 如果设置为 False，将导致空值 (None、[]、{}) 保留在文档上。否则，这些值将被剥离，因为它们在 Elasticsearch 中没有区别。

update(using: str | Elasticsearch | None = None, index: str | None = None, detect_noop: bool = True, doc_as_upsert: bool = False, refresh: bool = False, retry_on_conflict: int | None = None, script: str | Dict[str, Any] | None = None, script_id: str | None = None, scripted_upsert: bool = False, upsert: Dict[str, Any] | None = None, return_doc_meta: bool = False, **fields: Any) → Any

部分更新文档，指定要更新的字段，实例和 Elasticsearch 中的文档都会被更新。

doc = MyDocument(title='Document Title!')
doc.save()
doc.update(title='New Document Title!')

参数：:

• index – 要使用的 Elasticsearch 索引，如果 Document 与索引关联，则可以省略。

• using – 要使用的连接别名，默认为 'default'

• detect_noop – 设置为 False 以禁用无操作检测。

• refresh – 控制何时将此请求所做的更改对搜索可见。设置为 True 以立即生效。

• retry_on_conflict – 在更新的获取和索引阶段之间，另一个进程可能已经更新了相同的文档。默认情况下，更新将因版本冲突异常而失败。retry_on_conflict 参数控制在最终抛出异常之前重试更新的次数。

• doc_as_upsert – 不发送部分文档和 upsert 文档，将 doc_as_upsert 设置为 true 将使用 doc 的内容作为 upsert 值。

• script – 脚本的源代码作为字符串，或包含脚本属性以更新的字典。

• return_doc_meta – 设置为 True 以返回索引 API 调用的所有元数据，而不仅仅是操作结果。

返回:

操作结果无操作/已更新

class elasticsearch_dsl.Index(name: str, using: str | Elasticsearch = 'default')

参数：:

• name – 索引的名称

• using – 要使用的连接别名，默认为 'default'

aliases(**kwargs: Any) → Self

将别名添加到索引定义中。

i = Index('blog-v2')
i.aliases(blog={}, published={'filter': Q('term', published=True)})

analyze(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

对文本执行分析过程并返回文本的标记分解。

任何其他关键字参数都将原样传递给 Elasticsearch.indices.analyze。

analyzer(*args: Any, **kwargs: Any) → None

显式地将分析器添加到索引中。请注意，映射中定义的所有自定义分析器也将被创建。这对于搜索分析器很有用。

示例

from elasticsearch_dsl import analyzer, tokenizer

my_analyzer = analyzer('my_analyzer',
    tokenizer=tokenizer('trigram', 'nGram', min_gram=3, max_gram=3),
    filter=['lowercase']
)

i = Index('blog')
i.analyzer(my_analyzer)

clear_cache(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

清除与索引关联的所有缓存或特定缓存。

任何其他关键字参数都将原样传递给 Elasticsearch.indices.clear_cache。

clone(name: str | None = None, using: str | Elasticsearch | None = None) → Self

使用另一个名称或连接别名创建实例的副本。这对于使用共享配置创建多个索引很有用。

i = Index('base-index')
i.settings(number_of_shards=1)
i.create()

i2 = i.clone('other-index')
i2.create()

参数：:

• name – 索引的名称

• using – 要使用的连接别名，默认为 'default'

close(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

关闭 Elasticsearch 中的索引。

任何其他关键字参数都将原样传递给 Elasticsearch.indices.close。

create(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

在 Elasticsearch 中创建索引。

任何额外的关键字参数将被传递到 Elasticsearch.indices.create 而不做更改。

delete(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

在 Elasticsearch 中删除索引。

任何额外的关键字参数将被传递到 Elasticsearch.indices.delete 而不做更改。

delete_alias(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

删除特定别名。

任何额外的关键字参数将被传递到 Elasticsearch.indices.delete_alias 而不做更改。

document(document: DocumentMeta) → DocumentMeta

将一个 Document 子类与索引关联。这意味着，当此索引创建时，它将包含 Document 的映射。如果 Document 类还没有默认索引（通过定义 class Index），则将使用此实例。可以用作装饰器。

i = Index('blog')

@i.document
class Post(Document):
    title = Text()

# create the index, including Post mappings
i.create()

# .search() will now return a Search object that will return
# properly deserialized Post instances
s = i.search()

exists(using: str | Elasticsearch | None = None, **kwargs: Any) → bool

如果索引已存在于 Elasticsearch 中，则返回 True。

任何额外的关键字参数将被传递到 Elasticsearch.indices.exists 而不做更改。

exists_alias(using: str | Elasticsearch | None = None, **kwargs: Any) → bool

返回一个布尔值，指示给定别名是否为此索引存在。

任何额外的关键字参数将被传递到 Elasticsearch.indices.exists_alias 而不做更改。

flush(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

对索引执行刷新操作。

任何额外的关键字参数将被传递到 Elasticsearch.indices.flush 而不做更改。

forcemerge(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

force merge API 允许通过 API 强制合并索引。合并与每个分片中 Lucene 索引持有的段数有关。force merge 操作允许通过合并段来减少段数。

此调用将阻塞，直到合并完成。如果 HTTP 连接丢失，请求将在后台继续，任何新的请求都将阻塞，直到之前的 force merge 完成。

任何额外的关键字参数将被传递到 Elasticsearch.indices.forcemerge 而不做更改。

get(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

get index API 允许检索有关索引的信息。

任何额外的关键字参数将被传递到 Elasticsearch.indices.get 而不做更改。

get_alias(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

检索指定的别名。

任何额外的关键字参数将被传递给 Elasticsearch.indices.get_alias 不变。

get_field_mapping(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

检索特定字段的映射定义。

任何额外的关键字参数将被传递给 Elasticsearch.indices.get_field_mapping 不变。

get_mapping(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

检索特定类型特定的映射定义。

任何额外的关键字参数将被传递给 Elasticsearch.indices.get_mapping 不变。

get_settings(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

检索索引的设置。

任何额外的关键字参数将被传递给 Elasticsearch.indices.get_settings 不变。

mapping(mapping: MappingBase) → None

将映射（Mapping 的实例）与该索引关联。这意味着，当创建该索引时，它将包含由这些映射定义的文档类型的映射。

open(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

在 Elasticsearch 中打开索引。

任何额外的关键字参数将被传递给 Elasticsearch.indices.open 不变。

put_alias(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

为索引创建别名。

任何额外的关键字参数将被传递给 Elasticsearch.indices.put_alias 不变。

put_mapping(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

为特定类型注册特定的映射定义。

任何额外的关键字参数将被传递给 Elasticsearch.indices.put_mapping 不变。

put_settings(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

实时更改特定的索引级别设置。

任何额外的关键字参数将被传递给 Elasticsearch.indices.put_settings 不变。

recovery(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

索引恢复 API 提供了对索引正在进行的分片恢复的洞察。

任何额外的关键字参数将被传递给 Elasticsearch.indices.recovery 不变。

refresh(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

对索引执行刷新操作。

任何额外的关键字参数将被传递给 Elasticsearch.indices.refresh 不变。

save(using: str | Elasticsearch | None = None) → ObjectApiResponse[Any] | None

将索引定义与 Elasticsearch 同步，如果索引不存在则创建索引，如果存在则更新其设置和映射。

请注意，某些设置和映射更改无法在打开的索引上进行（或者根本无法在现有索引上进行），对于这些更改，此方法将使用底层异常失败。

search(using: str | Elasticsearch | None = None) → Search

返回一个 Search 对象，该对象在索引（或属于此模板的所有索引）及其 Document 上进行搜索。

segments(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

提供 Lucene 索引（分片级别）构建的低级分段信息。

任何其他关键字参数将被原样传递给 Elasticsearch.indices.segments。

settings(**kwargs: Any) → Self

向索引添加设置

i = Index('i')
i.settings(number_of_shards=1, number_of_replicas=0)

对 settings 的多次调用将合并键，后面的调用会覆盖前面的调用。

shard_stores(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

提供索引的分片副本的存储信息。存储信息报告分片副本存在于哪些节点上、分片副本版本（指示其更新程度）以及打开分片索引或从早期引擎故障中遇到的任何异常。

任何其他关键字参数将被原样传递给 Elasticsearch.indices.shard_stores。

shrink(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

缩减索引 API 允许您将现有索引缩减为具有更少主分片的新索引。目标索引中的主分片数量必须是源索引中分片数量的因子。例如，具有 8 个主分片的索引可以缩减为 4 个、2 个或 1 个主分片，或者具有 15 个主分片的索引可以缩减为 5 个、3 个或 1 个主分片。如果索引中的分片数量是素数，则它只能缩减为单个主分片。在缩减之前，索引中每个分片的（主或副本）副本必须存在于同一个节点上。

任何其他关键字参数将被原样传递给 Elasticsearch.indices.shrink。

stats(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

检索索引上发生的各种操作的统计信息。

任何其他关键字参数将被原样传递给 Elasticsearch.indices.stats。

updateByQuery(using: str | Elasticsearch | None = None) → UpdateByQuery

返回一个 UpdateByQuery 对象，该对象在索引（或属于此模板的所有索引）上进行搜索，并更新与搜索条件匹配的文档。

有关更多信息，请参见：https://elastic.ac.cn/guide/en/elasticsearch/reference/current/docs-update-by-query.html

validate_query(using: str | Elasticsearch | None = None, **kwargs: Any) → ObjectApiResponse[Any]

验证可能很昂贵的查询，而无需执行它。

任何其他关键字参数将被原样传递给 Elasticsearch.indices.validate_query。

class elasticsearch_dsl.FacetedSearch(query: str | Query | None = None, filters: Dict[str, str | datetime | Sequence[str]] = {}, sort: Sequence[str] = [])

参数：:

• query – 要搜索的文本

• filters – 要过滤的 facets 值

• sort – 对要传递给 Search 的信息进行排序

add_filter(name: str, filter_values: str | datetime | Sequence[str] | List[str | datetime | Sequence[str]]) → None

为一个 facet 添加一个过滤器。

aggregate(search: SearchBase[_R]) → None

添加代表所选 facets 的聚合，包括潜在的过滤器。

build_search() → SearchBase[_R]

构建 Search 对象。

execute() → Response[_R]

执行搜索并返回响应。

filter(search: SearchBase[_R]) → SearchBase[_R]

在搜索请求中添加一个 post_filter，根据 facet 过滤器缩小结果范围。

highlight(search: SearchBase[_R]) → SearchBase[_R]

为所有字段添加高亮显示。

params(**kwargs: Any) → None

指定在执行搜索时要使用的查询参数。所有关键字参数将覆盖当前值。有关所有可用参数，请参见 https://elasticsearch-py.elastic.ac.cn/en/master/api.html#elasticsearch.Elasticsearch.search。

query(search: SearchBase[_R], query: str | Query) → SearchBase[_R]

将查询部分添加到 search 中。

如果您希望自定义使用的查询，请覆盖此方法。

search() → Search[_R]

返回添加了 facets 的基本 Search 对象。

您可以通过覆盖此方法并返回修改后的搜索对象来自定义查询。

sort(search: SearchBase[_R]) → SearchBase[_R]

将排序信息添加到请求中。

class elasticsearch_dsl.UpdateByQuery(**kwargs: Any)

对 Elasticsearch 进行更新查询请求。

参数：:

• using – 要使用的 Elasticsearch 实例

• index – 将搜索限制为索引

• doc_type – 只查询此类型。

在创建类型时提供（或省略）的所有参数都可以通过方法（分别为 using、index 和 doc_type）在以后进行覆盖。

doc_type(*doc_type: type | str, **kwargs: Callable[[AttrDict[Any]], Any]) → Self

设置要搜索的类型。您可以提供单个值或多个值。值可以是字符串或 Document 的子类。

您还可以传递任何关键字参数，将 doc_type 映射到一个回调函数，该回调函数应用于 Hit 类而不是 Hit 类。

如果未提供 doc_type，则将擦除实例上存储的任何信息。

示例

s = Search().doc_type(‘product’, ‘store’, User, custom=my_callback)

execute() → UpdateByQueryResponse[_R]

执行搜索并返回一个 Response 实例，该实例包装所有数据。

extra(**kwargs: Any) → Self

向请求主体添加额外的键。主要用于向后兼容。

classmethod from_dict(d: Dict[str, Any]) → Self

从包含搜索主体的原始字典中构建一个新的 UpdateByQuery 实例。在从原始字典迁移时很有用。

示例

ubq = UpdateByQuery.from_dict({
    "query": {
        "bool": {
            "must": [...]
        }
    },
    "script": {...}
})
ubq = ubq.filter('term', published=True)

index(*index: str | List[str] | Tuple[str, ...]) → Self

设置搜索的索引。如果为空调用，它将删除所有信息。

示例

s = Search()
s = s.index('twitter-2015.01.01', 'twitter-2015.01.02')
s = s.index(['twitter-2015.01.01', 'twitter-2015.01.02'])

params(**kwargs: Any) → Self

指定在执行搜索时要使用的查询参数。所有关键字参数将覆盖当前值。有关所有可用参数，请参见 https://elasticsearch-py.elastic.ac.cn/en/latest/api/elasticsearch.html#elasticsearch.Elasticsearch.search。

示例

s = Search()
s = s.params(routing='user-1', preference='local')

response_class(cls: Type[UpdateByQueryResponse[_R]]) → Self

覆盖用于响应的默认包装器。

script(**kwargs: Any) → Self

定义要执行的更新操作：https://elastic.ac.cn/guide/en/elasticsearch/reference/current/modules-scripting-using.html 了解更多详情。

注意：API 仅接受单个脚本，因此多次调用脚本将覆盖之前的脚本。

示例

ubq = Search()
ubq = ubq.script(source="ctx._source.likes++"")
ubq = ubq.script(source="ctx._source.likes += params.f"",
             lang="expression",
             params={'f': 3})

to_dict(**kwargs: Any) → Dict[str, Any]

将搜索序列化为字典，该字典将作为请求的 ubq 主体发送。

所有额外的关键字参数都将包含在字典中。

update_from_dict(d: Dict[str, Any]) → Self

将序列化主体中的选项应用于当前实例。就地修改对象。主要由 from_dict 使用。

using(client: str | Elasticsearch | AsyncElasticsearch) → Self

将搜索请求与 Elasticsearch 客户端关联。将返回一个新的副本，而当前实例保持不变。

参数：:

client – elasticsearch.Elasticsearch 的实例，或在 elasticsearch_dsl.connections 中查找的别名

映射

如果您希望手动创建映射，可以使用 Mapping 类，对于更高级的用例，我们建议您将 Document 抽象与 Index（或 IndexTemplate）结合使用来定义索引级设置和属性。映射定义遵循与查询 dsl 类似的模式。

from elasticsearch_dsl import Keyword, Mapping, Nested, Text

# name your type
m = Mapping()

# add fields
m.field('title', 'text')

# you can use multi-fields easily
m.field('category', 'text', fields={'raw': Keyword()})

# you can also create a field manually
comment = Nested(
                 properties={
                    'author': Text(),
                    'created_at': Date()
                 })

# and attach it to the mapping
m.field('comments', comment)

# you can also define mappings for the meta fields
m.meta('_all', enabled=False)

# save the mapping into index 'my-index'
m.save('my-index')

注意

默认情况下，所有字段（除了 Nested）都将期望单个值。您始终可以在字段创建/定义期间通过将 multi=True 传递到构造函数中 (m.field('tags', Keyword(multi=True))) 来覆盖此期望。然后，即使未设置字段，字段的值也将是一个空列表，使您能够编写 doc.tags.append('search')。

特别是如果您使用动态映射，根据 Elasticsearch 中的现有类型更新映射或直接从现有类型创建映射可能很有用。

# get the mapping from our production cluster
m = Mapping.from_es('my-index', using='prod')

# update based on data in QA cluster
m.update_from_es('my-index', using='qa')

# update the mapping on production
m.save('my-index', using='prod')

常见字段选项

multi

如果设置为 True，则字段的值将在首次访问时设置为 []。

required

指示文档是否需要字段值才能有效。