› › ›

API поиска SQL

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

resp = client.sql.query(
    format="txt",
    query="SELECT * FROM library ORDER BY page_count DESC LIMIT 5",
)
print(resp)

const response = await client.sql.query({
  format: "txt",
  query: "SELECT * FROM library ORDER BY page_count DESC LIMIT 5",
});
console.log(response);

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, приоритет будет иметь этот параметр.

Тело запроса

allow_partial_search_results

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

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_mappings

<field-name>

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

Свойства <field-name>

type

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

boolean
composite
date
double
geo_point
ip
keyword
long
lookup

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