Spec-Zone.ru › Elasticsearch 8
›Руководство по Elasticsearch [8.17] ›REST API ›API поиска

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

Справочник по новому API

Для получения самых последних данных об API обратитесь к API поиска.

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

resp = client.field_caps(
    fields="rating",
)
print(resp)
response = client.field_caps(
  fields: 'rating'
)
puts response
const response = await client.fieldCaps({
  fields: "rating",
});
console.log(response);
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.
include_empty_fields
(Необязательно, логическое значение) Если false, поля, которые никогда не имели значения ни в одном фрагменте, не включаются в ответ. Поля, которые не пустые, всегда включаются. Этот флаг не учитывает удаления и обновления. Если поле было не пустым, и все документы, содержащие это поле, были удалены или поле было удалено путем обновления, оно по-прежнему будет возвращено, даже если флаг равен false. По умолчанию true.
filters

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

Допустимые значения для filters
+metadata
Включать только метаданные полей
-metadata
Исключить метаданные полей
-parent
Исключить родительские поля
-nested
Исключить вложенные поля
-multifield
Исключить многопольные поля
types
(Необязательно, строка) Список типов полей, разделенных запятыми, которые следует включить. Любые поля, которые не соответствуют одному из этих типов, будут исключены из результатов. По умолчанию пустое значение, что означает, что возвращаются все типы полей. Более подробную информацию о типах полей в запросах и ответах об API возможностей полей см. здесь.

Тело запроса

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

Тело ответа

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

metadata_field
Является ли это поле зарегистрированным полем метаданных.
searchable
Индексируется ли это поле для поиска по всем индексам.
aggregatable
Можно ли агрегировать это поле по всем индексам.
time_series_dimension
Используется ли это поле в качестве временной метки измерения во всех индексах. Для индексов, не относящихся к временным рядам, это поле отсутствует.
time_series_metric
Содержит тип метрики, если поле используется в качестве метрики временного ряда во всех индексах; отсутствует, если поле не используется в качестве метрики. Для индексов, не относящихся к временным рядам, это поле не включено.
indices
Список индексов, в которых это поле имеет то же семейство типов, или null, если для поля во всех индексах семейство типов одинаково.
non_searchable_indices
Список индексов, в которых это поле не может быть проиндексировано для поиска, или null, если для поля во всех индексах определение одинаково.
non_aggregatable_indices
Список индексов, в которых это поле не может быть агрегировано, или null, если для поля во всех индексах определение одинаково.
non_dimension_indices
[превью] Эта функциональность находится на стадии технического превью и может быть изменена или удалена в будущих выпусках. Elastic будет работать над исправлением любых проблем, но функции на стадии технического превью не подпадают под SLA поддержки официальных функций GA. Если этот список присутствует в ответе, то в некоторых индексах поле помечено как измерение, а в других индексах, указанных в списке, — нет.
metric_conflicts_indices
[превью] Эта функциональность находится на стадии технического превью и может быть изменена или удалена в будущих выпусках. Elastic будет работать над исправлением любых проблем, но функции на стадии технического превью не подпадают под SLA поддержки официальных функций GA. Список индексов, в которых это поле присутствует, если в этих индексах значение time_series_metric для этого поля не одинаковое.
meta
Объединенные метаданные по всем индексам в виде карты, где ключи — строки, а значения — массивы значений. Длина значения 1 указывает, что во всех индексах значения для этого ключа были одинаковыми, а длина 2 или более указывает на то, что во всех индексах значения для этого ключа не были одинаковыми.

Примеры

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

resp = client.field_caps(
    index="my-index-000001",
    fields="rating",
)
print(resp)
response = client.field_caps(
  index: 'my-index-000001',
  fields: 'rating'
)
puts response
const response = await client.fieldCaps({
  index: "my-index-000001",
  fields: "rating",
});
console.log(response);
GET my-index-000001/_field_caps?fields=rating

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

resp = client.field_caps(
    fields="rating,title",
)
print(resp)
response = client.field_caps(
  fields: 'rating,title'
)
puts response
const response = await client.fieldCaps({
  fields: "rating,title",
});
console.log(response);
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 в запрос:

resp = client.field_caps(
    fields="rating,title",
    include_unmapped=True,
)
print(resp)
response = client.field_caps(
  fields: 'rating,title',
  include_unmapped: true
)
puts response
const response = await client.fieldCaps({
  fields: "rating,title",
  include_unmapped: "true",
});
console.log(response);
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.

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

resp = client.field_caps(
    index="my-index-*",
    fields="rating",
    index_filter={
        "range": {
            "@timestamp": {
                "gte": "2018"
            }
        }
    },
)
print(resp)
response = client.field_caps(
  index: 'my-index-*',
  fields: 'rating',
  body: {
    index_filter: {
      range: {
        "@timestamp": {
          gte: '2018'
        }
      }
    }
  }
)
puts response
const response = await client.fieldCaps({
  index: "my-index-*",
  fields: "rating",
  index_filter: {
    range: {
      "@timestamp": {
        gte: "2018",
      },
    },
  },
});
console.log(response);
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/8.17/search-field-caps.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API