Модуль поиска¶

Основным запросом модуля поиска является POST-запрос /universe-backend/api/v2/search.

Механизм агрегации результатов поиска по типу актива¶

Секция aggregations содержит массив объектов агрегаций.

Каждый объект агрегации содержит обязательные поля:

aggregationType - тип агрегации. Возможные значения:
- term - агрегация по термам.
- range - агрегация по диапазонам.
aggregationName - имя агрегации, которое будет использоваться в результатах. Имя поискового атрибута, системное поле.
path - путь до атрибута в OpenSearch, по которому будет производиться агрегация.

Каждый тип агрегации требует заполнение дополнительных полей.

Чтобы запросить только агрегацию - установите параметр "count": 0.

Пример запроса:

{
"aggregations": [
    {
    "aggregationType": "term",
    "aggregationName": "user_search_str",
    "path": "str",
    ...
    }
]
}

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

{
"aggregations": [
    {
    "aggregationName": "user_search_str", // Имя агрегации
    "aggregationType": "term", // Тип агрегации: агрегация по термам
    "documentsCount": 5, // Общее количество документов в агрегации
    "countMap": {  // Карта значений и их частот
        "1": 2, // Значение "1" встречается 2 раза
        "2": 2, // Значение "2" встречается 2 раза
        "3": 1 // Значение "3" встречается 1 раз
    }
    }
]
}

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

aggregationName - имя агрегации, заданное в запросе. Используется для идентификации агрегации в результатах.
aggregationType - тип агрегации, как указано в запросе. Возможные значения:
- term - агрегация по термам.
- range - агрегация по диапазонам.
documentsCount - общее количество документов, попавших под агрегацию.
countMap - объект, где ключи представляют уникальные значения, найденные в поле агрегации, а значения представляют количество документов для каждого уникального значения.

Типы агрегации¶

Агрегация TERM

Пример запроса:

# блок в запросе
{
"aggregations": [
    {
    "aggregationType": "term",            // обязательное
    "aggregationName": "user_search_str", // обязательное
    "path": "str",                        // обязательное
    "size": 10                            // обязательное
    //, "minCount": int

    }
]
}

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

# блок в ответе

{
"aggregations": [
    {
    "aggregationName": "user_search_str",
    "aggregationType": "TERM",
    "documentsCount": 5,
    "countMap": {
        "1": 2,
        "2": 2,
        "3": 1
    }
    }
]
}

Поля запроса:

aggregationType - тип агрегации. Для агрегаций по термам значение должно быть term.
aggregationName - имя агрегации, которое будет использоваться в результатах. Помогает идентифицировать агрегацию в ответе.
path - путь до поля в индексе OpenSearch, по которому будет производиться агрегация. Указывает, какие данные будут агрегироваться.
size - максимальное количество уникальных значений, которые будут возвращены в результате агрегации. Определяет, сколько "ведущих" значений будет включено в результат.
minCount - нижняя граница агрегации. Если в запросе выставлено "1", то результат агрегации со значением "0" в ответ не попадет.

Ограничения использования:

Атрибут должен быть поисковым, или поле в индексе должно быть типа keyword.
Фильтр formFields накладывает ограничения на результат агрегации.

Агрегация RANGE

Примечание

В агрегации типа range, используемой в OpenSearch, верхняя граница to не включается в результирующий диапазон. Это связано с тем, что диапазоны определяются как полуоткрытые интервалы [from, to), что означает включение нижней границы `from` и исключение верхней границы to. Для включения верхней границы значение to должно быть чуть больше необходимого (5.0000001).

Пример запроса:

# блок в запросе
{
"aggregations": [
    {
    "aggregationType": "range",               // обязательное
    "aggregationName": "user_search_range",   // обязательное
    "path": "attr_int",                       // обязательное
    "ranges": [
        {
            "key": "user key definition",   // имя диапазона
            "from" : 1,                     // левая граница включительно
            "to" : 2.001                    // правая граница, до какого значения
        },
        {
            // "key" -  имя диапазона не указано. будет сгенерировано
            "from" : 1,                     // левая граница
            "to" : 2.001                    // правая граница, до какого значения
        }
    ]
    }
]
}

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

# блок в ответе

"aggregations": [
        {
        "aggregationName": "user_search_range",
        "aggregationType": "range",
        "documentsCount": 4,
        "countMap": {
            "user key definition": 2,   // ключ "user key definition" был задан в запросе
            "1.0-2.001": 2              // ключ не был задан, автогенерация
        }
        }
    ]

Поля запроса:

aggregationType - тип агрегации. Для агрегаций по диапазону значение должно быть range.
aggregationName - имя агрегации, которое будет использоваться в результатах.
path - путь до поля в индексе OpenSearch, по которому будет производиться агрегация. Указывает, какие данные будут агрегироваться.
ranges - коллекция диапазонов.
key - произвольное имя диапазона, которое будет использоваться в результатах.
from - левая граница диапазона.
to - правая граница диапазона.

Для объекта в ranges допустимо указать только from или to.

Ограничения использования:

Поле должно быть в индексе.
Тип поля должен быть целочисленным / с плавающей точкой.

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

{
"payload": {
    "org.unidata.dg.rest.v1.data": {
    "aggregations": [
        {
        "aggregationType": "term",                    // аггрегация по типу актива, количеству записей в типе больше 2000
        "aggregationName": "user_search_act",
        "path": "$type_name",
        "size": 10
        },
        {
        "aggregationType": "term",
        "aggregationName": "user_search_act_min_2000", // аггрегация по типу актива, количеству записей в типе больше 2000
        "path": "$type_name",
        "size": 10,
        "minCount": 2000
        },
        {
        "aggregationType": "term",
        "aggregationName": "user_search_act_act1#str", // аггрегация по атрибуту
        "path": "act1#str",
        "size": 3,
        "minCount": 2000
        },
        {
        "aggregationType": "term",
        "aggregationName": "user_search_act_ownership", // аггрегация по владельцу, аттр на стороне be так и выглядит
        "path": "$ownership.username",
        "size": 10
        },
        {
        "aggregationType": "range",
        "aggregationName": "user_search_range",
        "path": "$average_score",
        "ranges": [
            {
            "key": "$average_score 1-5.01", // количество записей с оценкой 1 до 5 включительно
            "from": 1,
            "to": 5.01
            },
            {
            "key": "$average_score 1-5", // количество записей с оценкой 1 до 5 не включительно
            "from": 1,
            "to": 5
            },
            {
            "key": "$average_score 5",    // количество записей с оценкой 5
            "from": 5,
            "to": 5.001
            }
        ]
        }
    ],
    "drafts": false,
    "countOnly": false,
    "totalCount": true,
    "returnFields": [
        "$etalon_id",
        "$average_score",
        "$business_role_assignments"
    ],
    "searchFields": [
        "$etalon_id",
        "$created_at",
        "$updated_at",
        "$display_name",
        "$external_keys",
        "$ownership.username",
        "$tags",
        "$business_role_assignments"
    ],
    "fetchAll": true,
    "entity": "",
    "searchDataType": "ASSET",
    "returnAllFields": false,
    "searchAllFields": false,
    "hierarchical": true,
    "returnAsValues": [
        "$business_role_assignments"
    ],
    "page": 0,
    "count": 0,
    "sortFields": []
    }
}
}