› › ›

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

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

resp = client.msearch(
    index="my-index-000001",
    searches=[
        {},
        {
            "query": {
                "match": {
                    "message": "this is a test"
                }
            }
        },
        {
            "index": "my-index-000002"
        },
        {
            "query": {
                "match_all": {}
            }
        }
    ],
)
print(resp)

response = client.msearch(
  index: 'my-index-000001',
  body: [
    {},
    {
      query: {
        match: {
          message: 'this is a test'
        }
      }
    },
    {
      index: 'my-index-000002'
    },
    {
      query: {
        match_all: {}
      }
    }
  ]
)
puts response

const response = await client.msearch({
  index: "my-index-000001",
  searches: [
    {},
    {
      query: {
        match: {
          message: "this is a test",
        },
      },
    },
    {
      index: "my-index-000002",
    },
    {
      query: {
        match_all: {},
      },
    },
  ],
});
console.log(response);

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.

[7.16.0] Устарело в 7.16.0.

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

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

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

rest_total_hits_as_int

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

routing

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

search_type

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

Варианты:

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

typed_keys

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

Тело запроса

Тело запроса содержит список поисковых <header> и поисковых <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

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

search_type

Варианты:

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

<body>

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

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

aggregations: (Необязательно, объект агрегации) Агрегации, которые вы хотите запустить во время поиска. См. Агрегации.
query: (Необязательно, объект языка запросов) Запрос, который вы хотите запустить во время поиска. В ответ возвращаются совпадающие с этим запросом результаты.
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. Например:

resp = client.msearch(
    index="my-index-000001",
    searches=[
        {},
        {
            "query": {
                "match_all": {}
            },
            "from": 0,
            "size": 10
        },
        {},
        {
            "query": {
                "match_all": {}
            }
        },
        {
            "index": "my-index-000002"
        },
        {
            "query": {
                "match_all": {}
            }
        }
    ],
)
print(resp)

response = client.msearch(
  index: 'my-index-000001',
  body: [
    {},
    {
      query: {
        match_all: {}
      },
      from: 0,
      size: 10
    },
    {},
    {
      query: {
        match_all: {}
      }
    },
    {
      index: 'my-index-000002'
    },
    {
      query: {
        match_all: {}
      }
    }
  ]
)
puts response

const response = await client.msearch({
  index: "my-index-000001",
  searches: [
    {},
    {
      query: {
        match_all: {},
      },
      from: 0,
      size: 10,
    },
    {},
    {
      query: {
        match_all: {},
      },
    },
    {
      index: "my-index-000002",
    },
    {
      query: {
        match_all: {},
      },
    },
  ],
});
console.log(response);

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/8.17/search-multi-search.html