API cat shards
API cat предназначены только для использования человеком с помощью командной строки или консоли Kibana. Они не предназначены для использования приложениями.
Команда shards отображает подробную информацию о том, какие фрагменты содержатся на каких узлах. Она покажет, является ли фрагмент первичным или репликой, количество документов, занимаемое ими место на диске и узел, на котором они расположены.
Для потоков данных API возвращает информацию об индексах, на которые опирается поток.
Запрос
GET /_cat/shards/<target>
GET /_cat/shards
Предварительные условия
- Если включены функции безопасности Elasticsearch, вам необходимо иметь
monitorилиmanageпривилегию кластера, чтобы использовать этот API. Вам также необходимо иметьmonitorилиmanageпривилегию индекса, чтобы просмотреть всю информацию о любом потоке данных, индексе или псевдониме, который вы извлекаете.
Параметры пути
-
<target> - (Необязательно, строка) Список потоков данных, индексов и псевдонимов, разделенных запятыми, используемых для ограничения запроса. Поддерживаются подстановочные знаки (
*). Для определения всех потоков данных и индексов опустите этот параметр или используйте*или_all.
Параметры запроса
-
bytes - (Необязательно, единицы измерения размера байтов) Единица измерения, используемая для отображения значений байтов.
-
format - (Необязательно, строка) Короткая версия заголовка HTTP Accept. Допустимые значения включают JSON, YAML и т.д.
-
h -
(Необязательно, строка) Список имен столбцов, разделенных запятыми, для отображения.
Если вы не указываете, какие столбцы включить, API возвращает столбцы по умолчанию в указанном ниже порядке. Если вы явно указываете один или несколько столбцов, он возвращает только указанные столбцы.
Допустимые столбцы:
-
index,i,idx - (Default) Имя индекса.
-
shard,s,sh - (Default) Имя фрагмента.
-
prirep,p,pr,primaryOrReplica - (Default) Тип фрагмента. Возвращаемые значения —
primaryилиreplica. -
state,st -
(Default) Состояние фрагмента. Возвращаемые значения:
-
INITIALIZING: фрагмент восстанавливается из фрагмента-пира или шлюза. -
RELOCATING: фрагмент переходит на новое место. -
STARTED: фрагмент запущен. -
UNASSIGNED: фрагмент не назначен ни одному узлу.
-
-
docs,d,dc - (Default) Количество документов в фрагменте, например,
25. -
store,sto - (Default) Используемое дисковое пространство фрагмента, например,
5kb. -
dataset.size - (Default) Дисковое пространство, используемое набором данных фрагмента. Оно может, но необязательно, соответствовать размеру на диске, а также включает пространство, используемое фрагментом в хранилище объектов. Выводится как значение размера, например,
5kb. -
ip - (Default) IP-адрес узла, например,
127.0.1.1. -
id - (Default) Идентификатор узла, например,
k0zy. -
node,n - (Default) Имя узла, например,
I8hydUG. -
completion.size,cs,completionSize - Размер завершения, например,
0b. -
dense_vector.value_count,dvc,denseVectorCount - Количество индексированных плотных векторов.
-
fielddata.memory_size,fm,fielddataMemory - Используемая память кэша fielddata, например,
0b. -
fielddata.evictions,fe,fielddataEvictions - Сбросы кэша fielddata, например,
0. -
flush.total,ft,flushTotal - Количество сбросов, например,
1. -
flush.total_time,ftt,flushTotalTime - Время, затраченное на сброс, например,
1. -
get.current,gc,getCurrent - Количество текущих операций получения, например,
0. -
get.time,gti,getTime - Время, затраченное на получение, например,
14ms. -
get.total,gto,getTotal - Количество операций получения, например,
2. -
get.exists_time,geti,getExistsTime - Время, затраченное на успешные получения, например,
14ms. -
get.exists_total,geto,getExistsTotal - Количество успешных операций получения, например,
2. -
get.missing_time,gmti,getMissingTime - Время, затраченное на неудачные получения, например,
0s. -
get.missing_total,gmto,getMissingTotal - Количество неудачных операций получения, например,
1. -
indexing.delete_current,idc,indexingDeleteCurrent - Количество текущих операций удаления, например,
0. -
indexing.delete_time,idti,indexingDeleteTime - Время, затраченное на удаления, например,
2ms. -
indexing.delete_total,idto,indexingDeleteTotal - Количество операций удаления, например,
2. -
indexing.index_current,iic,indexingIndexCurrent - Количество текущих операций индексирования, например,
0. -
indexing.index_time,iiti,indexingIndexTime - Время, затраченное на индексирование, например,
134ms. -
indexing.index_total,iito,indexingIndexTotal - Количество операций индексирования, например,
1. -
indexing.index_failed,iif,indexingIndexFailed - Количество неудачных операций индексирования, например,
0. -
merges.current,mc,mergesCurrent - Количество текущих операций слияния, например,
0. -
merges.current_docs,mcd,mergesCurrentDocs - Количество текущих документов, сливаемых вместе, например,
0. -
merges.current_size,mcs,mergesCurrentSize - Размер текущих слияний, например,
0b. -
merges.total,mt,mergesTotal - Количество завершенных операций слияния, например,
0. -
merges.total_docs,mtd,mergesTotalDocs - Количество слитых документов, например,
0. -
merges.total_size,mts,mergesTotalSize - Размер текущих слияний, например,
0b. -
merges.total_time,mtt,mergesTotalTime - Время, затраченное на слияние документов, например,
0s. -
query_cache.memory_size,qcm,queryCacheMemory - Используемая память кэша запросов, например,
0b. -
query_cache.evictions,qce,queryCacheEvictions - Сбросы кэша запросов, например,
0. -
recoverysource.type,rs - Тип источника восстановления.
-
refresh.total,rto,refreshTotal - Количество обновлений, например,
16. -
refresh.time,rti,refreshTime - Время, затраченное на обновления, например,
91ms. -
search.fetch_current,sfc,searchFetchCurrent - Текущие операции фазы извлечения, например,
0. -
search.fetch_time,sfti,searchFetchTime - Время, затраченное на фазу извлечения, например,
37ms. -
search.fetch_total,sfto,searchFetchTotal - Количество операций извлечения, например,
7. -
search.open_contexts,so,searchOpenContexts - Открытые контексты поиска, например,
0. -
search.query_current,sqc,searchQueryCurrent - Текущие операции фазы запроса, например,
0. -
search.query_time,sqti,searchQueryTime - Время, затраченное на фазу запроса, например,
43ms. -
search.query_total,sqto,searchQueryTotal - Количество операций запроса, например,
9. -
search.scroll_current,scc,searchScrollCurrent - Открытые контексты прокрутки, например,
2. -
search.scroll_time,scti,searchScrollTime - Время удержания контекстов прокрутки открытыми, например,
2m. -
search.scroll_total,scto,searchScrollTotal - Завершенные контексты прокрутки, например,
1. -
segments.count,sc,segmentsCount - Количество сегментов, например,
4. -
segments.memory,sm,segmentsMemory - Память, используемая сегментами, например,
1.4kb. -
segments.index_writer_memory,siwm,segmentsIndexWriterMemory - Память, используемая записью индекса, например,
18mb. -
segments.version_map_memory,svmm,segmentsVersionMapMemory - Память, используемая отображением версий, например,
1.0kb. -
segments.fixed_bitset_memory,sfbm,fixedBitsetMemory - Память, используемая наборами фиксированных битов для типов вложенных объектов и фильтрами типов, упомянутых в полях
join, например,1.0kb. -
seq_no.global_checkpoint,sqg,globalCheckpoint - Глобальная контрольная точка.
-
-
seq_no.local_checkpoint,sql,localCheckpoint - Местный контрольный пункт.
-
seq_no.max,sqm,maxSeqNo - Максимальное порядковое число.
-
sparse_vector.value_count,svc,sparseVectorCount - Количество индексированных разреженных векторов.
-
suggest.current,suc,suggestCurrent - Количество текущих операций подбора, таких как
0. -
suggest.time,suti,suggestTime - Время, затраченное на подбор, например,
0. -
suggest.total,suto,suggestTotal - Количество операций подбора, таких как
0. -
sync_id - Идентификатор синхронизации фрагмента.
-
unassigned.at,ua - Время, когда фрагмент перестал быть назначенным в координированном всемирном времени (UTC).
-
unassigned.details,ud - Сведения о причинах, по которым фрагмент перестал быть назначенным. Это не объясняет, почему фрагмент в настоящее время не назначен. Чтобы понять, почему фрагмент не назначен, используйте API объяснения распределения кластера.
-
unassigned.for,uf - Время, когда фрагмент был запрошен для отмены назначения в координированном всемирном времени (UTC).
-
unassigned.reason,ur -
Указывает причину последнего изменения состояния этого неназначенного фрагмента. Это не объясняет, почему фрагмент в настоящее время не назначен. Чтобы понять, почему фрагмент не назначен, используйте API объяснения распределения кластера. Возвращаемые значения включают:
-
ALLOCATION_FAILED: Отмена назначения в результате неудачного распределения фрагмента. -
CLUSTER_RECOVERED: Отмена назначения в результате полного восстановления кластера. -
DANGLING_INDEX_IMPORTED: Отмена назначения в результате импорта висящего индекса. -
EXISTING_INDEX_RESTORED: Отмена назначения в результате восстановления в закрытый индекс. -
FORCED_EMPTY_PRIMARY: Распределение фрагмента было последним изменено принудительным созданием пустого первичного фрагмента с помощью API перенаправления кластера. -
INDEX_CLOSED: Отмена назначения из-за закрытия индекса. -
INDEX_CREATED: Отмена назначения в результате создания индекса через API. -
INDEX_REOPENED: Отмена назначения в результате открытия закрытого индекса. -
MANUAL_ALLOCATION: Распределение фрагмента было последним изменено API перенаправления кластера. -
NEW_INDEX_RESTORED: Отмена назначения в результате восстановления в новый индекс. -
NODE_LEFT: Отмена назначения в результате выхода узла, на котором он размещён, из кластера. -
NODE_RESTARTING: АналогичноNODE_LEFT, за исключением того, что узел был зарегистрирован как перезапускающийся с помощью API остановки узла. -
PRIMARY_FAILED: Фрагмент инициализировался как реплика, но первичный фрагмент вышел из строя до завершения инициализации. -
REALLOCATED_REPLICA: Найден более подходящий узел для реплики, что приводит к отмене существующего распределения реплики. -
REINITIALIZED: Когда фрагмент переходит от состояния «запущен» к «инициализация». -
REPLICA_ADDED: Отмена назначения в результате явного добавления реплики. -
REROUTE_CANCELLED: Отмена назначения в результате явного отмены команды перенаправления.
-
-
-
help - (Необязательно, логическое значение) Если
true, в ответ включается справочная информация. По умолчаниюfalse. -
master_timeout - (Необязательно, единицы измерения времени) Период ожидания узла-мастера. Если узел-мастер недоступен до истечения срока ожидания, запрос завершается ошибкой. По умолчанию
30s. Также может быть задано значение-1, чтобы указать, что запрос никогда не должен приостанавливаться по истечении времени ожидания. -
s - (Необязательно, строка) Список столбцов или псевдонимов столбцов, разделённых запятыми, используемых для сортировки ответа.
-
time - (Необязательно, единицы измерения времени) Единица измерения времени в отображаемых значениях.
-
v - (Необязательно, логическое значение) Если
true, ответ включает заголовки столбцов. По умолчаниюfalse.
Примеры
Пример с одним потоком данных или индексом
resp = client.cat.shards() print(resp)
response = client.cat.shards puts response
const response = await client.cat.shards(); console.log(response);
GET _cat/shards
API возвращает следующий ответ:
my-index-000001 0 p STARTED 3014 31.1mb 192.168.56.10 H5dfFeA
Пример с шаблоном подстановки
Если в вашем кластере много фрагментов, вы можете использовать шаблон подстановки в параметре пути <target> для ограничения запроса к API.
Следующий запрос возвращает информацию для потоков данных или индексов, начинающихся с my-index-.
resp = client.cat.shards(
index="my-index-*",
)
print(resp) response = client.cat.shards( index: 'my-index-*' ) puts response
const response = await client.cat.shards({
index: "my-index-*",
});
console.log(response); GET _cat/shards/my-index-*
API возвращает следующий ответ:
my-index-000001 0 p STARTED 3014 31.1mb 192.168.56.10 H5dfFeA
Пример с перемещаемым фрагментом
resp = client.cat.shards() print(resp)
response = client.cat.shards puts response
const response = await client.cat.shards(); console.log(response);
GET _cat/shards
API возвращает следующий ответ:
my-index-000001 0 p RELOCATING 3014 31.1mb 192.168.56.10 H5dfFeA -> -> 192.168.56.30 bGG90GE
Значение RELOCATING в столбце state указывает, что фрагмент индекса перемещается.
Пример с состояниями фрагментов
Перед тем, как фрагмент станет доступен для использования, он проходит через состояние INITIALIZING. Вы можете использовать API cat shards, чтобы увидеть, какие фрагменты находятся в состоянии инициализации.
resp = client.cat.shards() print(resp)
response = client.cat.shards puts response
const response = await client.cat.shards(); console.log(response);
GET _cat/shards
API возвращает следующий ответ:
my-index-000001 0 p STARTED 3014 31.1mb 192.168.56.10 H5dfFeA my-index-000001 0 r INITIALIZING 0 14.3mb 192.168.56.30 bGG90GE
Пример с причинами неназначенных фрагментов
Следующий запрос возвращает столбец unassigned.reason, который указывает причину, по которой фрагмент не назначен.
resp = client.cat.shards(
h="index,shard,prirep,state,unassigned.reason",
)
print(resp) response = client.cat.shards( h: 'index,shard,prirep,state,unassigned.reason' ) puts response
const response = await client.cat.shards({
h: "index,shard,prirep,state,unassigned.reason",
});
console.log(response); GET _cat/shards?h=index,shard,prirep,state,unassigned.reason
API возвращает следующий ответ:
my-index-000001 0 p STARTED 3014 31.1mb 192.168.56.10 H5dfFeA my-index-000001 0 r STARTED 3014 31.1mb 192.168.56.30 bGG90GE my-index-000001 0 r STARTED 3014 31.1mb 192.168.56.20 I8hydUG my-index-000001 0 r UNASSIGNED ALLOCATION_FAILED
© 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/cat-shards.html