Spec-Zone.ru › Elasticsearch 8
›Руководство по Elasticsearch [8.17] ›REST API ›API поиска

Асинхронный поиск

Новая справка по API

Для получения самых последних данных об API обратитесь к API поиска.

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

API отправки асинхронного поиска

Выполняет запрос поиска асинхронно. Принимает те же параметры и тело запроса, что и API поиска.

resp = client.async_search.submit(
    index="sales*",
    size="0",
    sort=[
        {
            "date": {
                "order": "asc"
            }
        }
    ],
    aggs={
        "sale_date": {
            "date_histogram": {
                "field": "date",
                "calendar_interval": "1d"
            }
        }
    },
)
print(resp)
response = client.async_search.submit(
  index: 'sales*',
  size: 0,
  body: {
    sort: [
      {
        date: {
          order: 'asc'
        }
      }
    ],
    aggregations: {
      sale_date: {
        date_histogram: {
          field: 'date',
          calendar_interval: '1d'
        }
      }
    }
  }
)
puts response
const response = await client.asyncSearch.submit({
  index: "sales*",
  size: 0,
  sort: [
    {
      date: {
        order: "asc",
      },
    },
  ],
  aggs: {
    sale_date: {
      date_histogram: {
        field: "date",
        calendar_interval: "1d",
      },
    },
  },
});
console.log(response);
POST /sales*/_async_search?size=0
{
  "sort": [
    { "date": { "order": "asc" } }
  ],
  "aggs": {
    "sale_date": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "1d"
      }
    }
  }
}

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

{
  "id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=", 
  "is_partial" : true, 
  "is_running" : true, 
  "start_time_in_millis" : 1583945890986,
  "expiration_time_in_millis" : 1584377890986,
  "response" : {
    "took" : 1122,
    "timed_out" : false,
    "num_reduce_phases" : 0,
    "_shards" : {
      "total" : 562, 
      "successful" : 3, 
      "skipped" : 0,
      "failed" : 0
    },
    "hits" : {
      "total" : {
        "value" : 157483, 
        "relation" : "gte"
      },
      "max_score" : null,
      "hits" : [ ]
    }
  }
}

Идентификатор асинхронного поиска, который можно использовать для отслеживания его прогресса, получения результатов и/или удаления.

Когда запрос больше не выполняется, указывает, завершился ли поиск успешно на всех фрагментах или произошла ошибка. Пока запрос выполняется, is_partial всегда устанавливается в значение true

Указывает, выполняется ли поиск или он завершен.

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

Количество успешно завершенных фрагментов поиска.

Количество документов, которые в данный момент соответствуют запросу и относятся к фрагментам, которые уже завершили поиск.

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

Можно заблокировать и дождаться завершения поиска до определенного таймаута, задав параметр wait_for_completion_timeout, который по умолчанию равен 1 секундам. Если асинхронный поиск завершается в течение этого таймаута, идентификатор в ответе не будет включен, так как результаты не хранятся в кластере. Параметр keep_on_completion, который по умолчанию равен false, может быть установлен в значение true, чтобы запросить хранение результатов для последующего извлечения, даже если поиск завершается в течение таймаута wait_for_completion_timeout.

Также можно указать, как долго асинхронный поиск должен быть доступен, используя параметр keep_alive, который по умолчанию равен 5d (пять дней). Незавершенные асинхронные поиски и сохранённые результаты поиска удаляются по истечении этого срока.

Когда первичная сортировка результатов основана на индексированном поле, фрагменты сортируются на основе минимального и максимального значения, которые они содержат для этого поля, поэтому частичные результаты становятся доступными в соответствии с критериями сортировки, которые были запрошены.

API отправки асинхронного поиска поддерживает те же параметры, что и API поиска, хотя некоторые имеют разные значения по умолчанию:

  • batched_reduce_size по умолчанию устанавливается в значение 5: это влияет на частоту появления частичных результатов, что происходит всякий раз, когда результаты фрагментов сводятся. Частичное сведение выполняется каждый раз, когда координирующий узел получает определенное количество новых ответов от фрагментов (5 по умолчанию).
  • request_cache по умолчанию устанавливается в значение true
  • pre_filter_shard_size по умолчанию устанавливается в значение 1 и его нельзя изменить: это делается для обеспечения выполнения предварительного фильтра, чтобы получить статистику от каждого фрагмента, таким образом, фрагменты, которые, безусловно, не содержат документов, соответствующих запросу, пропускаются.
  • ccs_minimize_roundtrips по умолчанию устанавливается в значение false. При выполнении межкластерного поиска установка его в значение true может улучшить общую задержку поиска, особенно при поиске в кластерах с большим количеством фрагментов. Однако, если установить его в значение true, прогресс поиска в удалённых кластерах не будет получен до завершения поиска во всех кластерах. См. Поиск по нескольким кластерам для получения дополнительной информации.

Асинхронный поиск не поддерживает прокрутку ни запросы поиска, включающие только блок подсказок.

По умолчанию Elasticsearch не позволяет хранить ответ асинхронного поиска больше, чем 10 Мб, и попытка сделать это приводит к ошибке. Максимально допустимый размер сохранённого ответа асинхронного поиска можно изменить, изменив настройку уровня кластера search.max_async_search_response_size.

Получение асинхронного поиска

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

Если функции безопасности Elasticsearch включены, доступ к результатам конкретного асинхронного поиска разрешен только пользователю или API-ключу, который его отправил.

resp = client.async_search.get(
    id="FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
)
print(resp)
response = client.async_search.get(
  id: 'FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc='
)
puts response
const response = await client.asyncSearch.get({
  id: "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
});
console.log(response);
GET /_async_search/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=
{
  "id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
  "is_partial" : false, 
  "is_running" : false, 
  "start_time_in_millis" : 1583945890986,
  "expiration_time_in_millis" : 1584377890986, 
  "completion_time_in_millis" : 1583945903130, 
  "response" : {
    "took" : 12144,
    "timed_out" : false,
    "num_reduce_phases" : 46, 
    "_shards" : {
      "total" : 562,
      "successful" : 188, 
      "skipped" : 0,
      "failed" : 0
    },
    "hits" : {
      "total" : {
        "value" : 456433,
        "relation" : "eq"
      },
      "max_score" : null,
      "hits" : [ ]
    },
    "aggregations" : { 
      "sale_date" :  {
        "buckets" : []
      }
    }
  }
}

Когда запрос больше не выполняется, указывает, завершился ли поиск успешно на всех фрагментах или произошла ошибка. Пока запрос выполняется, is_partial всегда установлено в значение true

Указывает, выполняется ли поиск или он завершен.

Время истечения срока действия асинхронного поиска.

Когда асинхронный поиск завершился, указывается время завершения (время начала + время выполнения).

Указывает, сколько раз были выполнены сводки результатов. Если это число увеличилось по сравнению с последними полученными результатами, можно ожидать дополнительных результатов в ответе поиска.

Указывает, сколько фрагментов выполнили запрос. Обратите внимание, что для включения результатов фрагментов в ответ поиска они должны быть предварительно свёрнуты.

Частичные результаты агрегаций, полученные из фрагментов, которые уже завершили выполнение запроса.

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

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

Получение статуса асинхронного поиска

API get async search status, не возвращая результаты поиска, показывает только статус ранее отправленного запроса асинхронного поиска, заданного его id.

Если функции безопасности Elasticsearch включены, доступ к статусу конкретного асинхронного поиска ограничен:

  • Пользователем или API ключом, который отправил исходный запрос асинхронного поиска.
  • Пользователями, имеющими привилегию кластера monitor или выше.

Также можно указать, как долго асинхронный поиск должен быть доступен, через параметр keep_alive, который по умолчанию равен 5d (пять дней). Незавершенные асинхронные поиски и сохраненные результаты поиска удаляются после этого периода.

resp = client.async_search.status(
    id="FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
)
print(resp)
response = client.async_search.status(
  id: 'FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc='
)
puts response
const response = await client.asyncSearch.status({
  id: "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
});
console.log(response);
GET /_async_search/status/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=
{
  "id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
  "is_running" : true,
  "is_partial" : true,
  "start_time_in_millis" : 1583945890986,
  "expiration_time_in_millis" : 1584377890986,
  "_shards" : {
      "total" : 562,
      "successful" : 188, 
      "skipped" : 0,
      "failed" : 0
  }
}

Указывает, сколько фрагментов выполнили запрос до сих пор.

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

{
  "id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
  "is_running" : false,
  "is_partial" : false,
  "start_time_in_millis" : 1583945890986,
  "expiration_time_in_millis" : 1584377890986,
  "_shards" : {
      "total" : 562,
      "successful" : 562,
      "skipped" : 0,
      "failed" : 0
  },
 "completion_status" : 200 
}

Указывает, что асинхронный поиск был успешно завершен.

 
{
  "id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
  "is_running" : false,
  "is_partial" : true,
  "start_time_in_millis" : 1583945890986,
  "expiration_time_in_millis" : 1584377890986,
  "_shards" : {
      "total" : 562,
      "successful" : 450,
      "skipped" : 0,
      "failed" : 112
  },
 "completion_status" : 503 
}

Указывает, что асинхронный поиск был завершен с ошибкой.

Удаление асинхронного поиска

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

resp = client.async_search.delete(
    id="FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
)
print(resp)
response = client.async_search.delete(
  id: 'FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc='
)
puts response
const response = await client.asyncSearch.delete({
  id: "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
});
console.log(response);
DELETE /_async_search/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=

Если функции безопасности Elasticsearch включены, удаление конкретного асинхронного поиска ограничено:

  • Пользователем или API ключом, который отправил исходный запрос асинхронного поиска.
  • Пользователями, имеющими привилегию кластера cancel_task или выше.

© 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/async-search.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API