Query Builder в List Filter Online: условия, группы и CAML-запрос, который за ними стоит

Обзор

Query Builder — это часть веб-части Vitextra List Filter Online, в которой редактор страницы задаёт предустановленный фильтр: набор условий, которым должен удовлетворять каждый элемент, прежде чем он появится в веб-части. Пользователи не видят этот фильтр и не могут его снять — они лишь сужают результат с помощью области фильтра и фильтров в заголовках столбцов.

Предустановленный фильтр хранится в виде дерева условий и групп и преобразуется в CAML-запрос, который SharePoint выполняет на сервере. Ничего не загружается в браузер для последующей фильтрации: список возвращает только подходящие элементы, постранично, — именно поэтому веб-часть остаётся быстрой на больших списках.

Типичные сценарии предустановленного фильтра:

• Показывать только документы, созданные или изменённые текущим пользователем.
• Показывать на странице-дашборде только записи за последние 12 месяцев.
• Показывать только утверждённые элементы, элементы с вложениями или элементы, у которых Статус не равен Закрыто.
• Собрать по странице на каждый отдел из одного списка, не создавая отдельное представление для каждого отдела.

Где найти Query Builder

1. Откройте страницу в режиме редактирования и выберите Изменить веб-часть на веб-части List Filter Online.
2. В панели свойств перейдите к группе Фильтр. Под подписью Фильтровать представление по: отображается предварительный просмотр текущего фильтра — Фильтр не применен., если фильтр ещё не задан.
3. Нажмите Изменить фильтр. Query Builder откроется в большой боковой панели.
4. Соберите запрос и нажмите Сохранить, чтобы применить его, или Отмена, чтобы отменить изменения. Веб-часть сразу перерисовывается с новым фильтром.

Query Builder доступен только после того, как в группе Источник данных выбраны сайт и список или библиотека: перечень полей и их типы берутся из выбранного списка.

Условия и группы

Запрос состоит из строительных блоков двух видов.

• Условие — это одно сравнение: поле — оператор — значение, например Amount — Больше — 5000. Некоторым операторам значение не нужно (Содержит данные, Текущий пользователь, Сегодня).
• Группа содержит условия и другие группы и объединяет их одним логическим оператором — И (должны выполняться все члены группы) или ИЛИ (должен выполняться хотя бы один). Переключатель у левого края группы меняет оператор.

В панели всегда есть одна корневая группа; удалить её нельзя. Внутри любой группы кнопка Добавить предлагает две команды:

• Условие — добавляет в текущую группу пустую строку;
• Группа — добавляет вложенную группу (по умолчанию И), которую вы заполняете точно так же.

Группы можно вкладывать друг в друга до десяти уровней. У каждой строки и каждой вложенной группы справа есть значок удаления; при удалении группы удаляется всё её содержимое.

Запрос на рисунке читается так: Название заполнено и начинается с «C» и (создано мной или изменено мной) и (создано за последний год или изменено за последний год) и (есть вложения, или заполнен Клиент и Сумма больше 5 000).

Операторы по типам столбцов

Список операторов в строке зависит от типа выбранного поля. В таблице перечислены операторы, которые Query Builder предлагает для каждого поддерживаемого типа столбца.

Содержит данные и Не содержит данных проверяют, есть ли в столбце какое-либо значение, — так же, как IsNotNull и IsNull в CAML.

Редактор значения тоже зависит от типа столбца: выбор даты для дат (для оператора Между — два поля выбора даты), числовое поле для чисел и валюты, выбор пользователей для столбца Пользователь или группа, выбор терминов для Управляемых метаданных, список Да / Нет для столбцов «Да/Нет» и «Вложения», список статусов для столбца Статус утверждения и текстовое поле для текстовых столбцов, столбцов выбора и подстановки.

Статические и динамические условия

Статическое условие сравнивает столбец с фиксированным значением, которое вы ввели: датой, числом, текстом, пользователем. Значение записывается в запрос как есть. Оператор Между включает обе даты, с точностью до календарного дня; если задана только одна из дат, условие превращается в открытое Не Ранее или Не Позднее.

Динамическое условие SharePoint вычисляет в момент выполнения запроса, поэтому одна и та же страница показывает разные элементы разным пользователям и в разные дни:

Число для Последние X и Следующие X вводится в поле значения строки. Последние X Месяцев и Последние X Лет преобразуются в начальную дату при формировании запроса, поэтому страница с условием Изменён — Последние X Лет — 1 всегда охватывает последние двенадцать месяцев, и никому не нужно править фильтр.

Как предустановленный фильтр сочетается с фильтрами пользователя

Когда пользователь применяет фильтр в области фильтра или в заголовке столбца, веб-часть не заменяет предустановленный фильтр. Она формирует новый запрос, в котором предустановленный фильтр и фильтры пользователя объединены оператором И:

<Where>
  <And>
    <!-- предустановленный фильтр из Query Builder -->
    <!-- условия, выбранные пользователем в области фильтра -->
  </And>
</Where>

Следствия, о которых стоит знать:

• Пользователи могут сузить результат, но никогда не расширят его за пределы предустановленного фильтра. Страница с фильтром Кем создано — Текущий пользователь никогда не покажет чужие элементы, что бы пользователь ни выбрал в области фильтра.
• Сортировка, группировка, итоги и экспорт в Excel работают с объединённым результатом.
• Сохранённые фильтры и ссылки на фильтр (см. KB10253. Сохранение фильтров и ссылка на отфильтрованное представление в List Filter Online) хранят только пользовательскую часть запроса. Предустановленный фильтр — часть конфигурации страницы и перемещается вместе с ней.

От дерева к CAML

CAML — язык запросов к спискам SharePoint — допускает внутри <And> и <Or> ровно два операнда. Поэтому группу из трёх и более членов нельзя записать одним элементом: её приходится сворачивать в цепочку вложенных пар. Query Builder делает это за вас, а заодно учитывает детали, зависящие от типа: атрибут Type у каждого значения, LookupId для столбцов подстановки и IncludeTimeValue для сравнения дат.

Запрос с рисунка выше даёт предложение <Where> примерно в 70 строк. Его скелет — с сокращёнными сравнениями — выглядит так:

<Where>
  <And>
    <Or>  <!-- создано мной ИЛИ изменено мной -->
      <Eq><FieldRef Name="Author" /><Value Type="Integer"><UserID /></Value></Eq>
      <Eq><FieldRef Name="Editor" /><Value Type="Integer"><UserID /></Value></Eq>
    </Or>
    <And>
      <Or>  <!-- создано за последний год ИЛИ изменено за последний год -->
        <And> <Geq Created 2025-10-21 /> <Leq Created <Today /> /> </And>
        <And> <Geq Modified 2025-10-21 /> <Leq Modified <Today /> /> </And>
      </Or>
      <And>
        <Or>  <!-- (клиент заполнен И сумма > 5000) ИЛИ есть вложения -->
          <And> <IsNotNull Customer /> <Gt Amount 5000 /> </And>
          <Eq Attachments 1 />
        </Or>
        <And> <IsNotNull Title /> <BeginsWith Title "C" /> </And>
      </And>
    </And>
  </And>
</Where>

Каждая строка Последние X Лет превратилась в <And> из двух сравнений дат, каждая группа ИЛИ — в элемент <Or>, а четыре члена корневой группы И — в три вложенных элемента <And>.

Просмотр сгенерированного запроса

Чтобы увидеть точный CAML, который отправляет веб-часть, — включая предустановленный фильтр, текущие фильтры пользователя, поля представления, ограничение строк и группировку:

1. В панели свойств разверните группу Средства разработчика и включите параметр Включение режима разработчика.
2. Сохраните страницу. В правой части панели команд веб-части появится меню средств разработчика.
3. Выберите Запрос CAML. Запрос откроется в диалоговом окне, откуда его можно скопировать.

Предустановленные фильтры на больших списках

На списках с более чем 5 000 элементов SharePoint выполняет запрос только в том случае, если первое условие, сужающее результат, использует индексированный столбец. Предустановленный фильтр выполняется первым, поэтому именно он решает, откроется ли страница вообще.

• Начинайте корневую группу с условия по индексированному столбцу (Создан, Изменён, Кем создано, Кем изменено и ИД индексированы по умолчанию; остальные можно проиндексировать в параметрах списка).
• Предпочитайте И в корне: ИЛИ между двумя неиндексированными столбцами не может использовать ни один индекс.
• Динамические условия по дате (Последние X Месяцев, Сегодня) — хорошие первые условия, если столбец даты проиндексирован.

Подробности, предупреждение об индексе в конфигураторе фильтра и создание индекса одним щелчком описаны в статье KB10257. Фильтрация больших списков: индексированные столбцы и порог в 5 000 элементов.

Ограничения

• Query Builder работает со столбцами одного списка или библиотеки — того, что выбран в источнике данных. Условия по столбцам других списков невозможны.
• Значения подстановки и выбора сопоставляются по введённому тексту; отдельного средства выбора для них в Query Builder нет.
• Вложенная группа без условий игнорируется при формировании запроса.
• Максимальная глубина вложенности — десять уровней. На практике двух-трёх уровней хватает почти для любого сценария; более глубокое дерево трудно читать в предварительном просмотре.
• Предустановленный фильтр пользователям не показывается. Если пользователям нужно понимать, почему каких-то элементов нет, скажите об этом в заголовке веб-части или на странице.

Связанные статьи