Руководство прикладного разработчика#

О документе#

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

Расшифровку основных понятий см. в перечне "Термины и определения".

Системные требования#

Требования к окружению для использования компонента SRHX приведены в документе Руководство по установке в разделе Системные требования.

Подключение и конфигурирование#

Для целей разработки компонент SRHX обладает внешним Rest Api. SRHX Rest Api сохраняет преемственность по сравнению с Elasticsearch OSS REST API и OpenSearch REST API. Большая часть клиентского кода, работавшего с Elasticsearch OSS и OpenSearch будет работать с SRHX.

С документацией по Rest Api детально можно ознакомиться по ссылке https://opensearch.org/docs/2.11/api-reference/index/.

Конфигурирование прикладным разработчиком компонент SRHX не требует.

Миграция на текущую версию#

Миграция на текущую версию не требуется.

Быстрый старт#

Убедитесь, что выполнены все условия, указанные в Руководстве по установке в разделе Системные требования.

Ниже описаны процессы:

  • установки и запуска компонента SRHX производственной среде;

  • создание индекса;

  • добавление данных в индекс;

  • поиска данных.

Установка и запуск компонента SRHX на производственной среде

В случае, если компонент SRHX уже установлен на производственной среде, этот пункт можно пропустить.

Для того, чтобы выполнить установку компонента SRHX на производственную среду:

  1. Установите компонент SRHX. С установкой компонента SRHX можно ознакомиться в документации Руководство по установке для компонента SRHX.

Компонент SRHX имеет REST API, это позволяет взаимодействовать с ним с помощью любого клиента, который отправляет HTTP(S)-запросы, например, Postman или curl.

  1. После установки проверьте связь с кластером. Убедитесь, что все службы запущены.

  2. Используйте -k (–insecure) для отключения проверки имени хоста, поскольку конфигурация безопасности по умолчанию использует демонстрационные сертификаты. Используйте -u для передачи имени пользователя и пароля по умолчанию ( admin:admin).

curl https://localhost:Значение указанное в параметре "http.port" в opensearch.yml -ku admin:admin

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

{
    "name" : "opensearch-node1",
    "cluster_name" : "opensearch-cluster",
    "cluster_uuid" : "W0B8gPotTAajhMPbC9D4ww",
    "version" : {
        "distribution" : "opensearch",
        "number" : "2.6.0",
        "build_type" : "tar",
        "build_hash" : "7203a5af21a8a009aece1474446b437a3c674db6",
        "build_date" : "2023-02-24T18:58:37.352296474Z",
        "build_snapshot" : false,
        "lucene_version" : "9.5.0",
        "minimum_wire_compatibility_version" : "7.10.0",
        "minimum_index_compatibility_version" : "7.0.0"
    },
    "tagline" : "The OpenSearch Project: https://opensearch.org/"
}

Создание индекса и сопоставления полей с использованием демонстрационных данных

  1. Создайте индекс под названием ACCOUNTS.

curl -X PUT "https://localhost:Значение указанное в параметре "http.port" в opensearch.yml/accounts?pretty" -ku admin:admin

Вывод команды:

{
  "acknowledged" : true,
  "shards_acknowledged" : true,
  "index" : "accounts"
}

  1. Добавьте поля:

  • имя пользователя – текст;

  • имя – текст;

  • электронная почта – текст;

  • возраст – число.

curl -X PUT "http://localhost:Значение указанное в параметре "http.port" в opensearch.yml/accounts" -ku admin:admin -H 'Content-Type: application/json' -d'
{
    "mappings": {
        "properties": {
            "username": {
                "type": "text"
            },
            "name": {
                "type": "text"
            },
            "email": {
                "type": "text"
            },
            "age": {
                "type": "integer"
            }
        }
    }
}

Вывод команды:

{
    "acknowledged": true,
    "shards_acknowledged": true,
    "index": "accounts"
}

  1. Проверьте mapping:

curl -X GET "https://localhost:Значение указанное в параметре "http.port" в opensearch.yml/accounts/_mapping?pretty" -ku admin:admin

Вывод команды:

{
  "accounts" : {
    "mappings" : {
      "properties" : {
        "age" : {
          "type" : "integer"
        },
        "email" : {
          "type" : "text"
        },
        "name" : {
          "type" : "text"
        },
        "username" : {
          "type" : "text"
        }
      }
    }
  }
}

  1. В результате создан новый индекс ACCOUNTS на сервере компонента SRHX.

Добавление данных в индекс

  1. Для добавления данных воспользуйтесь созданным ранее тестовым индексом ACCOUNTS.

  2. С помощью следующего запроса добавьте документ в индекс.

curl  -X PUT "https://localhost:Значение указанное в параметре "http.port" в opensearch.yml/accounts/_doc/0001" -ku admin:admin -H 'Content-Type: application/json' -d'
{
    "username" : "Admin",
    "name" : "Иван Иванов",
    "email" : "iivanov@test.ru",
    "age" : "35"
}

Вывод команды:

{
    "_index": "accounts",
    "_id": "0001",
    "_version": 1,
    "result": "created",
    "_shards": {
        "total": 2,
        "successful": 2,
        "failed": 0
    },
    "_seq_no": 2,
    "_primary_term": 1
}

  1. Добавьте еще один документ в индекс.


curl  -X PUT "https://localhost:Значение указанное в параметре "http.port" в opensearch.yml/accounts/_doc/0002" -ku admin:admin -H 'Content-Type: application/json' -d'
{
    "username" : "Manager",
    "name" : "Артем Артемов",
    "email" : "aartemov@test.ru",
    "age" : "50"
}

Вывод команды:

{
    "_index": "accounts",
    "_id": "0002",
    "_version": 1,
    "result": "created",
    "_shards": {
        "total": 2,
        "successful": 2,
        "failed": 0
    },
    "_seq_no": 3,
    "_primary_term": 1
}

  1. В результате были загружены два документа в тестовый индекс ACCOUNTS.

Использование поискового API компонента SRHX

Пример. Найти все документы в тестовом индексе ACCOUNTS с возрастом менее 40 лет.

curl  -X GET "https://localhost:Значение указанное в параметре "http.port" в opensearch.yml/accounts/_search/?pretty" -ku admin:admin -H 'Content-Type: application/json' -d'
{
    "query": {
        "range" : {
            "age" : {
                "lt" : 40
            }
        }
    }
}

Результат работы команды:

{
  "took" : 2,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 1,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "accounts",
        "_type" : "_doc",
        "_id" : "1",
        "_score" : 1.0,
        "_source" : {
            "username" : "Admin",
            "name" : "Иван Иванов",
            "email" : "iivanov@test.ru",
            "age" : "35"
        }
      }
    ]
  }
}

Таким образом отображается документ, соответствующий критериям поиска.

Использование программного компонента SRHX#

Компонент SRHX представляет собой поисковую систему. С его помощью возможен поиск данных по следующим категориям:

  • поиск по полю;

  • поиск по нескольким индексам;

  • повышение полей;

  • сортировка результатов по полям и агрегирование результатов.