› › ›

API поиска SQL

Возвращает результаты поиска по запросу SQL.

POST _sql?format=txt
{
  "query": "SELECT * FROM library ORDER BY page_count DESC LIMIT 5"
}

Запрос

GET _sql

POST _sql

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

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

Ограничения

См. Ограничения SQL.

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

delimiter

(Необязательно, строка) Разделитель для результатов CSV. По умолчанию ,. API поддерживает этот параметр только для ответов в формате CSV.

format

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

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

Тело запроса

catalog

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

[preview] Эта функциональность находится на стадии технического превью и может быть изменена или удалена в будущих релизах. Elastic будет работать над устранением проблем, но функции на стадии технического превью не подпадают под SLA поддержки официальных функций GA. См. поиск по нескольким кластерам.

columnar

(Необязательно, булево) Если true, возвращает результаты в столбцовом формате. По умолчанию false. API поддерживает этот параметр только для ответов в формате CBOR, JSON, SMILE и YAML. См. Столбцовые результаты.

cursor

(Необязательно, строка) Курсор для получения набора постраничных результатов. Если вы укажете cursor, API использует только параметры columnar и time_zone тела запроса. Другие параметры тела запроса игнорируются.

fetch_size: (Необязательно, целое число) Максимальное количество строк, возвращаемых в ответе. По умолчанию 1000.

field_multi_value_leniency

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

filter

(Необязательно, объект) Query DSL для фильтрации документов для поиска SQL. См. Фильтрация с использованием Elasticsearch Query DSL.

index_include_frozen

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

keep_alive

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

keep_on_completion

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

page_timeout

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

params

(Необязательно, массив) Значения для параметров в query. Синтаксис см. в разделе Передача параметров в запрос.

query

(Обязательно, объект) SQL-запрос для выполнения. Синтаксис см. в разделе Язык SQL.

request_timeout

(Необязательно, значение времени) Таймаут перед тем, как запрос завершится ошибкой. По умолчанию 90s (90 секунд).

runtime_mappings

(Необязательно, объект объектов) Определяет один или несколько runtime-полей в запросе поиска. Эти поля имеют приоритет над сопоставленными полями с тем же именем.

Свойства объектов runtime_mappings

<field-name>

(Обязательно, объект) Настройка runtime-поля. Ключ — имя поля.

Свойства объектов <field-name>

type

(Обязательно, строка) Тип поля, который может быть любым из следующих:

boolean
composite
date
double
geo_point
ip
keyword
long

script

(Необязательно, строка) Painless-скрипт, выполняемый во время запроса. Скрипт имеет доступ ко всему контексту документа, включая исходный _source и любые сопоставленные поля и их значения.

Этот скрипт должен включать emit для возврата вычисленных значений. Например:

"script": "emit(doc['@timestamp'].value.dayOfWeekEnum.toString())"

time_zone

(Необязательно, строка) Идентификатор часового пояса ISO-8601 для поиска. Несколько функций SQL даты/времени используют этот часовой пояс. По умолчанию Z (UTC).

wait_for_completion_timeout

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

Чтобы сохранить синхронный поиск, необходимо указать этот параметр и параметр keep_on_completion.

Тело ответа

API поиска SQL поддерживает несколько форматов ответа. Большинство форматов ответа используют табличную структуру. JSON-ответы содержат следующие свойства:

id

(строка) Идентификатор поиска. Это значение возвращается только для асинхронных и сохранённых синхронных поисков. Для ответов в формате CSV, TSV и TXT это значение возвращается в заголовке HTTP Async-ID.

is_running

(Булево) Если true, поиск всё ещё выполняется. Если false, поиск завершён. Это значение возвращается только для асинхронных и сохранённых синхронных поисков. Для ответов в формате CSV, TSV и TXT это значение возвращается в заголовке HTTP Async-partial.

is_partial

(Булево) Если true, ответ не содержит полных результатов поиска. Если is_partial равно true и is_running равно true, поиск всё ещё выполняется. Если is_partial равно true, но is_running равно false, результаты частичны из-за ошибки или таймаута.

Это значение возвращается только для асинхронных и сохранённых синхронных поисков. Для ответов в формате CSV, TSV и TXT это значение возвращается в заголовке HTTP Async-partial.

rows

(массив массивов) Значения результатов поиска.

columns

(массив объектов) Заголовки столбцов результатов поиска. Каждый объект представляет столбец.

Свойства объектов columns

name: (строка) Название столбца.
type: (строка) Тип данных столбца.

cursor

(строка) Курсор для следующей страницы результатов постраничной выдачи. Для ответов в формате CSV, TSV и TXT это значение возвращается в заголовке HTTP Cursor.

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