Взаимодействие с OpenSearch

Вы можете работать с OpenSearch через REST API или используя клиентские библиотеки для различных языков программирования.

На этой странице рассматривается REST API. Список доступных клиентов для языков программирования вы найдёте в разделе Клиенты.

REST API OpenSearch

REST API предоставляет гибкий способ взаимодействия с кластерами OpenSearch. Через API вы можете:

  • Изменять настройки OpenSearch
  • Управлять индексами
  • Проверять состояние кластера
  • Получать статистику
  • И многое другое

Для отправки запросов можно использовать:

  • Командную строку (cURL)
  • Консоль Dev Tools в OpenSearch Dashboards
  • Любой язык программирования с поддержкой HTTP-запросов
Отправка запросов через терминал

Формат запросов зависит от использования плагина безопасности.

Без плагина безопасности:

curl -X GET "http://localhost:9200/_cluster/health"

С плагином безопасности (требуются учётные данные):

curl -X GET "https://localhost:9200/_cluster/health" -ku admin:ВАШ_ПАРОЛЬ

По умолчанию:

  • Логин: admin
  • Пароль: задаётся в параметре OPENSEARCH_INITIAL_ADMIN_PASSWORD файла docker-compose.yml

Форматирование ответа: Для удобочитаемого JSON добавьте параметр pretty:

curl -X GET "https://localhost:9200/_cluster/health?pretty"

Запросы с телом: Укажите заголовок Content-Type и передайте данные через параметр -d:

curl -X GET "https://localhost:9200/students/_search?pretty" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "match_all": {}
    }
  }'
Отправка запросов через Dev Tools

Консоль Dev Tools в OpenSearch Dashboards использует упрощённый синтаксис:

  1. Откройте Dashboards: https://localhost:5601/
  2. Перейдите: Management > Dev Tools
  3. Введите запрос (например):
    $$GET _cluster/health$$
  4. Отправьте запрос:
    • Клик по иконке ▶
    • Ctrl+Enter (Cmd+Enter на Mac)

В документации OpenSearch запросы чаще всего приводятся в формате Dev Tools.

Дополнительно:

Индексация документов

Для добавления JSON-документа в индекс OpenSearch (индексации документа) отправьте HTTP-запрос со следующим форматом:

$$PUT https://<хост>:<порт>/<имя-индекса>/_doc/<идентификатор-документа>$$

Пример индексации документа о студенте:

PUT /students/_doc/1
{
  "name": "Иван Иванов",
  "gpa": 4.5,
  "grad_year": 2023
}

После выполнения запроса:

  • OpenSearch создаст индекс students (если не существует)
  • Сохранит документ с указанным ID (1)
  • Если ID не указан - сгенерирует его автоматически

Динамическое маппинг

OpenSearch автоматически определяет типы полей на основе JSON-структуры документа.

Просмотр схемы полей:

$$GET /students/_mapping$$

Пример ответа:

{
  "students": {
    "mappings": {
      "properties": {
        "gpa": {"type": "float"},
        "grad_year": {"type": "long"},
        "name": {
          "type": "text",
          "fields": {
            "keyword": {
              "type": "keyword", 
              "ignore_above": 256
            }
          }
        }
      }
    }
  }
}

Особенности типов:

  • Числовые значения: float, long
  • Текстовые поля:
    • Основное поле (text): для полнотекстового поиска (с анализом)
    • Подполе (keyword): для точного поиска по терминам

Важно: Для изменения типов (например, преобразования grad_year в дату) требуется пересоздание индекса с явным указанием маппинга.

Поиск документов

Базовый запрос (возвращает все документы):

GET /students/_search
{
  "query": {
    "match_all": {}
  }
}

Пример ответа:

{
  "took": 12,
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "hits": [
      {
        "_index": "students",
        "_id": "1",
        "_score": 1,
        "_source": {
          "name": "Иван Иванов",
          "gpa": 4.5,
          "grad_year": 2023
        }
      }
    ]
  }
}

Ключевые элементы ответа:

  • took: время выполнения (мс)
  • hits.total: количество найденных документов
  • hits.hits: массив результатов
  • _score: релевантность документа

Дополнительные материалы:

Обновление документов

В OpenSearch документы неизменяемы, но их можно обновить, полностью заменив содержимое или изменив отдельные поля.

Полное обновление (переиндексация)

Используйте Index Document API для полного обновления:

PUT /students/_doc/1
{
  "name": "Иван Иванов",
  "gpa": 4.7,  // Обновлённое значение
  "grad_year": 2023,
  "address": "ул. Ленина, 123"  // Новое поле
}

Частичное обновление

Используйте Update Document API для изменения отдельных полей:

POST /students/_update/1/
{
  "doc": {
    "gpa": 4.7,
    "address": "ул. Ленина, 123"
  }
}

Удаление данных

Удаление документа

DELETE /students/_doc/1

Удаление индекса

DELETE /students

Настройка индексов

Маппинги и параметры

Индексы настраиваются через:

  • Маппинги - определяют типы полей
  • Параметры - настройки индекса (количество шардов и т.д.)

Пример создания индекса с явными настройками:

PUT /students
{
  "settings": {
    "index.number_of_shards": 1
  },
  "mappings": {
    "properties": {
      "name": {"type": "text"},
      "grad_year": {"type": "date"}
    }
  }
}

Проверка маппинга:

GET /students/_mapping

Важно:

  • Типы полей нельзя изменить после создания
  • Для изменения требуется пересоздание индекса

Дополнительные материалы

Следующие шаги

Ознакомьтесь с разделом Загрузка данных в OpenSearch для изучения способов импорта данных.