Обзор

Запросы - это объекты, в которых настраивается параметры и критерии запросов данных к API системы, параметры сортировки, пагенация и т.д.

Для внешнего получения данных запроса можно его вызвать, использую GET-запрос по адресу:

http(s)://домен/псевдоним/gui/query/идентификтор_запроса

• идентификтор_запроса - это id-запроса (именуется пользователем) или его uid (формируется автоматически при создании)

Например: 
http://buildbox.app/buildbox/gui/query/test_message

При разработки проектов с использованием Buildbox Studio созданных объект запроса выбирается в "Блоке" страницы.

Создание запроса

Ключевой момент работы с данными - создание и настройка объекта запроса

Запрос - это объект, который необходимо создать в шаблона "Запросы", для этого нажмите на шаблона и нажмите кнопку создания объекта.

Стоит учитывать тот факт, что для каждого создаваемого проекта существуют системные запросы (пункт основного меню "Сервисные" - "Запросы (системные)" и запросы для каждого приложения, разрабатываемого в рамках данного проекта (пункты меню "Приложения" - "ваш_проект" - "Запросы"

Это позволяет портировать приложения между различными сервисами, сохраняя все используемые в приложении запросы.

При создании запроса необходимо настроить следущие параметры:

 

Создание фильтров

Для получения данных необходимо создать минимум один фильтр и указать его в "Схема фильтро"

Фильтр - это отдельный подзапрос на получение данных.

Для создания фильтра необходимо нажать кнопку "+" создания в списке фильтров внутреннего запроса.

В открывшейся форме заполните следущие параметры:

• Название (обязательно)
• Описание
• Идентификатор (обязательно) - необходим для указания фильтра в "Схеме фильтров"
• К запросу - связь фильтра с данным запросом (выбираеся автоматически)
• Выбирать - выбор типов выбираемых объектов (Объекты/Поля/Шаблоны) (по-умолчанию - Объекты).
  Существует три типа объектов, в основном пользователь работает с Объектами, но сам Шаблон и Поля на форме шаблона тоже являются объектами, которые в исключительных случаях требуется получить из базы данных.

Условия поиска

При создании фильтров

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

Критериев поиска всего 5:

1. Из шаблона(-ов) - идентификатор шаблона, в котором производится поиск

2. ID-объектов (SRC) - идентификатор связи. В выборку будут попадать объекты связанные с объектом, у которого данных интификатор.

3. Значение (VALUE) - значение поля value (текстовое название выбранного объекта).

4. В элементе (ELEMENT) - id поля, в котором будет производиться поиск

5. UID объекта - идентификатор самого объекта

Стоит отметить, что каждое поле объекта имеет все 5 критерием.

Например, если вы выбрали в селекте (выподающее меню) объект, связанный с данным, то значение данного поля будет содержать в качестве src - идентификтор связанного объекта, value - заголовок объекта, element - id выбранного поля.

• Направление связи - параметр указывающий, какой тип связи учитывать. Мы можем учитывать Входящими связи (другие объекты ссылаются на объект) и Исходящие связи - связи объектов шаблона, которые ссылаются на другие объекты.

 

Логические операторы

Для поля "Значение (VALUE)" - можно использовать логические операторы.

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

1. Если используется перечисление значений (например при операторе IN), то значения необходимо брать в одиночные кавычки (') и разделять запятой (,)
   Например: IN 'значение1','значение2'
2. По-умолчанию используется операция сравнения (если значение равно "=").

Перечень поддерживаемых операторов:

• = - равно значению (по-умолчанию, если ничего не указано)
  Пример: = 'булочка с изюмом'
• > - если значения больше текущего
• < - если значения меньше текущего
• >= - если значения больше или равно текущему
• <= - если значения меньше или равно текущему
• IN - если значения находится в заданном списке
  Пример: IN 'сделано','отмечено'
• NOTIN - значения не входящие в список
• NOT или != или <> - если значение поля value не равно заданному
• NULL или ISNULL - если значение поля value пустое
• LIKE - поиск по шаблону (синтаксис схож с SQL) (см.ниже)

LIKE используются два подстановочных знака:

• % - Знак процента представляет нулевой, один или несколько символов
• _ - Подчеркнутый символ представляет собой один символ

Например: LIKE 'Т%' - выбирает объекты, если значение в поле value начинается с «Т»

Выражение	Описание
LIKE 'text%'	Находит любые значения, начинающиеся с "text"
LIKE '%text'	Находит любые значения, заканчивающиеся на "text"
LIKE '%text%'	Находит любые значения, которые имеют «text» в любой позиции
LIKE '_text%'	Находит любые значения, которые имеют «text» во второй позиции
LIKE 'text_%_%'	Находит любые значения, начинающиеся с «text» и длиной не менее 3 символов
LIKE 'text%data'	Находит любые значения, начинающиеся с «text» и заканчивающиеся на «data»

Логические операции с фильтрами

Запрос может содержать несколько фильтров (источников данных), которые в дальнейшем могут быть скоминированны между собой.

Результатом выполнения каждого фильтра является массив идентификторов объектов, которые могут быть подвержены логическим операциям (объединения, пересечения), а также запуска другого запроса.

• AND - находит пересечение множеств полученных объектов
• OR - производит сложение полученных множество (если один объект попадае в результаты двух фильтров, то в результирующем массиве он указываетс один раз)
• RUN - вызов другого запроса, в качестве дополнительного фильтра внутри запроса.

Например:

AND filter1, filter2

где:

• AND - логическая операция
• filter1, filter2 - названия фильтров

Ответ запроса

Данные, полученные в теле ответа запроса имеют стандартизованный формат, если запрос "внутренний" (был сформирован внутри Buildbox и получал данные из базы данных), то формат ответа имеет из себя следующий вид:

{
    "data": {}, - ту массив данных для внутреннего запроса и объекты без заданной структуры для внешнего
    "res": null,
    "status": {
        "description": "описание запроса",
        "status": (200 - все ОК, другие статусы говорят об ошибке),
        "error": "описание ошибки",
        "code": "код ошибки"
    },
    "metrics": {. - блок метрик выполнения запроса
        "result_size": 0, - общее количество объектов в результате
        "result_count": 0, - количество объектов в данной выдаче (мы можем получать не все данные, а и часть)
        "result_offset": 0, - сдвиг относительно начала выборки
        "result_limit": 0,  - лимит на страницу
        "result_page": 0, - текущая страница
        "time_execution": "",  - время выполнения запроса
        "time_query": "" - время получения данных из базы
    }
}

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