Миграция запросов для включения настройки автоподстановки keyword

Обратите внимание!

Инструкция по миграции для перехода на версию 5.1.

Описание API миграции

API миграции позволяет проверить запросы на необходимость миграции перед включением настройки автоподстановки keyword.

Обратите внимание!

Проверка миграции необходима, так как в команде search автоподстановка .keyword зависит от маппинга индексов в текущей инсталляции.

Проверка запросов в jobscheduler

Для проверки запросов в jobscheduler выполните команду в консоли разработчика (Навигационное меню - Параметры системы - Консоль разработчика):

GET /_sme/migration/autokeyword/jobscheduler

Данная команда в ответ возвращает массив с объектами замены. Пример ответа:

[
  {
    "job_id": "rnxSF5cBk65B9KQf1jWm",
    "index": ".sm_jsc_jobs",
    "doc_id": "r3xSF5cBk65B9KQf1jWy",
    "query": {
      "original": """
source internal_audit* | search audit_transport_headers.X-Opaque-Id="1b7adabf"
""",
      "replacement": """
source internal_audit* | search text audit_transport_headers.X-Opaque-Id="1b7adabf"
"""
    }
  }
]

Описание полей объекта замены:
job_id - идентификатор задания (поле _meta.id)
index - индекс, где хранится документ задания
doc_id - идентификатор документа задания (поле _id)
query - исходный запрос и запрос для замены

Проверка запросов в dashboards

Для проверки запросов в dashboards выполните команду в консоли разработчика (Навигационное меню - Параметры системы - Консоль разработчика):

GET /_sme/migration/autokeyword/dashboards

Данная команда в ответ возвращает массив с объектами замены. Пример ответа:

[
  {
    "pathInJson": "rows[3].panels[0].viz.options.sme.query",
    "dashboard_id": "incident_statistics",
    "index": ".sm_dashboards",
    "doc_id": "A8fyQ5cB8NGVbw6n_KHP",
    "query": {
      "original": ...,
      "replacement": ...
    }
  }
]

Описание полей объекта замены:
dashboard_id - идентификатор дашборда (поле _meta.id)
index - индекс, где хранится документ задания
doc_id - идентификатор документа задания (поле _id)
query - исходный запрос и запрос для замены
pathInJson - путь для поиска запроса в json поле дашборда

Проверка одного запроса

Чтобы проверить один запрос, выполните команду в консоли разработчика (Навигационное меню - Параметры системы - Консоль разработчика):

POST /_sme/migration/autokeyword/explain
{
  "query": """
  <SML запрос>
  """
}

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

POST /_sme/migration/autokeyword/explain
{
  "query": """
  source internal_audit* | search audit_transport_headers.X-Opaque-Id="1b7adabf"
  """
}

Результатом команды будет структура, содержащая в себе информацию о необходимой замене запроса (поле replacement):

{
	"original": """
  source internal_audit* | search audit_transport_headers.X-Opaque-Id="1b7adabf"
  """,
	"replacement": """
  source internal_audit* | search text audit_transport_headers.X-Opaque-Id="1b7adabf"
  """,
	"errors": [],
	"search_fields": [
		{
			"position": 35,
			"original": "audit_transport_headers.X-Opaque-Id",
			"name": "audit_transport_headers.X-Opaque-Id",
			"type": "text",
			"hasTextOp": false,
			"message": "Для поля добавлен оператор 'text'"
		}
	]
}

В данном примере ответ API указывает, что запрос:

source internal_audit* | search audit_transport_headers.X-Opaque-Id="1b7adabf"

Требуется заменить на запрос:

source internal_audit* | search text audit_transport_headers.X-Opaque-Id="1b7adabf"

То есть в запросе для замены к полю audit_transport_headers.X-Opaque-Id применен оператор text. Оператор text блокирует механизм автоподстановки .keyword. Если не произвести замену, то оператор text не будет применен, и в этом случае поле audit_transport_headers.X-Opaque-Id будет преобразовано в audit_transport_headers.X-Opaque-Id.keyword.

Автоподстановка произошла бы, так как маппинг текстового поля содержит в себе поле keyword. Для текстовых полей без keyword оператор text не требуется, механизм автоподстановки для них не сработает.

Маппинг поля audit_transport_headers.X-Opaque-Id в данном примере:

{
    "audit_transport_headers.X-Opaque-Id": {
        "full_name": "audit_transport_headers.X-Opaque-Id",
        "mapping": {
            "X-Opaque-Id": {
                "type": "text",
                "fields": {
                    "keyword": {
                        "type": "keyword",
                        "ignore_above": 256
                    }
                }
            }
        }
    }
}

Структура описания замены SML запроса

Все поля которые могут встречаться в структуре объяснения замены приведены в таблице.

Поле	Описание
original	Исходный запрос
expansion	Результат раскрытия всех макросов
macros	Деревья раскрытия макросов (состоит из узлов раскрытия макросов). Описывают раскрытие макросов первого уровня
replacement	Замена исходного запроса
errors	Ошибки, возникшие при обработке запроса
search_fields	Массив найденных полей и их атрибутов

Структура узла дерева раскрытия макроса

Структура узла дерева раскрытия макроса описывает раскрытие одного макроса.

Поле	Описание
expansion_position	Позиция раскрытия макроса в исходном запросе
original	Оригинальный текст (не раскрытый макрос)
expansion	Результат раскрытия макроса
name	Имя макроса
macros	Результат раскрытия дочерних (вложенных) макросов
search_fields	Массив найденных полей, порожденных раскрытием макроса

Структура поля и его атрибуты

Структура поля описывает найденные поля и их атрибуты. Могут присутствовать в общем результате объяснения замены, а также в узлах раскрытия макросов.

Обратите внимание!

Если поля найдены внутри деревьев раскрытия макросов, то такой случай требует детального рассмотрения и ручной осмысленной замены.

Поле	Описание
position	Позиция поля (после раскрытия всех макросов)
original	Оригинальный текст поля
name	Имя поля
type	Тип поля
hasTextOp	Применен ли к полю оператор text
message	Информация о статусе добавления оператора text к полю