Виртуальная сущность, или проекция, собирает ответ из выбранных полей существующей persistent-сущности. Например, блок страницы можно вернуть вместе с данными страницы и списком элементов. Новая таблица не создаётся, данные не копируются.
В ответ можно включить поля исходной записи, прямые belongsTo и ограниченные коллекции hasMany/manyToMany. Такая сущность доступна только для чтения.
Как собрать выборку через UI
Откройте Content → New entity, выберите virtual и исходную persistent-сущность. Укажите имя и модуль. В Fields → Configure fields выберите поля корня и нужные прямые связи, затем сохраните через Finish.
Для выбранных полей можно задать выходные имена — псевдонимы. Они меняют имя в API-ответе, но не колонку БД. Все имена результата должны быть уникальны.
Поиск, фильтры и порядок записей
У подходящих скалярных полей включите Searchable, Filterable и Sortable. Эти настройки задаются у проекции отдельно: признаки исходного persistent-поля не наследуются. Поиск работает с string и text.
Поля belongsTo участвуют в поиске и фильтрации корневого списка. Сортировка по ним меняет порядок корневых записей. У каждой коллекции собственные настройки: Default limit, Maximum limit, порядок по умолчанию и разрешённые операции над полями.
Например, сортировка pageItems по position упорядочит элементы отдельно внутри каждого блока. При равных значениях первичный ключ делает порядок стабильным.
Какие записи отдавать через external API
В Access находятся Entity CRUD access, External READ access и Generated routes. Правила external-чтения разделены по источнику, прямым belongsTo и выбранным коллекциям. Внутри каждого раздела можно объединять условия через И/ИЛИ.
Допустим, нужны блоки только опубликованных страниц и только видимые элементы:
- Page.status = published ограничивает страницы, к которым относятся блоки.
- PageBlock.isVisible = true оставляет видимые блоки.
- PageItems.isVisible = true И bodyMarkdown != пустой строке отбирает элементы внутри каждого блока.
Последнее правило не скрывает блок, если подходящих элементов нет: у блока останется пустая коллекция.
Добавляйте условия кнопкой + Add. Иконка перед корзиной помещает условие в группу, корзина удаляет условие или группу. Пустое текстовое значение означает "", а не NULL.
Правила задаются отдельно для виртуальной сущности и не наследуются от API её источников. Они ограничивают external list/get; административное чтение не меняется.
Как увидеть результат
После Generate и обновления приложения откройте виртуальную сущность в системе администрирования. В списке будут выбранные поля, в карточке — связанные данные. У коллекций можно использовать разрешённые поиск, фильтры, сортировку и пагинацию. Для изменения записи откройте её persistent-сущность.
Как передать условия из API-клиента
Для корневого списка используются limit, offset, searches, filters, sort, order. Для коллекции с alias pageItems — pageItemsLimit, pageItemsOffset, pageItemsSearches, pageItemsFilters, pageItemsSort, pageItemsOrder.
pageItemsSort=position&pageItemsOrder=asc
pageItemsFilters=[{"field":"title","op":"ne","value":""}]
В клиентских фильтрах указывайте выходные имена выбранных полей. В правилах генератора используются имена источника. Условия клиента добавляются к обязательным правилам и не могут их отменить.
Сервер сначала фильтрует данные, затем считает total и применяет пагинацию. В одном list-запросе параметры коллекции одинаковы для всех родителей. В Details системы администрирования у коллекций есть отдельные элементы управления.
Что учитывать при изменении проекции
Проекция не позволяет редактировать вложенные записи. Поддерживаются выбранные прямые связи; произвольно расширить ответ или построить проекцию из другой проекции нельзя. Коллекции загружаются пакетами: один HTTP-запрос не обязательно означает один SQL-запрос.
Изменили поля, правила или модель — выполните Generate и перезапустите приложение. При смене источника пересмотрите выборку. Недопустимое поле или ссылка в правиле вызовут ошибку при сохранении или генерации, а не будут незаметно исключены.
Подробные шаги: Content: виртуальные сущности и Content: доступ. Для автоматизации есть CLI: проекции.