Запросы к данным через REST API¶

Точечный запрос объекта¶

Точечные запросы предполагают получение одного объекта по уникальному индексу. Для выполнения точечного запроса по полному совпадению достаточно выполнить один GET-запрос с параметром <index_name>=<value>, например, title_index=Berlin:

curl http://localhost:8081/data/City?title_index=Berlin

Пакетная обработка¶

В случае выполнения запросов с неизвестным количеством результатов необходимо учитывать пагинацию – постраничную разбивку возвращаемых объектов. По умолчанию размер одной страницы равен 10. Это значит, что ответ на один запрос с условиями будет содержать максимум 10 записей, даже если подходящих объектов больше.

Если вы заранее знаете, сколько объектов хотите получить, вы можете изменить объём страницы с помощью параметра first. Например, получить 25 объектов, подходящих под условие выбора:

curl http://localhost:8081/data/City?population_ge=100000&first=25

Если количество результатов заранее неизвестно, нужно реализовать пакетную обработку (batching) с использованием курсоров. Курсоры позволяют задать начальный объект страницы.

Например, для получения всех объектов типа необходимо выполнять запросы в цикле с указанием параметра after - курсора последнего элемента, полученного в предыдущем запросе. Скрипт для выполнения такого цикла может выглядеть следующим образом:

while true; do
    url="http://127.0.0.1:8181/data/City?first=25"
    if [[ -n "$cursor" ]]; then
        url=$url"&after=$cursor"
    fi
    res=$(curl -s --url $url)
    if [[ $res == "[]" ]]; then break; fi
    len=$(echo $res | jq length)
    echo $len
    cursor=$(echo $res | jq ".[$len - 1].cursor")
done

Порядок возврата результатов¶

Порядок возврата результатов определяется индексом, используемым для выбора объектов, и условием выбора:

• «меньше» и «меньше или равно» – по убыванию индекса

• «больше» и «больше или равно» – по возрастанию индекса

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

Объекты можно запросить в порядке возрастания любого из доступных индексов. Для этого используется параметр indexed_by=<index_name>:

curl http://localhost:8081/data/City?indexed_by=population&first=25

Использование составных индексов¶

Если необходима фильтрация объектов по одному полю и сортировка по другому, рекомендуется использовать составной индекс, содержащий оба этих поля.

Пример: есть тип данных с полями типа string и datetime. Например, «событие»: у него есть дата и время (datetime) и идентификатор объекта, с которым произошло событие (string).

Допустим, нужно получить все события, произошедшие с выбранным объектом, по убыванию даты.

Для этого нужен составной индекс, включающий оба поля (object_datetime_index). Использовать этот индекс для поиска по полному совпадению не получится, поскольку изначально известен только идентификатор объекта, но не дата. Поэтому нужно выполнять поиск по условию «меньше или равно» с указанием только идентификатора объекта:

curl http://localhost:8081/data/Events?object_datetime_index_le="object_id"

В этом случае объекты будут фильтроваться только по идентификатору, без условий выбора даты. Но оператор сравнения «меньше или равно» применяется и к дате, поэтому результаты будут упорядочены по её убыванию.

При этом результат будет содержать лишние объекты с идентификаторами меньше указанного. Такие объекты нужно отсеять, отфильтровав массив полученных результатов в коде приложения.

Массовое удаление¶

Для массового удаления объектов можно использовать точечные DELETE-запросы с прохождением по списку объектов, например, полученному с помощью GET-запроса.

Однако, лучшим решением будет реализация массового удаления с помощью сервис-функций. Этот способ позволяет реализовать удаление с учётом особенностей схемы данных и в общем случае имеет лучшую производительность.