› › ›

API многократного поиска

Выполняет несколько поисков с помощью одного запроса API.

GET my-index-000001/_msearch
{ }
{"query" : {"match" : { "message": "this is a test"}}}
{"index": "my-index-000002"}
{"query" : {"match_all" : {}}}

Запрос

GET /<target>/_msearch

Предварительные условия

Если в Elasticsearch включены функции безопасности, у вас должна быть read привилегия индекса для целевого потока данных, индекса или псевдонима. Для межкластерного поиска см. Настройка удалённых кластеров с безопасностью.

Описание

API многократного поиска выполняет несколько поисков по одному запросу API. Формат запроса похож на формат API массовых операций и использует формат JSON с разделителями строк (NDJSON).

Структура следующая:

header\n
body\n
header\n
body\n

Эта структура оптимизирована для снижения расходов на обработку, если конкретный поиск перенаправляется на другой узел.

Последняя строка данных должна завершаться символом новой строки \n. Каждый символ новой строки может предшествовать символу возврата каретки \r. При отправке запросов на этот конечный пункт должна быть установлена заголовок Content-Type со значением application/x-ndjson.

Параметры пути

<target>

(Необязательно, строка) Список потоков данных, индексов и псевдонимов для поиска, разделённый запятыми.

Этот список используется в качестве резервного варианта, если поиск в теле запроса не указывает целевой index объект.

Поддерживаются символы подстановки (*). Для поиска всех потоков данных и индексов в кластере, опустите этот параметр или используйте _all или *.

Параметры запроса

allow_no_indices

(Необязательно, булево) Если false, запрос возвращает ошибку, если какие-либо символы подстановки, псевдонимы индексов, или _all значения, направлены только на отсутствующие или закрытые индексы. Это поведение применяется, даже если запрос направлен на другие открытые индексы. Например, запрос, направленный на foo*,bar*, возвращает ошибку, если индекс начинается с foo, но ни один индекс не начинается с bar.

ccs_minimize_roundtrips

(Необязательно, булево) Если true, сетевые запросы между узлом координации и удалёнными кластерами минимизируются для запросов межкластерного поиска. По умолчанию значение true. См. Как межкластерный поиск обрабатывает задержки сети.

expand_wildcards

(Необязательно, строка) Тип индекса, с которым могут совпадать шаблоны подстановки. Если запрос может нацеливаться на потоки данных, этот аргумент определяет, совпадают ли шаблоны подстановки с скрытыми потоками данных. Поддерживаются значения, разделённые запятыми, например, open,hidden. Допустимые значения:

all: Соответствует любому потоку данных или индексу, включая скрытые.
open: Соответствует открытым, нескрытым индексам. Также соответствует любым нескрытым потокам данных.
closed: Соответствует закрытым, нескрытым индексам. Также соответствует любым нескрытым потокам данных. Потоки данных не могут быть закрыты.
hidden: Соответствует скрытым потокам данных и скрытым индексам. Должен быть объединён с open, closed или обоими.
none: Шаблоны подстановки не принимаются.

По умолчанию open.

ignore_throttled

(Необязательно, булево) Если true, конкретные, расширенные или псевдонимизированные индексы игнорируются при заморозке. По умолчанию true.

ignore_unavailable

(Необязательно, булево) Если false, запрос возвращает ошибку, если он нацелен на отсутствующий или закрытый индекс. По умолчанию false.

max_concurrent_searches

(Необязательно, целое число) Максимальное количество одновременных поисков, которые может выполнить API многократного поиска. По умолчанию max(1, (# of data nodes * min(search thread pool size, 10))).

max_concurrent_shard_requests

(Необязательно, целое число) Максимальное количество одновременных запросов к фрагментам, которые выполняет каждый запрос подпоиска на каждом узле. По умолчанию 5.

Этот параметр можно использовать для предотвращения перегрузки кластера запросом. Например, запрос по умолчанию затрагивает все потоки данных и индексы в кластере. Это может привести к отклонению запросов к фрагментам, если количество фрагментов на узел высокое.

В некоторых сценариях параллелизм не достигается с помощью одновременных запросов. В таких случаях низкое значение этого параметра может привести к низкой производительности. Например, в среде, где ожидается очень небольшое количество одновременных запросов к поиску, более высокое значение этого параметра может повысить производительность.

pre_filter_shard_size

(Необязательно, целое число) Определяет порог, который требует предварительного фильтра roundtrip для предварительного фильтра фрагментов поиска на основе переписывания запроса, если количество фрагментов, к которым обращается запрос поиска, превышает порог. Этот предварительный фильтр roundtrip может значительно ограничить количество фрагментов, если, например, фрагмент не может сопоставить какие-либо документы на основе своего метода переписывания, т.е., если для соответствия обязательны фильтры дат, но границы фрагмента и запрос не пересекаются.

Запрос нацелен на более чем 128 фрагмента.
Запрос нацелен на один или несколько индексов только для чтения.
Основной сортировки запроса направлены на индексированное поле.

rest_total_hits_as_int

(Необязательно, булево) Если true, hits.total возвращаются как целое число в ответе. По умолчанию false, что возвращает объект.

routing

(Необязательно, строка) Пользовательское значение маршрутизации, используемое для маршрутизации операций поиска к определённому фрагменту.

search_type

(Необязательно, строка) Указывает, следует ли использовать глобальные частоты терминов и документов при оценке возвращаемых документов.

Варианты:

query_then_fetch: (по умолчанию) Документы оцениваются с использованием локальных частот терминов и документов для фрагмента. Обычно это быстрее, но менее точно.
dfs_query_then_fetch: Документы оцениваются с использованием глобальных частот терминов и документов по всем фрагментам. Обычно это медленнее, но более точно.

typed_keys

(Необязательно, булево) Указывает, должны ли имена агрегаций и подсказок предваряться соответствующими типами в ответе.

Тело запроса

Тело запроса содержит список запросов поиска, разделенных новой строкой, и объекты поиска <body>.

<header>

(Обязательный, объект) Параметры, используемые для ограничения или изменения поиска.

Этот объект обязателен для каждого тела запроса поиска, но может быть пустым ({}) или содержать пустую строку.

Свойства объектов <header>

allow_no_indices

(Необязательный, логическое значение) Если true, запрос не возвращает ошибку, если выражение с подстановкой или значение _all возвращают только отсутствующие или закрытые индексы.

Этот параметр также относится к псевдонимам, которые указывают на отсутствующий или закрытый индекс.

expand_wildcards

(Необязательный, строка) Тип индекса, с которым могут совпадать шаблоны с подстановкой. Если запрос может нацеливаться на потоки данных, этот аргумент определяет, соответствуют ли выражения с подстановкой скрытым потокам данных. Поддерживаются значения, разделенные запятыми, например, open,hidden. Допустимые значения:

all: Соответствие любому потоку данных или индексу, включая скрытые.
open: Соответствие открытым, нескрытым индексам. Также соответствует любому нескрытому потоку данных.
closed: Соответствие закрытым, нескрытым индексам. Также соответствует любому нескрытому потоку данных. Потоки данных не могут быть закрыты.
hidden: Соответствие скрытым потокам данных и скрытым индексам. Должно быть совмещено с open, closed или обоими.
none: Шаблоны с подстановкой не принимаются.

По умолчанию open.

ignore_unavailable

(Необязательный, логическое значение) Если true, документы из отсутствующих или закрытых индексов не включаются в ответ. По умолчанию false.

index

(Необязательный, строка или массив строк) Потоки данных, индексы и псевдонимы для поиска. Поддерживаются подстановки (*). Укажите несколько целей в виде массива.

Если этот параметр не указан, используется параметр пути запроса <target> в качестве резервного варианта.

preference

(Необязательный, строка) Узел или фрагмент, используемый для выполнения поиска. По умолчанию случайный.

request_cache

(Необязательный, логическое значение) Если true, кэш запросов может быть использован для этого поиска. По умолчанию — настройки уровня индекса. См. Настройки кэша запросов фрагментов.

routing

(Необязательный, строка) Пользовательское значение routing для маршрутизации операций поиска на определенный фрагмент.

search_type

(Необязательный, строка) Указывает, следует ли использовать глобальную частоту терминов и документов при оценке возвращаемых документов.

Варианты:

query_then_fetch: (по умолчанию) Документы оцениваются с использованием локальной частоты терминов и документов для фрагмента. Обычно быстрее, но менее точно.
dfs_query_then_fetch: Документы оцениваются с использованием глобальной частоты терминов и документов по всем фрагментам. Обычно медленнее, но точнее.

<body>

(Необязательный, объект) Содержит параметры для запроса поиска:

Свойства объектов <body>

aggregations: (Необязательный, объект агрегации) Агрегации, которые необходимо выполнить во время поиска. См. Агрегации.
query: (Необязательный, объект DSL-запроса) Запрос, который нужно выполнить во время поиска. В ответе возвращаются совпадения с этим запросом.
from: (Необязательный, целое число) Начальное смещение для возвращаемых совпадений. По умолчанию 0.
size: (Необязательный, целое число) Количество совпадений для возврата. По умолчанию 10.

Тело ответа

responses: (массив) Включает ответ поиска и код состояния для каждого запроса поиска, соответствующего порядку в исходном запросе многократного поиска. Если произошла полная ошибка для определенного запроса поиска, вместо фактического ответа поиска будет возвращен объект с сообщением error и соответствующим кодом состояния.

Примеры

Заголовок включает потоки данных, индексы и псевдонимы для поиска. Заголовок также указывает на search_type, preference и routing. Тело включает типичный запрос тела поиска (включая query, aggregations, from, size и так далее).

$ cat requests
{"index" : "test"}
{"query" : {"match_all" : {}}, "from" : 0, "size" : 10}
{"index" : "test", "search_type" : "dfs_query_then_fetch"}
{"query" : {"match_all" : {}}}
{}
{"query" : {"match_all" : {}}}

{"query" : {"match_all" : {}}}
{"search_type" : "dfs_query_then_fetch"}
{"query" : {"match_all" : {}}}

$ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch --data-binary "@requests"; echo

Обратите внимание, что выше приведен пример пустого заголовка (также может быть просто без содержимого), который также поддерживается.

Этот конечный пункт также позволяет вам выполнять поиск по потокам данных, индексам и псевдонимам в пути запроса. В этом случае он будет использоваться в качестве значения по умолчанию, если явно не указан в параметре заголовка index. Например:

GET my-index-000001/_msearch
{}
{"query" : {"match_all" : {}}, "from" : 0, "size" : 10}
{}
{"query" : {"match_all" : {}}}
{"index" : "my-index-000002"}
{"query" : {"match_all" : {}}}

Вышеприведенное выполнит поиск по индексу my-index-000001 для всех запросов, которые не определяют цель index в теле запроса. Последний поиск будет выполнен по индексу my-index-000002.

search_type может быть задан аналогичным образом для глобального применения ко всем запросам поиска.

Безопасность

См. Управление доступом на основе URL

Частичные ответы

Для обеспечения быстрых ответов API многократного поиска возвращает частичные результаты, если один или несколько фрагментов завершились неудачей. Подробнее см. Ошибки фрагментов.

Отмена поиска

Многократные запросы можно отменить, используя стандартный механизм отмены задач, а также они автоматически отменяются при закрытии клиентом HTTP-соединения, используемого для выполнения запроса. Необходимо, чтобы HTTP-клиент, отправляющий запросы, закрывал соединения всякий раз, когда запросы истекают или прерываются. Отмена запроса msearch также отменяет все соответствующие подзапросы.

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/7.17/search-multi-search.html