Дизайнер JPQL

Дизайнер JPQL - это визуальный инструмент, созданный упростить создание и редактирование запросов на языке Java Persistence Query Language (JPQL) в ваших приложениях на Jmix. Его цель - снять часть сложности, связанной с ручным написанием JPQL, делая работу с доступом к данным более удобной для разработчиков любого уровня.

Дизайнер JPQL предоставляет визуальный интерфейс для конструирования JPQL-запросов. Вы можете задавать целевые таблицы, условия выбора данных, сортировку и другие параметры без прямого написания кода JPQL. Инструмент формирует корректно отформатированную строку JPQL-запроса.

Эта функция свободно доступна для использования в небольших проектах с количеством сущностей и ролей до 10. В более крупных проектах она требует RAD или Enterprise подписку.

Основные функции включают:

  • Визуальное проектирование запросов: графический интерфейс позволяет создавать JPQL-запросы без непосредственного ввода синтаксиса JPQL.

  • Интеллектуальное автозаполнение: контекстно-зависимые подсказки по атрибутам и сущностям минимизируют ручной ввод и ошибки.

  • Проверка синтаксиса запросов: проверка правильности синтаксиса и распространённых ошибок в режиме реального времени обеспечивает целостность запроса.

Запуск дизайнера JPQL

Вы можете запустить JPQL дизайнер следующими способами:

  • Через палитру сниппетов кода с часто используемыми действиями при создании операций загрузки данных (загрузка сущности или списка сущностей).

  • Через маркер строки, который появляется рядом с существующим JPQL-запросом, облегчая его редактирование.

    jpql designer launch 1

  • Через панель инспектора Jmix UI, открыв свойство query.

    jpql designer launch 2

Диалоговое окно дизайнера JPQL

Дизайнер JPQL предоставляет диалоговое окно, в котором отображается структура запроса и даётся возможность пользователям редактировать и расширять функциональность запроса.

jpql designer

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

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

  • Наличие в результирующем запросе всех атрибутов сущности, используемых для сортировки.

  • Совместимость типов данных встроенных параметров, используемых в условиях, с типами данных атрибутов сущности, с которыми они сравниваются.

При сохранении структуры JPQL-запроса дизайнер генерирует строку JPQL и сохраняет её в исходном Java-коде или XML-файле, из которого был вызван дизайнер.

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

Выбор корневой сущности

При создании нового запроса дизайнер предлагает пользователю выбрать корневую сущность запроса (раздел «from E»).

jpql designer 1

  • Поле Entity class содержит список доступных вариантов с возможностью быстрого поиска по имени класса или имени сущности.

  • В поле Entity alias пользователь должен ввести алиас для выбранной сущности, который затем проверяется на соответствие синтаксису JPQL.

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

Результаты JPQL-запроса

Поле Result type используется для указания выходных параметров запроса.

jpql designer 2

В качестве выходного параметра могут быть выбраны:

  • Сама корневая сущность как объект результата.

  • Атрибут сущности или вложенный путь к атрибуту сущности (например, student.group.number).

  • Агрегатные функции, применённые к корневой сущности или её атрибутам: AVG, COUNT, MIN, MAX, SUM.

Можно указать несколько выходных параметров. Дополнительно доступна опция Distinct для исключения дублирующихся значений.

Задание условий запроса

Дизайнер JPQL предлагает несколько способов указать условия запроса, позволяя фильтровать и сортировать получаемые данные. В этом разделе подробно рассматривается использование операторов WHERE, HAVING и ORDER BY в дизайнере JPQL.

Фильтрация результатов с помощью WHERE

Оператор WHERE используется для фильтрации строк на основе одного или нескольких заданных условий в JPQL-запросах.

В JPQL дизайнере вы можете задать условия WHERE, используя удобный визуальный интерфейс, который отображает атрибуты сущности и связанные с ними значения. Для этого нужно:

  • Выбрать алиас сущности, атрибут или вложенный путь к атрибуту из списка доступных.

  • Выбрать оператор сравнения (например, =, <>, >, <, LIKE, IN).

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

Дизайнер JPQL-запросов предоставляет следующие возможности:

  • Построение подусловий:

    • Выбор логического оператора: =, <>, >, <, >=, <=, IN, NOT IN, LIKE, NOT LIKE, IS NULL, IS NOT NULL.

    • Поддержка модификаторов (%, _) для шаблонов LIKE.

    • Поддержка строковых функций: LOWER, UPPER, TRIM и других.

    • Поддержка функций даты и времени: CURRENT_DATE, CURRENT_TIME, CURRENT_TIMESTAMP и других.

  • Объединение условий:

    • AND: оба условия должны быть true.

    • OR: достаточно, чтобы было истинным хотя бы одно из условий.

  • Параметризованные условия:

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

Условия для запроса можно добавить, нажав на ссылку Add query condition или кнопку Add (+).

jpql designer 3

Затем выберите атрибут сущности в диалоговом окне Choose Attribute и укажите требуемый оператор из списка доступных:

jpql designer 4

Чтобы задать параметр запроса, нажмите кнопку …​ в колонке Parameter. Откроется диалоговое окно, где можно ввести имя параметра вручную, выбрать атрибут сущности или использовать функцию.

jpql designer 6

Условия запроса могут группироваться с помощью операторов AND и OR. Итоговый запрос может выглядеть, например, следующим образом:

jpql designer 5

Сортировка результатов с помощью ORDER BY

Оператор ORDER BY позволяет сортировать результаты запроса по одному или нескольким атрибутам в порядке возрастания (ASC) или убывания (DESC).

Вкладка ORDER позволяет задать один или несколько критериев сортировки. Критерием сортировки может быть:

  • Атрибут корневой сущности.

  • Вложенный путь к атрибуту (например, student.group.number).

Для каждого критерия сортировки необходимо выбрать порядок сортировки: ASC (по возрастанию) или DESC (по убыванию).

Фильтрация агрегированных данных с помощью HAVING

Оператор HAVING используется специально для работы с агрегированными данными. Он фильтрует группы на основе результатов агрегатных функций (например, COUNT, SUM, AVG, MIN, MAX).

Вкладка HAVING отображается, если пользователь выбирает тип результата Tuple и применяет агрегатную функцию к атрибуту сущности.

jpql designer 7

Функция GROUP BY активируется, если пользователь выбирает атрибут сущности в блоке Select без указания к нему агрегатной функции (то есть оставляет поле Aggregate пустым).