Техническое руководство по формулам Baserow

Это руководство объясняет внутреннее устройство формул Baserow для разработчиков.

См. руководство по пониманию формул Baserow, если вам нужна общая информация о том, как использовать формулы в Baserow в качестве пользователя.

Технический обзор

В Baserow существует специальный тип поля формулы. Пользователь вводит одну формулу для всего поля формулы, которая затем используется для вычисления каждой ячейки в этом поле.

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

• Определением синтаксиса/грамматики языка.
  • См. {git repo root}/formulas/*.g4.
• Лексеры и парсеры, сгенерированные с помощью ANTLR4 из грамматики.
  • См. {git repo root}/formulas/build.sh для скрипта, который генерирует их с использованием Docker.
  • Сгенерированный парсер, используемый для проверки правильности формулы в браузере, можно найти в web-frontend/modules/database/formula/parser.
  • Сгенерированный парсер, используемый для проверки правильности формулы и построения AST Python на стороне сервера, можно найти в backend/src/baserow/core/formulas/parser/generated.
• Абстрактное синтаксическое дерево Python, используемое внутренне на стороне сервера.
  • См. backend/src/baserow/core/formulas/ast/tree.py.
• Алгоритм типизации, способный определить тип данной формулы.
  • См. модуль типов формул, найденный в backend/src/baserow/core/formulas/types.
• Наконец, генератор, который преобразует типизированную формулу в выражение Django для безопасной оценки.
  • См. модуль генератора выражений, найденный в backend/src/baserow/core/formulas/expression_generator.

Функциональные возможности формул с технической точки зрения

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

Функции формул

Функции определяются путем реализации BaserowFunctionDefinition и хранения их в formula_function_registry (что позволяет плагинам легко добавлять свои собственные пользовательские функции).

Функции имеют определенное или неограниченное количество аргументов. Эти аргументы могут быть проверены на тип и принудительно приведены к определенным типам, иначе будет показана ошибка. Сама функция имеет тип возвращаемого значения.

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

Функции определяют, как они преобразуют себя в выражение Django для вычисления своего результата.

Расширение формул Baserow с помощью плагинов

Плагины могут легко добавлять новые функции и типы формул Baserow, реализуя BaserowFunctionDefinition и регистрируя его в formula_function_registry. Подсказка: используйте различные подклассы {Zero/One/Two/Three}ArgumentBaserowFunctionDefinition, чтобы получить более удобный набор функций для реализации, соответствующий аргументам.

Операторы формул

Операторы реализованы как отображение от оператора к BaserowFunctionDefinition. Таким образом, оператор + является просто удобным способом вызова функции BaserowAdd. Операторы имеют приоритет, определенный порядком правил в файле грамматики BaserowParser.g4.

Перегрузка операторов

Операторы могут иметь разные реализации в зависимости от типов входных данных. Например, 'a'+'b' объединяет две строки вместе, тогда как 1+2 выполняет числовое сложение.

Вычисление результата формулы

Формулы в конечном итоге компилируются до подготовленного SQL-запроса, который используется для вычисления и хранения результатов формулы в столбце PostgreSQL.

Для генерации SQL мы преобразуем формулу Baserow в выражение Django и затем полагаемся на Django для генерации SQL.

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

Формулы могут ссылаться на другие поля, включая другие поля формул. Они не могут ссылаться на себя и циклические ссылки запрещены.

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

Пользовательские настройки типа/форматирования

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

Например:

• Поле формулы 1+1 изначально вычисляется как имеющее тип BaserowFormulaNumberType(num_decimal_places=0).
• Этот вычисленный тип хранится в модели FormulaField, устанавливая поле formula_type на number, поле num_decimal_places на 0 и устанавливая все остальные поля типов на null.
• Затем все ячейки этого поля будут отображаться как 1.
• Однако пользователь может затем изменить эти сохраненные типовые опции самостоятельно, чтобы изменить тип и, следовательно, то, как отображается поле.
• Например, пользователь может изменить num_decimal_places на 2, что изменит соответствующее поле модели и также изменит тип этого поля на BaserowFormulaNumberType(num_decimal_places=2).
• Теперь ячейки будут отображаться как 1.00.

Эти пользовательские настройки типа/форматирования будут сброшены при изменении общего типа поля формулы; в противном случае они останутся неизменными.

Невалидный тип формулы

Существует невалидный тип, который хранит ошибку в модели FormulaField для формул с невалидным типом, таких как (1+'a') и т.д.

Приведение типов

В целом функции предпочитают приводить типы разумными способами, которые непрофессиональный пользователь мог бы ожидать. Например, CONCAT(field('a date field'), field('a boolean field')) должно работать без необходимости использования функции для преобразования каждого значения в текст. * Однако мы не позволяем пользователям делать странные вещи, такие как сравнение булевого значения с датой, вместо этого предоставляя ошибку типа вместо того, чтобы всегда возвращать false или что-то подобное.

Переименование полей

Переименование поля переименует все ссылки на это поле в формуле. Это достигается следующим процессом:

• Обновление всех формул, ссылающихся на это поле, для ссылки на новое имя
• Возврат этих обновленных полей в браузер.

При удалении поля мы:

• Отмечаем формулы, ссылающиеся на него, как сломанные с ошибкой.
• Это позволяет пользователю создать новое поле с именем 'name', что исправит эти сломанные формулы.

Это также может происходить при восстановлении или переименовании поля.

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

Сортировка и фильтрация полей формул

Поля формул можно сортировать и фильтровать с помощью существующих фильтров представлений Baserow на основе типа BaserowFormulaType поля. Просто используйте помощник функции FormulaFieldType.compatible_with_formula_types при определении ваших фильтров представлений compatible_field_types, чтобы указать, какие из типов формул совместимы с вашим фильтром представления.