Синтаксис формул

Формула — это одно выражение, которое возвращает значение. Внизу — полная справка по синтаксису, какой поддерживается парсером.

Литералы

Числа: 42, 3.14, .5, -7. Дробная точка ., не запятая.
Строки: "текст" или 'текст' (одинарные/двойные кавычки). Экранирование: \", \', \n, \t.
Булевы: true, false. Внутри хранятся как 1 и 0.
Null: null — отсутствие значения.

Идентификаторы

Имя поля (ключ): amount, purchase_date, is_rented.
Имя функции: round, if, coalesce, today и т. д.
Ограничения: [a-zA-Z_][a-zA-Z0-9_]* — только латиница, цифры, подчёркивание; начинается с буквы или _.

Если идентификатора нет в датасете и нет среди встроенных функций — формула вычислит null (для полей) или выдаст ошибку «Unknown function» (для функций).

Операторы

Группа	Операторы	Замечания
Арифметика	`+`, `-`, `*`, `/`, `%`	`+` для строк = конкатенация. Деление на 0 → `null`.
Сравнение	`==`, `!=`, `<`, `>`, `<=`, `>=`	Равенство нестрогое: `"1" == 1` → `true`. Сравнение `< > <= >=` — только для чисел.
Логика	`&&`, `\|\|`, `!` (или `not(...)`)	`&&` / `\|\|` короткозамкнутые. Truthy: ненулевое число, непустая строка, `true`.
Унарные	`-x`, `+x`, `!x`

Приоритет (от низкого к высокому)

\|\|
&&
==, !=
<, >, <=, >=
+, -
*, /, %
Унарные -, +, !
Скобки, вызовы функций, идентификаторы

Примеры:

a + b * c — это a + (b * c).
a < b && c > d — это (a < b) && (c > d).
!a == b — это (!a) == b. Если хотите «не (a == b)», пишите !(a == b).

Вызов функции

round(amount * 1.2, 2)

Аргументы через запятую.
Регистр имени неважен: Round(...) и round(...) — одно и то же.
Лишних/недостающих аргументов парсер не ловит на этапе разбора — ошибка появится при вычислении.

Условие — функция `if`, а НЕ тернарный оператор

Тернарного оператора ? : нет. Условные ветвления пишутся через функцию if:

if(amount > 100000, "Большая сумма", "Малая сумма")

if(is_rented, monthly_rent, 0)

Подробности — в скалярных функциях.

Ссылки на поля

Поле = идентификатор по своему ключу:

purchase_price * area_m2

Если поле не задано (пусто) — оно вычисляется как null, и арифметика возвращает null.

Совет. В редакторе формулы под textarea есть рейл «Доступные поля» — клик по русскому названию вставляет английский ключ в курсорную позицию. Удобно при первом знакомстве с датасетом.

Поведение `null`

Арифметика с null → null. 5 + null = null.
Сравнение < > <= >= с null → null.
== и !=: null == null → true, null == 0 → false.
coalesce(a, b, ...) — первый ненулевой аргумент.

Связи в формулах

Поле-связь хранит id целевой строки. Получить её поля через связь.поле нельзя. Подробнее — в «Связи в формулах».

Агрегаты и кросс-строчные

Агрегаты (sum, avg, count) считают по всему датасету и не зависят от текущей строки.
Кросс-строчные (lag, lead, running_sum, window_avg, rank) считают относительно текущей строки в порядке отображения таблицы. Подразумевается, что таблица отсортирована — иначе результат осмысленный, но непредсказуемый.

⚠️ Уточнить: агрегатные и кросс-строчные функции в формулах-полях работают, когда система предоставляет контекст датасета и индекса строки. На момент написания документации точное место, где такой контекст уже подаётся (везде, только в виджетах, только в drill-down?), не подтверждено в коде. Если вы добавили sum(amount) в формулу-поле и видите ошибку «Aggregate can’t be used in per-row formula» — это значит, что вычисление идёт без датасета; считайте такое значение на дашборде через KPI или замените sum(...) на обычную арифметику.

Ошибки парсера

«Unexpected character “X”» — символ, который парсер не знает (например, &, не идущий парой с другим &).
«Unterminated string» — забыли закрыть кавычку.
«Unknown function foo()» — функция не зарегистрирована.
«Aggregate sum() can’t be used in a per-row formula» — попытка использовать sum там, где нет датасета.

Частые ошибки

? :. Не работает. Заменяйте на if.
Запятая вместо точки в числе. 3,14 парсится как 3,14 (две сущности) — будет ошибка.
Кириллица в имени поля. Ключи только латиницей. Русское название — только в шапке колонки.
Точечная нотация для связи. object.price — ошибка. См. «Связи в формулах».