Пользовательская формула (FORMULA)

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

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

Класс результата

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

Обращение к параметрам

Пользовательская формула обращается к своим параметрам внутри SQL-текста; аргументы свойства подставляются в тех местах, где формула на них ссылается. Доступны и позиционные, и именованные обращения — точная нотация и правила определения арности результирующего свойства относятся к статье оператора FORMULA.

Табличные формулы

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

• напрямую отобразить свойство lsFusion на внешнюю таблицу в базе данных;
• использовать табличные SQL-функции как свойства lsFusion;
• «разворачивать» строки, JSON-документы или массивы в свойства, индексированные по ключу.

Правила соотнесения параметров свойства с этой таблицей описаны в статье оператора FORMULA.

Обработка NULL

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

Это поведение по умолчанию ослабляется одним из двух способов, причём более сильный поглощает более слабый. Меньшее ослабление объявляет, что формула может возвращать NULL даже при всех не-NULL аргументах. Большее ослабление идёт дальше и пропускает NULL-аргументы внутрь самой формулы — это нужно, например, для SQL-функций вроде COALESCE, чья задача как раз — работать с NULL — и как только она их получает, она целиком распоряжается тем, что вернуть на любой вход, так что меньшее ослабление поверх этого ничего не добавляет.

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

Язык

Для объявления свойства с помощью пользовательской формулы используется оператор FORMULA.

Примеры

// свойство с двумя параметрами: округляемым числом и количеством знаков после запятой
round(number, digits) = FORMULA 'round(CAST(($1) as numeric),$2)';

// свойство, преобразовывающее значение, переданное в качестве аргумента, к строковому типу длиной в 15 символов.
toString15(str) = FORMULA BPSTRING[15] 'CAST($1 AS character(15))';

// свойство с двумя различными реализациями для разных диалектов SQL
jumpWorkdays = FORMULA NULL DATE PG 'jumpWorkdays($1, $2, $3)', MS 'dbo.jumpWorkdays($1, $2, $3)';

// табличная формула — параметр INTEGER row не используется в тексте и становится
// ключевой колонкой таблицы, возвращаемой jsonb_array_elements
array (JSON json, INTEGER row) = FORMULA JSON value 'jsonb_array_elements($json)';