› › ›

API возможностей полей

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

GET /_field_caps?fields=rating

Запрос

GET /_field_caps?fields=<fields>

POST /_field_caps?fields=<fields>

GET /<target>/_field_caps?fields=<fields>

POST /<target>/_field_caps?fields=<fields>

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

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

Описание

API возможностей полей возвращает информацию о возможностях полей среди нескольких индексов.

API возможностей полей возвращает поля runtime, как и любое другое поле. Например, поле runtime с типом keyword возвращается как любое другое поле, которое принадлежит семейству keyword.

Параметры пути

<target>: (Необязательно, строка) Список потоков данных, индексов и псевдонимов, разделенных запятыми, используемых для ограничения запроса. Поддерживаются подстановки (*). Для задания всех потоков данных и индексов опустите этот параметр или используйте * или _all.

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

fields

(Обязательно, строка) Список полей, для которых нужно получить возможности, разделенных запятыми. Поддерживаются выражения с подстановками (*).

allow_no_indices

(Необязательно, логическое значение) Если false, запрос возвращает ошибку, если какое-либо выражение с подстановкой, псевдоним индекса или _all значение указывает только отсутствующие или закрытые индексы. Это поведение применяется даже если запрос направлен на другие открытые индексы. Например, запрос, направленный на foo*,bar*, возвращает ошибку, если индекс начинается с foo, но ни один индекс не начинается с bar.

По умолчанию true.

expand_wildcards

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

all: Соответствие любому потоку данных или индексу, включая скрытые.
open: Соответствие открытым, нескрываемым индексам. Также соответствует любому открытому, нескрываемому потоку данных.
closed: Соответствие закрытым, нескрываемым индексам. Также соответствует любому нескрываемому потоку данных. Потоки данных не могут быть закрыты.
hidden: Соответствие скрытым потокам данных и скрытым индексам. Должно быть комбинировано с open, closed или обоими.
none: Шаблоны с подстановками не принимаются.

По умолчанию open.

ignore_unavailable

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

include_unmapped

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

Тело запроса

index_filter: (Необязательно, объект запроса Позволяет фильтровать индексы, если предоставленный запрос переписывается в match_none на каждом фрагменте.
runtime_mappings: (Необязательно, объект) Определяет временные поля ad-hoc runtime fields в запросе, аналогично тому, как это делается в запросах поиска. Эти поля существуют только в рамках запроса и имеют приоритет перед полями, определенными с тем же именем в картах индексов.

Тело ответа

Типы, используемые в ответе, описывают семейства типов полей. Как правило, семейство типов совпадает с типом поля, объявленным в схеме, но для упрощения некоторые типы полей, которые ведут себя одинаково, описываются с помощью семейства типов. Например, keyword, constant_keyword и wildcard типы полей описываются как семейство типов keyword.

metadata_field: Зарегистрировано ли это поле как поле метаданных.
searchable: Индексируется ли это поле для поиска во всех индексах.
aggregatable: Можно ли агрегировать это поле по всем индексам.
indices: Список индексов, где это поле имеет то же семейство типов, или null, если все индексы имеют то же семейство типов для поля.
non_searchable_indices: Список индексов, где это поле недоступно для поиска, или null, если все индексы имеют то же определение для поля.
non_aggregatable_indices: Список индексов, где это поле недоступно для агрегирования, или null, если все индексы имеют то же определение для поля.
meta: Объединенные метаданные по всем индексам в виде карты с строковыми ключами и массивами значений. Длина значения 1 указывает, что во всех индексах было одно и то же значение для этого ключа, а длина 2 или более указывает, что не во всех индексах было одно и то же значение для этого ключа.

Примеры

Запрос можно ограничить конкретными потоками данных и индексами:

GET my-index-000001/_field_caps?fields=rating

Следующий пример API-запроса запрашивает информацию о полях rating и title:

GET _field_caps?fields=rating,title

API возвращает следующий ответ:

{
  "indices": [ "index1", "index2", "index3", "index4", "index5" ],
  "fields": {
    "rating": {                                   
      "long": {
        "metadata_field": false,
        "searchable": true,
        "aggregatable": false,
        "indices": [ "index1", "index2" ],
        "non_aggregatable_indices": [ "index1" ]  
      },
      "keyword": {
        "metadata_field": false,
        "searchable": false,
        "aggregatable": true,
        "indices": [ "index3", "index4" ],
        "non_searchable_indices": [ "index4" ]    
      }
    },
    "title": {                                    
      "text": {
        "metadata_field": false,
        "searchable": true,
        "aggregatable": false

      }
    }
  }
}

	Поле `rating` определено как long в `index1` и `index2` и как `keyword` в `index3` и `index4`.
	Поле `rating` не доступно для агрегирования в `index1`.
	Поле `rating` недоступно для поиска в `index4`.
	Поле `title` определено как `text` во всех индексах.

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

GET _field_caps?fields=rating,title&include_unmapped

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

{
  "indices": [ "index1", "index2", "index3" ],
  "fields": {
    "rating": {
      "long": {
        "metadata_field": false,
        "searchable": true,
        "aggregatable": false,
        "indices": [ "index1", "index2" ],
        "non_aggregatable_indices": [ "index1" ]
      },
      "keyword": {
        "metadata_field": false,
        "searchable": false,
        "aggregatable": true,
        "indices": [ "index3", "index4" ],
        "non_searchable_indices": [ "index4" ]
      },
      "unmapped": {                               
        "metadata_field": false,
        "indices": [ "index5" ],
        "searchable": false,
        "aggregatable": false
      }
    },
    "title": {
      "text": {
        "metadata_field": false,
        "indices": [ "index1", "index2", "index3", "index4" ],
        "searchable": true,
        "aggregatable": false
      },
      "unmapped": {                               
        "metadata_field": false,
        "indices": [ "index5" ],
        "searchable": false,
        "aggregatable": false
      }
    }
  }
}

	Поле `rating` несопоставлено в `index5`.
	Поле `title` несопоставлено в `index5`.

Также можно фильтровать индексы с помощью запроса:

POST my-index-*/_field_caps?fields=rating
{
  "index_filter": {
    "range": {
      "@timestamp": {
        "gte": "2018"
      }
    }
  }
}

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

Фильтрация выполняется в лучшем случае, она использует статистику индекса и карты для переписывания запросов на match_none вместо полного выполнения запроса. Например, запрос range по полю date может переписаться в match_none, если все документы в фрагменте (включая удаленные) находятся вне заданного диапазона. Однако не все запросы могут быть переписаны на match_none, поэтому этот API может вернуть индекс, даже если предоставленный фильтр не соответствует ни одному документу.

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