Index API
Тема дорожной карты · Elasticsearch
Index API в Elasticsearch создаёт или заменяет документ в индексе через PUT /<index>/_doc/<id> (с явным идентификатором документа) или POST /<index>/_doc (позволяя Elasticsearch автоматически сгенерировать UUID в качестве идентификатора). При вызове Index API Elasticsearch направляет документ в соответствующий основной шард на основе хеша идентификатора, записывает его в translog шарда для обеспечения долговечности и делает доступным для поиска после следующего обновления (по умолчанию раз в секунду). Если документ с таким же идентификатором уже существует, Index API заменяет весь документ и увеличивает счётчик _version; для защиты от случайного перезаписи можно использовать вариант PUT /<index>/_create/<id>, который возвращает ошибку, если документ уже существует. Поля _version и порядкового номера, возвращаемые Index API, можно использовать для оптимистичного управления параллельным доступом, включая параметры if_seq_no и if_primary_term в последующие запросы обновления или удаления. Для массового приёма документов эндпоинт POST /_bulk всегда предпочтителен перед многократными вызовами Index API, поскольку значительно снижает HTTP-накладные расходы и повышает пропускную способность индексирования в Elasticsearch.
Как это работает
Index API: Index API (PUT /index/_doc/id — create/replace), Get API (GET /index/_doc/id), Update API (POST /index/_update/id — partial update через script или doc), Delete API (DELETE /index/_doc/id), Bulk API (POST /_bulk с newline-delimited actions). Bulk обязателен для high-throughput индексации — single-doc indexing жжёт ресурсы. ES near real-time (NRT): writes ищутся через ~1 секунду (refresh interval).
Когда применять
Bulk API для любой sustained индексации — batch 5-15MB типично. Тюньте refresh_interval в -1 во время bulk-загрузок, потом 1s для normal use — экономит IO + heap. Updates в ES = delete + re-index под капотом — частые updates фрагментируют индексы. Для deletes — reindex-with-filter лучше многих delete-by-query.
Типичные ошибки
Ловушки Index API: single-doc indexing в hot loop (кластер ползёт); Bulk batches слишком большие (>100MB — OOM); не handle bulk partial failures (часть items падают, игнор); update API для очень частых updates (delete+re-index churn).