39 KiB
Запросы
← К разделу «Как собирается сайт»
Запрос — сохранённая выборка документов и правила её представления. Он подходит для новостей, статей, карточек, связанных материалов и других списков.
Части запроса
| Часть | Назначение |
|---|---|
| Рубрики и условия | Определяют документы результата. |
| Сортировка | Определяет порядок результата. |
| Количество и пагинация | Ограничивают выдачу и создают страницы списка. |
| Шаблон элемента | Рендерит один документ. |
| Основной шаблон | Оборачивает готовые элементы и пагинацию. |
| Контракт результата | Явно перечисляет системные свойства и поля, доступные структурированным потребителям. |
| Кеш | Сохраняет результат на заданное время. |
Запрос вставляется по alias:
[tag:request:latest_news]
Обычный и расширенный режимы
Редактор открывается в обычном режиме. Для большинства списков этого достаточно: здесь находятся название, рубрика, количество материалов, сортировка, пагинация, шаблоны и условия.
Расширенный режим нужен, когда вы настраиваете кеш, интеграцию, старый PHP-шаблон, Native executor или точный контракт данных. Если смысл параметра непонятен, оставьте его без изменения и вернитесь в обычный режим.
Переключатель меняет только вид формы. Он не удаляет скрытые настройки и не меняет публичную страницу. Выбранный режим запоминается в текущем браузере.
Простой порядок работы:
- Выберите рубрику.
- Укажите количество материалов и порядок сортировки.
- Добавьте условия, если нужно отобрать не все документы рубрики.
- Проверьте шаблон одного материала и общий шаблон списка.
- Запустите предпросмотр и только затем сохраните запрос.
Как показать результат
В обычном режиме есть отдельный блок «Как показать результат». Он позволяет посмотреть одну и ту же выборку в нескольких видах:
| Вид | Для чего подходит |
|---|---|
| Карточки данных | Проверить все выбранные свойства каждого материала. |
| Компактный список | Быстро просмотреть названия и несколько основных значений. |
| Таблица | Сравнить одинаковые свойства нескольких материалов по колонкам. |
| JSON | Проверить структурированные данные для API и интеграций. |
Выбор сохраняется вместе с запросом, но относится только к предпросмотру в админке. Чтобы применить его, нажмите «Обновить» в блоке предпросмотра.
Публичный сайт продолжает использовать сохранённые шаблоны main и item.
Переключение карточек, списка или таблицы не меняет HTML сайта. Для изменения
публичной разметки нажмите «Редактировать шаблон сайта»: редактор перейдёт
в расширенный режим и откроет текущие шаблоны. Это разделение позволяет
проверять данные, не рискуя случайно изменить работающую страницу.
Условия и группы
Простой плоский список недостаточен, когда части фильтра должны работать с
разной логикой. Используйте группы и явно задавайте И/ИЛИ:
Опубликован
И
(
Рубрика = Новости
ИЛИ Рубрика = Статьи
)
И
(
Тег = Важное
ИЛИ Просмотры > 1000
)
Сначала спроектируйте выражение, затем создавайте группы. Перемещение условия между группами меняет смысл выборки даже при тех же значениях.
Условие И должно сужать текущий набор, ИЛИ — добавлять альтернативу внутри
своей группы. После изменения обязательно проверьте реальный результат, а не
только сохранение формы.
Как читать одну строку условия
Редактор читает каждую строку слева направо:
Поле документа → сравнение → откуда взять значение → значение
Например, строка Цена → больше или равно → параметр min_price → число
означает: посетитель может передать min_price=1000, после чего запрос оставит
документы с ценой от 1000. Если min_price не передан, эта необязательная
строка не участвует в фильтрации.
- Поле — данные документа, которые проверяются.
- Сравнение — правило проверки: равно, содержит, больше, входит в список и так далее.
- Источник — готовое значение редактора либо параметр текущей страницы или формы.
- Значение — редактор сам предлагает подходящий элемент для типа поля: переключатель, список, число, дату или выбор связанного документа.
Коды старых операторов (==, %%, FRE) хранятся для совместимости, но в
редакторе показываются человекопонятные названия. Для новых условий свободный
SQL и PHP не требуются.
Как работают группы
Переключатель в заголовке группы относится ко всем непосредственным элементам этой группы:
- И — должны совпасть все строки и вложенные группы;
- ИЛИ — достаточно одной совпавшей строки или вложенной группы;
- вложенная группа — это скобки, содержимое которых вычисляется отдельно.
Например, выражение Показывать на главной = Да И (Тип = Новость ИЛИ Тип = Статья)
собирается из корневой группы И и вложенной группы ИЛИ. Если оставить
всё в одной группе, смысл будет другим.
Как выбрать сравнение
| Сравнение | Практический смысл |
|---|---|
| Равно / не равно | Проверяет полное значение поля. |
| Содержит / не содержит текст | Ищет фрагмент внутри строки. Для точного элемента составного поля используйте обработку |значение|. |
| Начинается / не начинается с | Проверяет начало текстового значения. |
| Больше / меньше | Сравнивает обычное сохранённое значение. |
| Число больше / меньше | Использует числовой индекс поля и подходит для цены, веса, количества и других чисел. |
| Входит / не входит в список | Сравнивает значение с несколькими допустимыми вариантами. |
| Диапазон | Проверяет нижнюю и верхнюю границу. Для фильтра из формы выберите обработку диапазона. |
| Legacy SQL | Оставлен для старых проектов. Новые правила через него не создавайте. |
Если результат не совпал с ожиданием, сначала проверьте не шаблон, а тип поля и формат сохранённого значения. Число, текст и составное значение с разделителями сравниваются по-разному.
Значение условия
У значения есть три источника:
| Источник | Когда использовать |
|---|---|
| Готовое значение | Запрос всегда сравнивает поле с выбранным или введённым значением. |
| Параметр URL или формы | Фильтр получает значение из адреса страницы или формы посетителя. |
| Код совместимости | Старое условие с PHP. Показывается в расширенном режиме и не нужно для новых запросов. |
В режиме Готовое значение вид поля зависит от его типа:
| Тип поля | Что показывает редактор |
|---|---|
| Флажок | Две понятные кнопки Да и Нет. |
| Список | Готовые варианты из настроек поля; для сравнения со списком можно выбрать несколько. |
| Число | Числовой ввод без стрелок увеличения и уменьшения. |
| Дата | Календарь; старый формат хранения сохраняется автоматически. |
| Связанный документ | Поиск по ID, названию и адресу с учётом рубрик-источников поля. |
| Обычный текст | Строка ввода; для оператора «входит в список» значения указываются через запятую. |
После выбора поля список сравнений также сокращается. Например, у флажка остаются только «равно» и «не равно», а у числа доступны числовые сравнения и диапазоны. Существующий нестандартный оператор не удаляется при открытии формы: его можно проверить и заменить вручную.
Для публичного параметра укажите его имя. Под строкой редактор сразу показывает итоговое правило обычной фразой: какое поле сравнивается, откуда берётся значение и что с ним произойдёт. Например:
Поле «Каталог» содержит параметр «catalog», преобразованный в
|значение|. Пустой параметр не участвует в фильтрации.
Служебное представление можно раскрыть отдельно:
[tag:cond:catalog]
Это не обычный шаблонный тег и не строковая подстановка. Редактировать его
вручную не требуется. Он сообщает компилятору, что значение нужно безопасно
прочитать из параметра catalog.
В обычном режиме редактор выбирает обработку по типу поля. Изменить её вручную можно в Расширенном режиме.
| Обработка значения | Что получает движок |
|---|---|
| Взять текст как есть | Одно текстовое значение. |
| Взять целое число | Одно число без дробной части. |
| Взять десятичное число | Одно число с дробной частью. |
| Взять список | Несколько значений, любое из которых может дать совпадение. |
| Взять диапазон от/до | Массив с ключами min и max; пустая граница не применяется. |
| Обернуть значение: ` | значение |
| Обернуть список: ` | значение |
| Подставить константу, если заполнено | Пока параметр пуст, условия нет; при заполнении сравнивается указанная константа. Только в этом режиме показывается поле константы. |
Пустой необязательный параметр полностью исключает условие из дерева. Поэтому не добавляйте разделители или SQL вокруг тега вручную: способ хранения задаётся вариантом Как читать. Alias поля подставляется при выборе источника, но его можно заменить, если публичный URL исторически использует другое имя, например oldprice для поля old.
Каталог создаёт такие же условия, а не отдельный фильтр в обход запросов. Одиночные значения, флажки, множественный выбор и диапазоны остаются элементами общего дерева И/ИЛИ и редактируются в запросе.
Пример: раздел каталога
Условие запроса товаров обычно выглядит так:
- Поле — Каталог.
- Сравнение — содержит.
- Источник — параметр URL или формы.
- Имя параметра —
catalog. - Обработка — обернуть значение:
|значение|.
При значении catalog=95 движок ищет в поле каталога точный маркер |95|.
Это не даёт разделу 9 случайно совпасть с разделом 95. Если параметр
отсутствует или пуст, условие не возвращает ложный результат, а полностью
пропускается. Остальные активные условия запроса продолжают работать.
Шаблон элемента
Шаблон получает текущий документ и его поля. Типичный элемент:
<article class="teaser">
<h2><a href="[tag:link]">[tag:doctitle]</a></h2>
<div>[tag:rfld:excerpt][0]</div>
</article>
Откройте кнопку Теги именно у редактора Шаблон одного материала. Первая группа Поля рубрики строится по выбранной рубрике запроса. В ней рядом с названием и типом поля показан готовый тег:
[tag:rfld:title][0]
[tag:rfld:image][0]
По возможности используется системный alias поля, а если его нет — ID. Суффикс
[0] включает обычный публичный шаблон поля для списка. Для изображения внутри
тега превью можно заменить его на [img], например:
[tag:c760x460:[tag:rfld:image][img]]
Группа полей не показывается в палитре общего шаблона: там ещё нет текущего
документа, а готовые карточки вставляются тегом [tag:content]. Не выполняйте
отдельный SQL-запрос для каждого элемента списка.
Основной шаблон
Основной шаблон получает уже собранные элементы и отвечает за контейнер, заголовок и пагинацию. Не дублируйте в нём разметку одной карточки.
Проверьте отдельно обычную и постраничную выдачу: у пагинации могут быть иной URL и активное состояние.
Контракт результата
Контракт отвечает не за поиск документов и не за HTML. Он перечисляет данные, которые разрешено передать API, предпросмотру или renderer'у:
- системные свойства документа: ID, название, alias, тизер, состояние и даты;
- выбранные поля рубрики;
- стабильные системные ключи и alias полей.
Например, для списка новостей достаточно названия, alias, тизера, даты и поля с обложкой. Цена и остаток в такой контракт не попадут, если они не выбраны.
Пустой старый контракт автоматически получает безопасный базовый набор системных свойств. Выбор полей сохраняется вместе с запросом и переносится контент-пакетом. Удалённое или чужое поле при сохранении отбрасывается.
Контракт первой итерации не меняет теги и HTML существующего сайта. Публичный
вывод по-прежнему выполняют шаблоны main/item, помеченные в редакторе как
Legacy renderer.
Рядом можно выбрать renderer предпросмотра:
- Карточки данных удобны для визуальной проверки выбранных свойств;
- JSON показывает тот же контракт в машинном формате.
Выбор сохраняется у запроса, но не переключает публичную страницу. Поэтому можно проверять будущий API-формат, не меняя карточки и листинги сайта.
Режим выполнения
У запроса есть три режима executor. Они меняют только получение списка
документов. Шаблоны main/item, разметка карточек и публичные URL остаются
прежними.
| Режим | Что происходит |
|---|---|
| Legacy | Работает прежняя выборка со всеми историческими PHP- и SQL-возможностями. Это безопасное состояние по умолчанию. |
| Shadow | Публичный сайт продолжает использовать Legacy. В Adminx тот же запрос дополнительно выполняется Native executor'ом и результаты сравниваются. |
| Native | Список выбирается по параметризованному плану без исполнения PHP из значений условий. Старые шаблоны продолжают рендерить результат. |
Native нельзя выбрать сразу. Сначала сохраните запрос, включите Shadow и запустите предпросмотр. Система сравнит:
- общее количество документов;
- ID документов в проверяемом окне;
- порядок документов;
- текущую версию условий, групп, рубрики и сортировки.
Если всё совпало, появится состояние Native подтверждён и режим станет доступен. Подтверждение связано с хешем плана. Изменение условия, группы, рубрики или сортировки автоматически снимает его; после сохранения нужно снова запустить сравнение.
Для автоматического подтверждения порядок должен заканчиваться уникальным системным полем ID. Одинаковая дата публикации, позиция или цена может быть у нескольких документов. Без финального ID MySQL вправе переставить такие строки после очистки кеша, даже если состав списка не изменился. В этом случае Adminx покажет Порядок не закреплён и сохранит Shadow/Legacy. Это защищает пагинацию, меню и карточки от незаметной перестановки.
Для текстовой сортировки равенство определяется той же collation базы, что и в
реальном ORDER BY. Например, MODEL-X и Model-X обычно считаются одним
значением. В диагностике они будут показаны как два исходных текста, но причина
останется той же: таким строкам нужен отдельный финальный порядок.
В конструкторе порядка нажмите «Закрепить по ID». Система добавит ID последним уровнем по возрастанию. При необходимости направление можно поменять. Это не заменяет предыдущие уровни: дата, цена или позиция остаётся главным правилом, ID только стабилизирует строки с одинаковым значением. У случайного порядка с заполненным ключом ID добавляется автоматически как незаметный финальный признак; вручную добавлять его не нужно.
Автоподтверждение сравнивает до 5000 документов целиком. Более крупная выборка помечается как неполная и остаётся на Legacy, даже если её начало совпало.
Native использует декларативные источники HTTP-параметров: необязательное целое, десятичное число, строку, список, диапазон, составное значение и константу по наличию параметра. PHP при этом не исполняется. Аудит проверяет состояние без параметров, каждый параметр отдельно и их сочетание; для теста берётся реальное значение соответствующего поля, когда оно доступно.
Запрос останется на Legacy, если использует произвольный FRE, ANY, произвольный PHP,
[field], случайную сортировку без постоянного ключа или переданные при вызове сырые USER_WHERE,
USER_FROM, USER_JOIN, ORDER, SQL_QUERY. Adminx показывает конкретные
причины. Эти возможности не интерпретируются приближённо.
Декларативный диапазон и множественный фильтр могут хранить исторический код
оператора FRE, но внутри у них уже нет свободного SQL: Native строит
параметризованное сравнение по сохранённому типу.
Даже в режиме Native действует защитный fallback: неподдерживаемый runtime- параметр или неподтверждённая версия плана выполняются через Legacy. Для быстрого ручного отката достаточно вернуть режим Legacy.
Массовая проверка
На странице списка запросов откройте Проверка Native. Эта страница нужна для безопасного перехода существующего сайта:
- Проверить все переводит запросы в Shadow. Распознанным старым условиям записывается типизированное описание рядом с исходным PHP, но публичный HTML продолжает собираться Legacy executor'ом.
- Adminx последовательно сравнивает до 5000 документов каждого запроса, не создавая одновременную нагрузку на БД. Если состав Legacy-выборки совпал во всех состояниях параметров, PHP заменяется декларативным тегом и Legacy проверяется ещё раз по хешу полного списка ID. При отличии значение автоматически возвращается.
- В таблице отдельно видны точное совпадение, несовпадение порядка, незакреплённая сортировка и legacy-код. Для несовпадения порядка показывается первая отличающаяся позиция, ID из Legacy и Native и фактические значения ключа сортировки. Например, одинаковая дата или цена сразу показывает, что фильтр совпал, а запросу не хватает только финального ID.
- Закрепить порядок обрабатывает только незакреплённые запросы. Для каждого
из них и запросов с отличием порядка система целиком сравнивает прежний
Legacy-порядок сначала с
Id ASC, затем сId DESC. Подходящее направление сохраняется только при точном совпадении всех ID. После записи выполняется повторная контрольная сверка; при любом отличии настройка и прежний режим автоматически восстанавливаются. - Включить подтверждённые меняет executor только у запросов с актуальным хешем, полным совпадением и уникальным финальным порядком. Условия запросов без стабильной сортировки уже могут быть переведены на теги, но сам запрос останется в Shadow/Legacy.
- Вернуть Legacy одним действием откатывает все запросы. Хеши проверки сохраняются, но после изменения запроса всё равно потребуют новой сверки.
Если ни одно направление ID не воспроизводит существующую выдачу, запрос остаётся в Shadow/Legacy. Это нормальный результат: система не пытается «приблизительно» исправить порядок и не меняет публичную страницу.
Смена режима очищает кеш настроек и элементов запросов. Поэтому контрольные страницы после активации проверяйте заново, а не по старому закешированному HTML.
Предпросмотр данных
Кнопка Обновить выполняет сохранённую выборку, не запускает шаблоны
main/item и одновременно проводит теневое сравнение Legacy/Native. Поэтому
результат показывает данные и совместимость, а не дизайн сайта.
В предпросмотре доступны:
- общее количество найденных документов;
- первые 5, 10 или 20 результатов;
- время SQL;
- рубрика, число групп и активных условий, сортировка и публикационные ограничения;
- только свойства, выбранные в контракте;
- SQL для пользователя с правом управления запросами.
- состояние Native-плана, причины несовместимости и различающиеся ID.
Если вы изменили рубрику, сортировку или основные параметры запроса, сначала сохраните форму. Выбор полей контракта передаётся в preview сразу и может быть проверен до сохранения.
Каждый показанный документ уже прошёл всё дерево условий. Чтобы проверить исключённый материал, найдите его по ID, названию или alias в строке Почему документ попал или не попал? и нажмите Объяснить.
В правой панели отдельно показаны:
- рубрика, состояние, удаление и срок публикации;
- результат каждой группы И/ИЛИ;
- фактическое значение поля и ожидаемое значение;
- окончательный ответ реального executor.
Свободное условие FRE может содержать PHP, SQL или runtime-параметры. Инспектор
не исполняет такой код повторно и честно помечает условие как неопределённое,
но итог «входит / не входит» всё равно получает из настоящей выборки.
Сортировка
Порядок собирается сверху вниз. Первое правило является главным, второе применяется при совпадении первого, третье — при совпадении первых двух.
Пример:
1. Дата публикации — по убыванию
2. Название документа — по возрастанию
3. ID документа — по возрастанию
Так новые материалы показываются первыми, материалы с одинаковой датой упорядочиваются по названию, а ID делает итог стабильным для пагинации.
Нажмите «Добавить уровень», выберите системное свойство документа или поле рубрики и задайте направление. Строки можно переставлять за левый маркер. Одинаковое поле нельзя добавить дважды; доступно не больше восьми уровней. Случайный порядок используется отдельно и не сочетается с другими правилами.
После его выбора появляется Ключ порядка. Пустой ключ перемешивает
материалы заново, как прежний RAND(). Одинаковый числовой ключ всегда даёт
одинаковый порядок и подходит для пагинации: переход на следующую страницу не
перемешивает уже показанные материалы.
Например, ключ 2026 можно оставить постоянным, а для ежедневной подборки
менять его планировщиком раз в день. SQL для этого писать не требуется.
Для больших списков выбирайте поля с однозначным типом и числовым индексом. SQL писать не требуется. Кнопка «Закрепить по ID» добавляет безопасный последний уровень и предотвращает перестановку элементов между страницами.
Старые запросы открываются в новом конструкторе без миграции вручную. Их историческая последовательность «поле рубрики → системное поле → ID» сохраняется. После сохранения полный порядок записывается в JSON, а старые колонки продолжают заполняться для совместимости с прежними интеграциями.
Поле Шаблон пагинации показывает реальные шаблоны из настроек по названию и ID. Удалённый или несуществующий шаблон сохранить нельзя: сначала выберите действующий либо создайте новый в настройках пагинации.
Кеш
Время жизни 0 отключает долговременный кеш результата. Большой срок подходит
стабильным спискам, но задерживает появление новых документов. Сохранение
документа очищает связанные ключи там, где зависимость известна; проектные
внешние данные могут потребовать явной инвалидации.
Перед выводом списка движок сам собирает ID документов и пакетно подготавливает
их JSON-снимки и поля. Поэтому шаблон элемента может продолжать использовать
обычные [tag:doc:*] и [tag:rfld:*]: переносить поля в SQL запроса ради
скорости не требуется. Если снимка ещё нет, первая страница создаст его; далее
используется готовый файл. Сохранение документа обновляет снимок автоматически.
Не включайте общий кеш для результата, который зависит от пользователя, сессии или непредставленных в ключе параметров.
Внешний и AJAX-вызов
Эти флаги разрешают получить запрос вне обычной страницы. Включайте их только
для реально используемого endpoint и проверяйте права, входные параметры и
кеширование. Внутреннему тегу [tag:request:alias] они не нужны.
Проверка запроса
- Выберите минимальный контракт результата.
- Запустите структурированный предпросмотр и сверьте первые документы.
- Сверьте количество результатов без кеша.
- Проверьте каждую группу условий отдельно.
- Проверьте пустую выдачу и один элемент.
- Проверьте первую, вторую и последнюю страницу пагинации.
- Проверьте активность и дату публикации документов.
- После включения кеша повторите изменение одного документа.
- Оставьте режим Shadow на реальном трафике, затем включайте Native отдельно для каждого подтверждённого запроса.