Поля и вычисляемые поля

Поля датасета — это колонки, которые видят виджеты. Их можно переименовывать, менять им тип и агрегацию по умолчанию, скрывать из выдачи и дополнять вычисляемыми полями.

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

Настройка обычного поля

Каждая строка списка — поле датасета:

Колонка	Что задаёт
Имя	Как поле называется в интерфейсе
Источник поля	Откуда оно берётся, например orders.amount
Тип	Как трактовать значение: целое число, дробное число, строка, дата и время
Агрегация	Функция, которая применяется к полю по умолчанию
Описание	Пояснение для тех, кто будет строить виджеты

Три значка справа

В конце каждой строки — три значка. Они делают с полем то, что иначе пришлось бы повторять в каждом виджете.

Значок	Что делает
Глаз	Скрывает поле: оно остаётся в датасете, но не предлагается при сборке виджета
Форматирование	Задаёт, как значение выглядит везде: префикс и постфикс, сокращение крупных чисел, разделители разрядов и дробной части, знаки после запятой, подпись отсутствующего значения
Сортировка	Задаёт порядок значений поля в виджетах

У вычисляемого поля добавляются ещё два: карандаш — правка формулы, корзина — удаление. В колонке «Источник поля» у него вместо имени таблицы стоит значок f(x).

Настройки применяются к выходной витрине датасета — то есть ко всем виджетам, построенным на нём.

Порядок значений поля

Значок сортировки открывает окно Настройки поля с единственной настройкой — Сортировать по. Вариантов два: по значениям самого поля или по другому полю той же таблицы.

Второй вариант решает известную беду: месяцы, отсортированные по алфавиту. Отсортируйте поле «Месяц» по полю «Номер месяца» — и в каждом виджете январь встанет перед февралём, а не после августа. Так же поступают с размерами одежды, категориями важности и любыми списками, у которых свой, не алфавитный порядок.

Формат числа здесь тот же, что и в конструкторе виджета, — см. Виджеты. Разница в том, что заданный в датасете формат действует во всех виджетах сразу, а формат в виджете переопределяет его для одной визуализации.

Кнопка Группа или бин объединяет значения поля в группы или числовые интервалы — например, возраст в диапазоны «18–25», «26–35».

Кроме вкладки Поля в окне есть ещё три: иерархии, фильтры и параметры.

Иерархии

Иерархия — упорядоченный набор полей от общего уровня к детальному, например «Страна → Город → Адрес». Она задаёт порядок, в котором можно проваливаться вглубь данных.

Вкладка Иерархии → Добавить иерархию. Иерархии перечислены в сводке окна вместе с числом полей и параметров.

Фильтры датасета

Условия отбора строк, заданные один раз на весь датасет: они действуют во всех виджетах, построенных на нём, и накладываются до соединения таблиц.

Вкладка Фильтры → Добавить условие. Типичные примеры — только оплаченные заказы или только текущий год. Пока условий нет, виджеты видят датасет целиком.

Не путайте с фильтрами виджета: те действуют на одну визуализацию, эти — на весь датасет.

Параметры

Параметр — именованное значение, которое задаёт зритель при просмотре, а формула подставляет его по ссылке в квадратных скобках:

SUM([Выручка]) * (1 - [Скидка])

Здесь [Скидка] — параметр: меняя его, зритель пересчитывает показатель, не редактируя датасет. Вкладка Параметры → Добавить параметр.

Вычисляемое поле

Вычисляемое поле — новая колонка, значение которой считается выражением на основе других полей. Например, сумма заказа с НДС или доля от общего.

1. В окне Настройка полей нажмите Вычисляемое поле.
2. Заполните:
   • Идентификатор — латиницей, без пробелов; под этим именем поле живёт в датасете;
   • Псевдоним — как поле будет называться в списке;
   • Тип — как трактовать результат: число, дробное, строка, дата или логический;
   • SQL-выражение — сама формула.
3. Нажмите Создать, затем Применить и сохраните датасет.

Как писать выражение

Выражение пишется на SQL той базы, к которой подключён источник. Ссылка на поле берётся в квадратные скобки:

ROUND([amount] * 1.2, 2)

Слева в окне есть список всех доступных полей с поиском — по нему удобно сверять имена.

Это SQL, а не отдельный язык формул

Доступны функции и синтаксис вашей СУБД. Выражение, которое работает в ClickHouse, не обязательно заработает в PostgreSQL.

Справочник функций

Кнопка Справочник открывает список функций по категориям. Выберите функцию — справа появятся её синтаксис и описание. Например, для ROUND показано ROUND( number [, precision ] ) и пояснение «Округление до заданной точности».

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

Категория	Для чего
Агрегатные функции	Суммы, средние, количества
Уровень детализации (LOD)	Расчёты с гранулярностью, отличной от виджета
Оконные функции	Расчёты по окну строк — нарастающие итоги, ранги
Область окна	Управление границами окна
Функции времени	Работа с интервалами
Логические функции	Условия и ветвления
Математические функции	Округление, степени, модуль
Строковые функции	Обрезка, склейка, поиск подстроки
Функции даты и времени	Извлечение частей даты, сдвиги
Преобразование типов	Приведение значения к другому типу

Уровень детализации (LOD)

Обычная мера считается в разрезе тех измерений, что лежат на полках виджета. LOD меняет этот разрез, не трогая сам виджет:

Функция	Синтаксис	Что делает
FIXED	SUM([value] FIXED [dim], …)	Считает со строго заданной группировкой, независимо от измерений виджета
INCLUDE	SUM([value] INCLUDE [dim], …)	Добавляет измерения к разрезу виджета — считает детальнее
EXCLUDE	SUM([value] EXCLUDE [dim], …)	Убирает измерения из разреза — так считают долю от целого
BEFORE FILTER BY	SUM([value] BEFORE FILTER BY [dim], …)	Считает до применения фильтров по перечисленным полям

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

Оконные функции

Считают не по строке, а по окну соседних строк: нарастающие итоги, ранги, сравнение с предыдущим значением.

Группа	Функции
Ранги	RANK, RANK_DENSE, RANK_UNIQUE, RANK_PERCENTILE, ROW_NUMBER
Соседние значения	FIRST, LAST, LAG, LEAD
Нарастающие итоги	RSUM, RCOUNT, RAVG, RMIN, RMAX
Скользящие по окну строк	MSUM, MAVG, MCOUNT, MMIN, MMAX

Например, RSUM( number ) — нарастающая сумма, MAVG( number, rows ) — скользящее среднее по заданному числу строк, LAG( value [, offset ] ) — значение со смещением назад.

У RANK одинаковым значениям достаётся общий ранг, а следующий идёт с пропуском; RANK_DENSE пропусков не делает, RANK_UNIQUE всегда даёт разные ранги.

Область окна

Задаёт, что считать окном для оконной функции:

Функция	Синтаксис	Окно
TOTAL	SUM( SUM([value]) TOTAL )	Вся выборка целиком — так считают общий итог для доли
WITHIN	SUM( SUM([value]) WITHIN [dim], … )	Группы по перечисленным измерениям
AMONG	SUM( SUM([value]) AMONG [dim], … )	Измерения виджета, кроме перечисленных

Классическая доля от общего пишется так и проверена на демо-данных — сумма долей по четырём категориям дала ровно 100 %:

100.0 * SUM([orders.amount]) / SUM(SUM([orders.amount]) TOTAL)

Вычисляемые поля виджета

Если поле нужно только в одной визуализации, создайте его прямо в конструкторе виджета — блок Вычисляемые поля виджета внизу левой панели. Такое поле не попадает в датасет и не влияет на другие виджеты.

Платформа предложит два пути: SQL-выражение — писать формулу с нуля, или клонировать поле — взять за основу существующее и поправить.

В окне слева перечислены поля по таблицам, а под редактором — шаблоны, вставляющие готовый фрагмент: SUM(x), COUNTD(x), SUM_IF(x, cond), IF … THEN … ELSE … END, IFNULL(a, b), ROUND(x, 2), YEAR(x), CONCAT(a, b), а также заготовки посложнее — SUM(x FIXED [dim]), SUM(x EXCLUDE [dim]), SUM(SUM(x) TOTAL), RSUM(x), RANK(x).

Сохраните виджет, иначе поле не посчитается

Положив только что созданное поле на полку, вы увидите «Не удалось загрузить данные виджета — Определение вычисляемого поля не найдено». Это не ошибка формулы: определение ещё не сохранено на сервере. Нажмите Сохранить — виджет построится.