Search API позволяет выполнять поисковые запросы и получать результаты, соответствующие запросу. Запросы могут быть предоставлены с использованием параметра строки запроса q или тела запроса.
Параметры пути
<target>
Описание: Необязательный параметр. Список потоков данных, индексов и псевдонимов, разделенных запятыми, для поиска. Поддерживает подстановочные знаки (*). Чтобы искать во всех потоках данных и индексах, опустите этот параметр или используйте * или _all.
Пример:
/my-index-000001/_search/my-index-000001,my-index-000002/_search
Параметры запроса
allow_no_indices
Описание: Необязательный параметр. Если false, запрос возвращает ошибку, если любое выражение с подстановочными знаками, псевдоним индекса или значение _all нацелено только на отсутствующие или закрытые индексы. По умолчанию true.
Пример: allow_no_indices=false
allow_partial_search_results
Описание: Необязательный параметр. Если true, возвращает частичные результаты в случае тайм-аутов или сбоев шардов. По умолчанию true.
Пример: allow_partial_search_results=true
analyzer
Описание: Необязательный параметр. Анализатор для использования в строке запроса. Этот параметр может быть использован только при указании параметра строки запроса q.
Пример: analyzer=standard
analyze_wildcard
Описание: Необязательный параметр. Если true, подстановочные и префиксные запросы анализируются. По умолчанию false. Этот параметр может быть использован только при указании параметра строки запроса q.
Пример: analyze_wildcard=true
batched_reduce_size
Описание: Необязательный параметр. Количество результатов шардов, которые должны быть уменьшены одновременно на координирующем узле. Это значение должно использоваться как механизм защиты для уменьшения накладных расходов памяти на запрос поиска, если потенциальное количество шардов в запросе может быть большим. По умолчанию 512.
Пример: batched_reduce_size=256
ccs_minimize_roundtrips
Описание: Необязательный параметр. Если true, сетевые раунды между координирующим узлом и удаленными кластерами минимизируются при выполнении запросов кросс-кластерного поиска (CCS). По умолчанию true.
Пример: ccs_minimize_roundtrips=true
default_operator
Описание: Необязательный параметр. Оператор по умолчанию для строки запроса: AND или OR. По умолчанию OR. Этот параметр может быть использован только при указании параметра строки запроса q.
Пример: default_operator=AND
df
Описание: Необязательный параметр. Поле для использования по умолчанию, если в строке запроса не указано префикса поля. Этот параметр может быть использован только при указании параметра строки запроса q.
Пример: df=title
docvalue_fields
Описание: Необязательный параметр. Список полей, разделенных запятыми, для возврата в виде представления docvalue для каждого попадания. См. Doc value fields.
Пример: docvalue_fields=field1,field2
expand_wildcards
Описание: Необязательный параметр. Тип индекса, который могут соответствовать шаблоны подстановочных знаков. Если запрос может нацеливаться на потоки данных, этот аргумент определяет, соответствуют ли выражения подстановочных знаков скрытым потокам данных. Поддерживает значения, разделенные запятыми, такие как open,hidden. Допустимые значения:
all- Соответствует любому потоку данных или индексу, включая скрытые.open- Соответствует открытым, не скрытым индексам. Также соответствует любому не скрытому потоку данных.closed- Соответствует закрытым, не скрытым индексам. Также соответствует любому не скрытому потоку данных. Потоки данных не могут быть закрыты.hidden- Соответствует скрытым потокам данных и скрытым индексам. Должен быть комбинирован сopen,closedили обоими.none- Шаблоны подстановочных знаков не принимаются.
Пример: expand_wildcards=open,hidden
explain
Описание: Необязательный параметр. Если true, возвращает подробную информацию о вычислении оценки как часть попадания. По умолчанию false.
Пример: explain=true
from
Описание: Необязательный параметр. Начальное смещение документа. Должно быть неотрицательным и по умолчанию равно 0. По умолчанию вы не можете пролистывать более 10 000 попаданий, используя параметры from и size. Чтобы пролистывать больше попаданий, используйте параметр search_after.
Пример: from=40
ignore_throttled
Описание: Необязательный параметр. Если true, конкретные, расширенные или псевдонимные индексы игнорируются, когда они заморожены. По умолчанию true.
Пример: ignore_throttled=true
include_named_queries_score
Описание: Необязательный параметр. Если true, включает вклад оценки от любых именованных запросов. Эта функциональность повторно запускает каждый именованный запрос для каждого попадания в ответе на поиск. Обычно это добавляет небольшую накладную к запросу. Однако использование вычислительно дорогих именованных запросов на большом количестве попаданий может значительно увеличить накладные расходы. По умолчанию false.
Пример: include_named_queries_score=true
ignore_unavailable
Описание: Необязательный параметр. Если false, запрос возвращает ошибку, если он нацелен на отсутствующий или закрытый индекс. По умолчанию false.
Пример: ignore_unavailable=false
lenient
Описание: Необязательный параметр. Если true, ошибки формата (например, предоставление текста числовому полю) в строке запроса будут игнорироваться. По умолчанию false. Этот параметр может быть использован только при указании параметра строки запроса q.
Пример: lenient=true
max_concurrent_shard_requests
Описание: Необязательный параметр. Определяет количество одновременных запросов к шардам на узел, которые этот поиск выполняет одновременно. Это значение должно использоваться для ограничения воздействия поиска на кластер, чтобы ограничить количество одновременных запросов к шардам. По умолчанию 5.
Пример: max_concurrent_shard_requests=10
pre_filter_shard_size
Описание: Необязательный параметр. Определяет порог, который применяет предварительный фильтр для предварительной фильтрации шардов поиска на основе переписывания запроса, если количество шардов, на которые расширяется запрос поиска, превышает порог. Этот раунд предварительного фильтра может значительно ограничить количество шардов, если, например, шард не может соответствовать ни одному документу на основе его метода переписывания, т.е. если фильтры даты обязательны для соответствия, но границы шарда и запрос не пересекаются. Если не указано, фаза предварительного фильтра выполняется, если выполнено любое из следующих условий:
- Запрос нацелен на более чем 128 шардов.
- Запрос нацелен на один или несколько индексов только для чтения.
- Основная сортировка запроса нацелена на индексированное поле.
Пример: pre_filter_shard_size=100
preference
Описание: Необязательный параметр. Узлы и шарды, используемые для поиска. По умолчанию Elasticsearch выбирает из доступных узлов и шардов, используя адаптивный выбор реплик, учитывая осведомленность о распределении.
Допустимые значения:
_only_local- Выполняет поиск только на шардах на локальном узле._local- Если возможно, выполняет поиск на шардах на локальном узле. Если нет, выбирает шарды, используя метод по умолчанию._only_nodes:<node-id>,<node-id>- Выполняет поиск только на указанных узлах. Если подходящие шарды существуют на более чем одном выбранном узле, использует шарды на этих узлах, используя метод по умолчанию. Если ни один из указанных узлов недоступен, выбирает шарды с любого доступного узла, используя метод по умолчанию._prefer_nodes:<node-id>,<node-id>- Если возможно, выполняет поиск на указанных узлах. Если нет, выбирает шарды, используя метод по умолчанию._shards:<shard>,<shard>- Выполняет поиск только на указанных шардах. Вы можете комбинировать это значение с другими значениями предпочтений. Однако значение_shardsдолжно быть первым. Например:_shards:2,3|_local.<custom-string>- Любая строка, которая не начинается с_. Если состояние кластера и выбранные шарды не изменяются, поиски с использованием одного и того же значения<custom-string>направляются на одни и те же шарды в одном и том же порядке.
Пример: preference=_local
q
Описание: Необязательный параметр. Запрос в синтаксисе строки запроса Lucene. Вы можете использовать параметр q для выполнения поиска по параметрам запроса. Поиски по параметрам запроса не поддерживают полный Elasticsearch Query DSL, но удобны для тестирования. Параметр q переопределяет параметр запроса в теле запроса. Если указаны оба параметра, документы, соответствующие параметру запроса тела запроса, не возвращаются.
Пример: q=user.id:kimchy
request_cache
Описание: Необязательный параметр. Если true, кэширование результатов поиска включено для запросов, где размер равен 0. См. Shard request cache settings. По умолчанию настройки уровня индекса.
Пример: request_cache=true
rest_total_hits_as_int
Описание: Необязательный параметр. Указывает, должны ли попадания.total отображаться как целое число или объект в ответе на поиск. По умолчанию false.
Пример: rest_total_hits_as_int=true
routing
Описание: Необязательный параметр. Пользовательское значение, используемое для маршрутизации операций на конкретный шард.
Пример: routing=user1
scroll
Описание: Необязательный параметр. Период для сохранения контекста поиска для прокрутки. См. Scroll search results. По умолчанию это значение не может превышать 1d (24 часа). Вы можете изменить этот лимит, используя настройку уровня кластера search.max_keep_alive.
Пример: scroll=1m
search_type
Описание: Необязательный параметр. Как рассчитываются распределенные частоты терминов для оценки релевантности. Допустимые значения:
query_then_fetch- (По умолчанию) Распределенные частоты терминов рассчитываются локально для каждого шарда, выполняющего поиск. Мы рекомендуем этот вариант для более быстрых поисков с потенциально менее точной оценкой.dfs_query_then_fetch- Распределенные частоты терминов рассчитываются глобально, используя информацию, собранную со всех шардов, выполняющих поиск. Хотя этот вариант увеличивает точность оценки, он добавляет раунд-трип к каждому шарду, что может привести к более медленным поискам.
Пример: search_type=dfs_query_then_fetch
seq_no_primary_term
Описание: Необязательный параметр. Если true, возвращает номер последовательности и основной термин последнего изменения каждого попадания. См. Optimistic concurrency control.
Пример: seq_no_primary_term=true
size
Описание: Необязательный параметр. Определяет количество возвращаемых попаданий. По умолчанию 10. По умолчанию вы не можете пролистывать более 10 000 попаданий, используя параметры from и size. Чтобы пролистывать больше попаданий, используйте параметр search_after.
Пример: size=20
sort
Описание: Необязательный параметр. Список пар <field>:<direction>, разделенных запятыми.
Пример: sort=age:desc
_source
Описание: Необязательный параметр. Указывает, какие исходные поля возвращаются для соответствующих документов. Эти поля возвращаются в свойстве hits._source ответа на поиск. По умолчанию true. См. source filtering.
Допустимые значения:
true- Возвращается весь исходный документ.false- Исходный документ не возвращается.<string>- Список исходных полей, разделенных запятыми, для возврата. Поддерживаются шаблоны подстановочных знаков (*).
Пример: _source=title,author
_source_excludes
Описание: Необязательный параметр. Список исходных полей, разделенных запятыми, для исключения из ответа. Вы также можете использовать этот параметр для исключения полей из подмножества, указанного в параметре _source_includes. Если параметр _source равен false, этот параметр игнорируется.
Пример: _source_excludes=metadata
_source_includes
Описание: Необязательный параметр. Список исходных полей, разделенных запятыми, для включения в ответ. Если этот параметр указан, возвращаются только эти исходные поля. Вы можете исключить поля из этого подмножества, используя параметр _source_excludes. Если параметр _source равен false, этот параметр игнорируется.
Пример: _source_includes=title,author
stats
Описание: Необязательный параметр. Специфический тег запроса для ведения журнала и статистических целей.
Пример: stats=search_stats
stored_fields
Описание: Необязательный параметр. Список сохраненных полей, разделенных запятыми, для возврата в качестве части попадания. Если поля не указаны, сохраненные поля не включаются в ответ. См. Stored fields. Если это поле указано, параметр _source по умолчанию равен false. Вы можете передать _source: true, чтобы вернуть как исходные поля, так и сохраненные поля в ответе на поиск.
Пример: stored_fields=title,author
suggest_field
Описание: Необязательный параметр. Указывает, какое поле использовать для предложений.
Пример: suggest_field=title
suggest_mode
Описание: Необязательный параметр. Указывает режим предложений. По умолчанию missing. Доступные опции:
always- Всегда возвращать предложения.missing- Возвращать предложения только для отсутствующих терминов.popular- Возвращать предложения только для популярных терминов.
Пример: suggest_mode=always
suggest_size
Описание: Необязательный параметр. Количество предложений для возврата.
Пример: suggest_size=5
suggest_text
Описание: Необязательный параметр. Исходный текст, для которого должны быть возвращены предложения.
Пример: suggest_text=elastic
terminate_after
Описание: Необязательный параметр. Максимальное количество документов для сбора для каждого шарда. Если запрос достигает этого предела, Elasticsearch завершает запрос досрочно. Elasticsearch собирает документы перед сортировкой. Используйте с осторожностью. Elasticsearch применяет этот параметр к каждому шару, обрабатывающему запрос. По возможности, позвольте Elasticsearch выполнять досрочное завершение автоматически. Избегайте указания этого параметра для запросов, нацеленных на потоки данных с резервными индексами на нескольких уровнях данных. По умолчанию 0, что не завершает выполнение запроса досрочно.
Пример: terminate_after=1000
timeout
Описание: Необязательный параметр. Указывает период времени ожидания ответа от каждого шарда. Если ответ не получен до истечения тайм-аута, запрос завершается с ошибкой. По умолчанию тайм-аут не установлен.
Пример: timeout=2s
track_scores
Описание: Необязательный параметр. Если true, рассчитывает и возвращает оценки документов, даже если оценки не используются для сортировки. По умолчанию false.
Пример: track_scores=true
track_total_hits
Описание: Необязательный параметр. Количество попаданий, соответствующих запросу, для точного подсчета. По умолчанию 10000. Если true, возвращается точное количество попаданий за счет некоторого снижения производительности. Если false, ответ не включает общее количество попаданий, соответствующих запросу.
Пример: track_total_hits=true
typed_keys
Описание: Необязательный параметр. Если true, имена агрегаций и предложений в ответе будут иметь префиксы их соответствующих типов. По умолчанию false.
Пример: typed_keys=true
version
Описание: Необязательный параметр. Если true, возвращает версию документа как часть попадания. По умолчанию false.
Пример: version=true
Примеры
Пример запроса
GET /my-index-000001/_search?from=40&size=20
{
"query": {
"term": {
"user.id": "kimchy"
}
}
}Пример ответа
{
"took": 5,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 20,
"relation": "eq"
},
"max_score": 1.3862942,
"hits": [
{
"_index": "my-index-000001",
"_id": "0",
"_score": 1.3862942,
"_source": {
"@timestamp": "2099-11-15T14:12:12",
"http": {
"request": {
"method": "get"
},
"response": {
"status_code": 200,
"bytes": 1070000
},
"version": "1.1"
},
"source": {
"ip": "127.0.0.1"
},
"message": "GET /search HTTP/1.1 200 1070000",
"user": {
"id": "kimchy"
}
}
}
]
}
}
