REST API и формат запросов

Учимся разговаривать с Elasticsearch по HTTP: методы, пути, тело запроса и где находится поиск.

REST API Elasticsearch — это набор HTTP-эндпоинтов, где метод и путь задают действие, а тело JSON — детали запроса.

Анатомия запроса

Любой запрос к ES — это HTTP-вызов: МЕТОД /путь и иногда тело-JSON. Путь обычно начинается с имени индекса, а специальные эндпоинты начинаются с подчёркивания (_search, _bulk, _mapping).

# Проверить, что кластер жив
curl http://localhost:9200/

# Здоровье кластера
curl http://localhost:9200/_cluster/health

HTTP-методы и их смысл

Создать индекс и положить документ

# Создать индекс products
curl -X PUT http://localhost:9200/products

# Положить документ с id=1
curl -X PUT http://localhost:9200/products/_doc/1 \
  -H 'Content-Type: application/json' \
  -d '{"title": "Кофемашина", "price": 24990}'

Часть пути _doc — это «точка входа» для документа (рудимент старых типов). После _doc идёт _id. Если id не нужен, используйте POST /products/_doc без id — ES сгенерирует.

Эндпоинт _search

Главный эндпоинт — поиск. Тело запроса — это Query DSL (язык запросов на JSON), который мы изучим в отдельном разделе.

curl -X GET http://localhost:9200/products/_search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": { "match": { "title": "кофемашина" } }
  }'

Тело запроса (Query DSL) выглядит так:

{
  "query": {
    "match": { "title": "кофемашина" }
  }
}

Как работает под капотом

ES слушает HTTP на порту 9200. Запрос приходит на любой узел кластера — этот узел становится координатором: он рассылает запрос по нужным шардам, собирает их частичные ответы, объединяет, сортирует по релевантности и возвращает клиенту единый JSON. Поэтому вам не важно, к какому узлу обращаться: координатором станет тот, к кому вы пришли. Ответ всегда JSON: в нём поле hits с найденными документами, их _score (релевантность) и метаданные (время, число попаданий).

Частые ошибки

• Забыть заголовок Content-Type. Если шлёте тело-JSON, обязателен -H 'Content-Type: application/json', иначе ES вернёт ошибку 406.
• Путать PUT и POST для документов. PUT /index/_doc/ID требует id и заменит документ целиком; POST /index/_doc создаёт новый со сгенерированным id.

Итоги

• Запрос к ES — это HTTP: метод + путь (имя индекса, спец-эндпоинты с подчёркиванием) + тело JSON.
• Поиск идёт через GET/POST /индекс/_search с телом Query DSL.
• Любой узел может быть координатором: он разошлёт запрос, соберёт ответы и вернёт единый JSON.