› › ›

ES|QL REST API

Обзор

API запросов ES|QL принимает строку запроса ES|QL в параметре query, выполняет её и возвращает результаты. Например:

resp = client.esql.query(
    format="txt",
    query="FROM library | KEEP author, name, page_count, release_date | SORT page_count DESC | LIMIT 5",
)
print(resp)

const response = await client.esql.query({
  format: "txt",
  query:
    "FROM library | KEEP author, name, page_count, release_date | SORT page_count DESC | LIMIT 5",
});
console.log(response);

POST /_query?format=txt
{
  "query": "FROM library | KEEP author, name, page_count, release_date | SORT page_count DESC | LIMIT 5"
}

Что возвращает:

     author      |        name        |  page_count   | release_date
-----------------+--------------------+---------------+------------------------
Peter F. Hamilton|Pandora's Star      |768            |2004-03-02T00:00:00.000Z
Vernor Vinge     |A Fire Upon the Deep|613            |1992-06-01T00:00:00.000Z
Frank Herbert    |Dune                |604            |1965-06-01T00:00:00.000Z
Alastair Reynolds|Revelation Space    |585            |2000-03-15T00:00:00.000Z
James S.A. Corey |Leviathan Wakes     |561            |2011-06-02T00:00:00.000Z

Консоль Kibana

Если вы используете Консоль Kibana (что крайне рекомендуется), воспользуйтесь тройными кавычками """ при создании запроса. Это не только автоматически экранирует двойные кавычки (") внутри строки запроса, но и поддерживает многострочные запросы:

resp = client.esql.query(
    format="txt",
    query="\n    FROM library\n    | KEEP author, name, page_count, release_date\n    | SORT page_count DESC\n    | LIMIT 5\n  ",
)
print(resp)

const response = await client.esql.query({
  format: "txt",
  query:
    "\n    FROM library\n    | KEEP author, name, page_count, release_date\n    | SORT page_count DESC\n    | LIMIT 5\n  ",
});
console.log(response);

POST /_query?format=txt
{
  "query": """
    FROM library
    | KEEP author, name, page_count, release_date
    | SORT page_count DESC
    | LIMIT 5
  """
}

Форматы ответов

ES|QL может возвращать данные в следующих удобочитаемых и двоичных форматах. Вы можете установить формат, указав параметр format в URL или установив заголовок HTTP Accept или Content-Type.

Параметр URL имеет приоритет над заголовками HTTP. Если ни один из них не указан, то ответ возвращается в том же формате, что и запрос.

`format`	Заголовок HTTP	Описание
Удобный для чтения
`csv`	`text/csv`	CSV (Значения, разделённые запятыми)
`json`	`application/json`	JSON (JavaScript Object Notation)
`tsv`	`text/tab-separated-values`	TSV (Значения, разделённые табуляцией)
`txt`	`text/plain`	Представление в стиле командной строки
`yaml`	`application/yaml`	YAML (YAML Ain’t Markup Language)
Двоичный
`cbor`	`application/cbor`	CBOR (Concise Binary Object Representation)
`smile`	`application/smile`	Smile
`arrow`	`application/vnd.apache.arrow.stream`	Экспериментальный. Apache Arrow фреймворки

Формат csv принимает атрибут URL-параметра форматирования, delimiter, который указывает, какой символ следует использовать для разделения значений CSV. По умолчанию это запятая (,) и он не может принимать следующие значения: двойная кавычка ("), возврат каретки (\r) и новая строка (\n). Табуляция (\t) также недоступна. Используйте формат tsv.

Фильтрация с помощью Elasticsearch Query DSL

Укажите запрос Query DSL в параметре filter, чтобы отфильтровать набор документов, на которых выполняется запрос ES|QL.

resp = client.esql.query(
    format="txt",
    query="\n    FROM library\n    | KEEP author, name, page_count, release_date\n    | SORT page_count DESC\n    | LIMIT 5\n  ",
    filter={
        "range": {
            "page_count": {
                "gte": 100,
                "lte": 200
            }
        }
    },
)
print(resp)

const response = await client.esql.query({
  format: "txt",
  query:
    "\n    FROM library\n    | KEEP author, name, page_count, release_date\n    | SORT page_count DESC\n    | LIMIT 5\n  ",
  filter: {
    range: {
      page_count: {
        gte: 100,
        lte: 200,
      },
    },
  },
});
console.log(response);

POST /_query?format=txt
{
  "query": """
    FROM library
    | KEEP author, name, page_count, release_date
    | SORT page_count DESC
    | LIMIT 5
  """,
  "filter": {
    "range": {
      "page_count": {
        "gte": 100,
        "lte": 200
      }
    }
  }
}

Что возвращает:

    author     |                name                |  page_count   | release_date
---------------+------------------------------------+---------------+------------------------
Douglas Adams  |The Hitchhiker's Guide to the Galaxy|180            |1979-10-12T00:00:00.000Z

Столбчатые результаты

По умолчанию ES|QL возвращает результаты как строки. Например, FROM возвращает каждый отдельный документ как одну строку. Для форматов json, yaml, cbor и smile форматов ES|QL может возвращать результаты в столбчатом виде, где одна строка представляет все значения определённого столбца в результатах.

resp = client.esql.query(
    format="json",
    query="\n    FROM library\n    | KEEP author, name, page_count, release_date\n    | SORT page_count DESC\n    | LIMIT 5\n  ",
    columnar=True,
)
print(resp)

const response = await client.esql.query({
  format: "json",
  query:
    "\n    FROM library\n    | KEEP author, name, page_count, release_date\n    | SORT page_count DESC\n    | LIMIT 5\n  ",
  columnar: true,
});
console.log(response);

POST /_query?format=json
{
  "query": """
    FROM library
    | KEEP author, name, page_count, release_date
    | SORT page_count DESC
    | LIMIT 5
  """,
  "columnar": true
}

Что возвращает:

{
  "took": 28,
  "columns": [
    {"name": "author", "type": "text"},
    {"name": "name", "type": "text"},
    {"name": "page_count", "type": "integer"},
    {"name": "release_date", "type": "date"}
  ],
  "values": [
    ["Peter F. Hamilton", "Vernor Vinge", "Frank Herbert", "Alastair Reynolds", "James S.A. Corey"],
    ["Pandora's Star", "A Fire Upon the Deep", "Dune", "Revelation Space", "Leviathan Wakes"],
    [768, 613, 604, 585, 561],
    ["2004-03-02T00:00:00.000Z", "1992-06-01T00:00:00.000Z", "1965-06-01T00:00:00.000Z", "2000-03-15T00:00:00.000Z", "2011-06-02T00:00:00.000Z"]
  ]
}

Возврат локализованных результатов

Используйте параметр locale в теле запроса, чтобы вернуть результаты (особенно даты) в формате, соответствующем соглашениям локали. Если locale не указан, по умолчанию используется en-US (английский). Обратитесь к JDK Поддерживаемые Локали.

Синтаксис: параметр locale принимает теги языка в формате (регистронезависимом) xy и xy-XY.

Например, чтобы вернуть название месяца по-французски:

resp = client.esql.query(
    locale="fr-FR",
    query="\n          ROW birth_date_string = \"2023-01-15T00:00:00.000Z\"\n          | EVAL birth_date = date_parse(birth_date_string)\n          | EVAL month_of_birth = DATE_FORMAT(\"MMMM\",birth_date)\n          | LIMIT 5\n   ",
)
print(resp)

const response = await client.esql.query({
  locale: "fr-FR",
  query:
    '\n          ROW birth_date_string = "2023-01-15T00:00:00.000Z"\n          | EVAL birth_date = date_parse(birth_date_string)\n          | EVAL month_of_birth = DATE_FORMAT("MMMM",birth_date)\n          | LIMIT 5\n   ',
});
console.log(response);

POST /_query
{
  "locale": "fr-FR",
  "query": """
          ROW birth_date_string = "2023-01-15T00:00:00.000Z"
          | EVAL birth_date = date_parse(birth_date_string)
          | EVAL month_of_birth = DATE_FORMAT("MMMM",birth_date)
          | LIMIT 5
   """
}

Передача параметров в запрос

Значения, например для условия, могут быть переданы в запрос "встроенно", интегрировав значение в саму строку запроса:

resp = client.esql.query(
    query="\n    FROM library\n    | EVAL year = DATE_EXTRACT(\"year\", release_date)\n    | WHERE page_count > 300 AND author == \"Frank Herbert\"\n    | STATS count = COUNT(*) by year\n    | WHERE count > 0\n    | LIMIT 5\n  ",
)
print(resp)

const response = await client.esql.query({
  query:
    '\n    FROM library\n    | EVAL year = DATE_EXTRACT("year", release_date)\n    | WHERE page_count > 300 AND author == "Frank Herbert"\n    | STATS count = COUNT(*) by year\n    | WHERE count > 0\n    | LIMIT 5\n  ',
});
console.log(response);

POST /_query
{
  "query": """
    FROM library
    | EVAL year = DATE_EXTRACT("year", release_date)
    | WHERE page_count > 300 AND author == "Frank Herbert"
    | STATS count = COUNT(*) by year
    | WHERE count > 0
    | LIMIT 5
  """
}

Чтобы избежать попыток взлома или вставки кода, извлеките значения в отдельный список параметров. Используйте подстановки знаков вопроса (?) в строке запроса для каждого параметра:

resp = client.esql.query(
    query="\n    FROM library\n    | EVAL year = DATE_EXTRACT(\"year\", release_date)\n    | WHERE page_count > ? AND author == ?\n    | STATS count = COUNT(*) by year\n    | WHERE count > ?\n    | LIMIT 5\n  ",
    params=[
        300,
        "Frank Herbert",
        0
    ],
)
print(resp)

const response = await client.esql.query({
  query:
    '\n    FROM library\n    | EVAL year = DATE_EXTRACT("year", release_date)\n    | WHERE page_count > ? AND author == ?\n    | STATS count = COUNT(*) by year\n    | WHERE count > ?\n    | LIMIT 5\n  ',
  params: [300, "Frank Herbert", 0],
});
console.log(response);

POST /_query
{
  "query": """
    FROM library
    | EVAL year = DATE_EXTRACT("year", release_date)
    | WHERE page_count > ? AND author == ?
    | STATS count = COUNT(*) by year
    | WHERE count > ?
    | LIMIT 5
  """,
  "params": [300, "Frank Herbert", 0]
}

Параметры могут быть именованными или позиционными.

Именованные параметры используют подстановки знаков вопроса (?) в сочетании со строкой.

resp = client.esql.query(
    query="\n    FROM library\n    | EVAL year = DATE_EXTRACT(\"year\", release_date)\n    | WHERE page_count > ?page_count AND author == ?author\n    | STATS count = COUNT(*) by year\n    | WHERE count > ?count\n    | LIMIT 5\n  ",
    params=[
        {
            "page_count": 300
        },
        {
            "author": "Frank Herbert"
        },
        {
            "count": 0
        }
    ],
)
print(resp)

const response = await client.esql.query({
  query:
    '\n    FROM library\n    | EVAL year = DATE_EXTRACT("year", release_date)\n    | WHERE page_count > ?page_count AND author == ?author\n    | STATS count = COUNT(*) by year\n    | WHERE count > ?count\n    | LIMIT 5\n  ',
  params: [
    {
      page_count: 300,
    },
    {
      author: "Frank Herbert",
    },
    {
      count: 0,
    },
  ],
});
console.log(response);

POST /_query
{
  "query": """
    FROM library
    | EVAL year = DATE_EXTRACT("year", release_date)
    | WHERE page_count > ?page_count AND author == ?author
    | STATS count = COUNT(*) by year
    | WHERE count > ?count
    | LIMIT 5
  """,
  "params": [{"page_count" : 300}, {"author" : "Frank Herbert"}, {"count" : 0}]
}

Позиционные параметры используют подстановки знаков вопроса (?) в сочетании с целым числом.

resp = client.esql.query(
    query="\n    FROM library\n    | EVAL year = DATE_EXTRACT(\"year\", release_date)\n    | WHERE page_count > ?1 AND author == ?2\n    | STATS count = COUNT(*) by year\n    | WHERE count > ?3\n    | LIMIT 5\n  ",
    params=[
        300,
        "Frank Herbert",
        0
    ],
)
print(resp)

const response = await client.esql.query({
  query:
    '\n    FROM library\n    | EVAL year = DATE_EXTRACT("year", release_date)\n    | WHERE page_count > ?1 AND author == ?2\n    | STATS count = COUNT(*) by year\n    | WHERE count > ?3\n    | LIMIT 5\n  ',
  params: [300, "Frank Herbert", 0],
});
console.log(response);

POST /_query
{
  "query": """
    FROM library
    | EVAL year = DATE_EXTRACT("year", release_date)
    | WHERE page_count > ?1 AND author == ?2
    | STATS count = COUNT(*) by year
    | WHERE count > ?3
    | LIMIT 5
  """,
  "params": [300, "Frank Herbert", 0]
}

Выполнение асинхронного запроса ES|QL

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

Выполнение запроса ES|QL обычно довольно быстро, однако запросы к большим наборам данных или замороженным данным могут занять некоторое время. Чтобы избежать длительных ожиданий, выполните асинхронный запрос ES|QL.

Запросы, инициированные с помощью API асинхронных запросов, могут вернуть результаты или нет. Свойство wait_for_completion_timeout определяет, как долго ждать результатов. Если результаты недоступны к этому времени, возвращается идентификатор запроса wait_for_completion_timeout, который позже можно использовать для получения результатов. Например:

resp = client.esql.async_query(
    query="\n    FROM library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
    wait_for_completion_timeout="2s",
)
print(resp)

const response = await client.transport.request({
  method: "POST",
  path: "/_query/async",
  body: {
    query:
      "\n    FROM library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
    wait_for_completion_timeout: "2s",
  },
});
console.log(response);

POST /_query/async
{
  "query": """
    FROM library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  """,
  "wait_for_completion_timeout": "2s"
}

Если результаты недоступны в течение заданного времени ожидания, в данном случае 2 секунды, результаты не возвращаются, а возвращается ответ, который включает:

Идентификатор запроса
Значение is_running равное true, что указывает на то, что запрос выполняется

Запрос продолжает выполняться в фоновом режиме без блокировки других запросов.

{
  "id": "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
  "is_running": true
}

Чтобы проверить ход выполнения асинхронного запроса, используйте API получения асинхронных запросов ES|QL с идентификатором запроса. Укажите, сколько времени вы хотите подождать, чтобы получить полные результаты, в параметре wait_for_completion_timeout.

resp = client.esql.async_query_get(
    id="FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
    wait_for_completion_timeout="30s",
)
print(resp)

response = client.esql.async_query_get(
  id: 'FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=',
  wait_for_completion_timeout: '30s'
)
puts response

const response = await client.transport.request({
  method: "GET",
  path: "/_query/async/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE&#x3D;",
  querystring: {
    wait_for_completion_timeout: "30s",
  },
});
console.log(response);

GET /_query/async/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=?wait_for_completion_timeout=30s

Если значение is_running ответа равно false, запрос завершен, и результаты возвращаются вместе со временем took запроса.

{
  "is_running": false,
  "took": 48,
  "columns": ...
}

Используйте ES|QL API асинхронного удаления запроса, чтобы удалить асинхронный запрос до окончания keep_alive периода. Если запрос всё ещё выполняется, Elasticsearch его отменяет.

resp = client.esql.async_query_delete(
    id="FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=",
)
print(resp)

DELETE /_query/async/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=

© 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/esql-rest.html