Индексирование и обновление документов с помощью REST API Elasticsearch

Elasticsearch — это мощная, распределенная поисковая и аналитическая система, которая полагается на хорошо структурированный ввод данных. Управление этими данными включает в себя основные операции Create, Read, Update, Delete (CRUD), в первую очередь выполняемые через его универсальный REST API. Понимание того, как правильно индексировать новые документы и эффективно обновлять существующие, имеет решающее значение для поддержания актуальной и точной базы данных в реальном времени.

В этом руководстве мы рассмотрим основные HTTP-методы и конечные точки API, используемые для индексирования новых записей и изменения существующих документов в вашем кластере Elasticsearch. Мы сосредоточимся на синтаксисе, требуемых JSON-запросах и интерпретации кодов ответа для обеспечения бесперебойного управления данными.

---

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

Перед началом убедитесь, что у вас есть:

• Активный работающий кластер Elasticsearch.
• Инструмент командной строки, способный выполнять HTTP-запросы (например, curl), или HTTP-клиент (например, Postman).
• Знание имени целевого индекса.

---

1. Индексирование новых документов

Индексирование — это процесс хранения JSON-документа в индексе Elasticsearch. Elasticsearch автоматически назначает документу уникальный идентификатор, если он не указан явно. Основной метод для индексирования — HTTP-метод PUT или POST.

1.1 Индексирование с автоматическим ID (POST)

Когда вы используете POST для конечной точки индекса, Elasticsearch генерирует для вас уникальный идентификатор документа. Часто это предпочтительный метод для первоначального ввода данных, когда идентификаторы управляются внутренне.

Конечная точка: POST /{index_name}/_doc/

Пример запроса (с использованием curl):

curl -X POST "localhost:9200/products/_doc/" -H 'Content-Type: application/json' -d'
{
  "name": "Wireless Mouse X1",
  "price": 25.99,
  "in_stock": true
}
'

Фрагмент успешного ответа:

{
  "_index": "products",
  "_id": "c7BwJ3gBpV4wT-eH_aY1",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 0,
  "_primary_term": 1
}

Поле result со значением created подтверждает, что новый документ был добавлен.

1.2 Индексирование с указанием ID (PUT)

Если ваша исходная система предоставляет уникальный идентификатор для документа, вы должны использовать метод PUT, нацеленный на определенный идентификатор. Если документ с таким идентификатором уже существует, PUT перезапишет весь документ.

Конечная точка: PUT /{index_name}/_doc/{document_id}

Пример запроса: Индексирование документа с ID 1001.

curl -X PUT "localhost:9200/products/_doc/1001" -H 'Content-Type: application/json' -d'
{
  "name": "Mechanical Keyboard K90",
  "price": 129.99,
  "in_stock": true
}
'

Фрагмент успешного ответа:

{
  "_index": "products",
  "_id": "1001",
  "_version": 1,
  "result": "created",
  "_shards": { ... }
}

Совет по перезаписи: Если вы выполните тот же запрос PUT еще раз с тем же идентификатором, значение result изменится на updated, а номер _version увеличится.

---

2. Обновление существующих документов

Обновление документов отличается от перезаписи. Когда вы хотите изменить только определенные поля в существующем документе, не затрагивая неизмененные поля, вы используете конечную точку _update, обычно с методом POST.

2.1 Частичные обновления с использованием _update

API _update имеет решающее значение для атомарных обновлений. Он требует блок doc внутри запроса, который содержит только поля, которые вы хотите изменить. Elasticsearch извлекает документ, объединяет изменения и повторно индексирует его.

Конечная точка: POST /{index_name}/_update/{document_id}

Пример сценария: Мы хотим обновить цену продукта с ID 1001 с $129.99 до $119.99 и пометить его как отсутствующий на складе.

curl -X POST "localhost:9200/products/_update/1001" -H 'Content-Type: application/json' -d'
{
  "doc": {
    "price": 119.99,
    "in_stock": false
  }
}
'

Фрагмент успешного ответа:

{
  "_index": "products",
  "_id": "1001",
  "_version": 2, 
  "result": "updated",
  "_shards": { ... }
}

Обратите внимание, что _version увеличился с 1 до 2, отражая модификацию.

2.2 Использование скриптовых обновлений

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

Пример сценария: Увеличить количество на складе на 5 для документа с ID 1001.

curl -X POST "localhost:9200/products/_update/1001" -H 'Content-Type: application/json' -d'
{
  "script": {
    "source": "ctx._source.stock += params.count",
    "params": {
      "count": 5
    }
  }
}
'

Ключевая концепция скриптов: ctx._source относится к исходному коду текущего документа.

Предупреждение о скриптах: Несмотря на свою мощь, сложные скрипты могут повлиять на производительность. По возможности используйте простые обновления полей (doc), так как они, как правило, быстрее и безопаснее.

---

3. Массовое индексирование и обновление

При операциях с большими объемами данных отправка отдельных запросов для каждого документа неэффективна. Elasticsearch предоставляет API _bulk для обработки нескольких операций индексирования, обновления или удаления в одном запросе.

3.1 Структура массового запроса

Массовые запросы используют специальный формат JSON, разделенного переносами строк (NDJSON). Каждая операция определяется строкой метаданных (указывающей действие, индекс и необязательный ID), за которой сразу следует исходный код документа (если требуется).

Типы действий для массовых операций: index, create, update, delete.

Пример массового запроса (смешивание индексирования и обновления):

curl -X POST "localhost:9200/products/_bulk" -H 'Content-Type: application/x-ndjson' -d'

{"index": {"_id": "2001"}}
{"name": "USB-C Hub", "price": 45.00, "in_stock": true}
{"update": {"_id": "1001"}}
{"doc": {"price": 115.00}}
{"delete": {"_id": "3003"}}

'

В этом примере:

1. Индексируется документ 2001.
2. Частично обновляется документ 1001 (снижается цена).
3. Удаляется документ 3003.

Массовый ответ: Ответ будет детализировать успех или неудачу каждой отдельной операции в пакете, позволяя вам точно определить, какие документы были успешно обработаны, а какие — нет.

---

Сводка основных команд API

Операция	HTTP-метод	Шаблон конечной точки	Эффект
Индексирование (авто ID)	POST	/{index}/_doc/	Создает новый документ с автоматически сгенерированным ID.
Индексирование/Перезапись	PUT	/{index}/_doc/{id}	Создает или полностью заменяет документ по указанному ID.
Частичное обновление	POST	/{index}/_update/{id}	Объединяет изменения, указанные в блоке doc.
Массовые операции	POST	/{index}/_bulk	Выполняет несколько операций в одном запросе.

Овладение этими основными взаимодействиями REST API обеспечивает основу для динамического управления данными в любом приложении Elasticsearch.