Создание пользовательских функций

Пользовательские функции позволяют расширить MariaDB новой функцией, работающей как встроенная функция MariaDB, например, ABS() или CONCAT(). Существуют альтернативные способы добавления новой функции: написание встроенной функции (что требует изменения и компиляции исходного кода сервера) или написание хранимой функции.

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

Функции пишутся на C или C++, и для их использования операционная система должна поддерживать динамическую загрузку.

Каждая новая SQL-функция требует соответствующих функций, написанных на C/C++. В списке ниже требуется как минимум основная функция - x() - и еще одна. x следует заменить именем создаваемой функции.

Все функции должны быть потокобезопасными, поэтому нельзя использовать глобальные или статические переменные, которые изменяются. Память выделяется в x_init()/ и освобождается в x_deinit().

Краткое описание функций

x()

Требуется для всех пользовательских функций; здесь рассчитываются результаты.

Функции DECIMAL возвращают строковые значения и должны быть написаны соответствующим образом. Невозможно создать функции ROW.

x_init()

Функция инициализации для x(). Может использоваться для:

• Проверки количества аргументов для X() (SQL эквивалент).
• Проверки типов аргументов или принудительного изменения типа аргументов после вызова функции.
• Указание, может ли результат быть NULL.
• Указание максимальной длины результата.
• Для функций REAL укажите максимальное количество десятичных знаков для результата.
• Выделение любой необходимой памяти.

x_deinit()

Функция завершения для x(). Используется для освобождения памяти, выделенной в x_init().

Описание

Каждый раз при вызове SQL-функции X():

• MariaDB сначала вызовет функцию C/C++ инициализации x_init(), если она существует. Все настройки будут выполнены, и если она вернёт ошибку, SQL-запрос прервётся, и другие функции не будут вызваны.
• Если функции x_init() нет или она была вызвана и не вернула ошибку, x() вызывается один раз на строку.
• После завершения обработки всех строк вызывается x_deinit(), если она существует, для очистки, освобождая память, выделенную в x_init().
• Дополнительные сведения о функциях см. в разделе Последовательности вызова пользовательских функций.

Функции агрегирования

Следующие функции необходимы для агрегатных функций, таких как AVG() и SUM(). При использовании CREATE FUNCTION требуется ключевое слово AGGREGATE.

x_clear()

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

x_add()

Используется для добавления аргумента к текущему агрегату.

x_remove()

Начиная с MariaDB 10.4, улучшена поддержка оконных функций (поэтому добавление необязательно) и должна удалять аргумент из текущего агрегата.

Описание

Каждый раз при вызове агрегатной SQL-функции X():

• MariaDB сначала вызовет функцию C/C++ инициализации x_init(), если она существует. Все настройки будут выполнены, и если она вернёт ошибку, SQL-запрос прервётся, и другие функции не будут вызваны.
• Таблица сортируется в соответствии с выражением GROUP BY.
• x_clear() вызывается для первой строки каждой новой группы.
• x_add() вызывается один раз на строку для каждой строки в той же группе.
• x() вызывается при изменении группы или после последней строки, чтобы получить результат агрегирования.
• Эти три шага повторяются до тех пор, пока все строки не будут обработаны.
• После завершения обработки всех строк вызывается x_deinit(), если она существует, для очистки, освобождая память, выделенную в x_init().

• MariaDB сначала вызовет функцию C/C++ инициализации x_init(), если она существует. Все настройки будут выполнены, и если она вернёт ошибку, SQL-запрос прервётся, и другие функции не будут вызваны.
• x_clear() вызывается для первой строки каждой новой группы.
• x_add() вызывается один раз на строку для каждой строки в той же группе.
• x() вызывается при изменении группы или после последней строки, чтобы получить результат агрегирования.
• Эти три шага повторяются до тех пор, пока все строки не будут обработаны.
• После завершения обработки всех строк вызывается x_deinit(), если она существует, для очистки, освобождая память, выделенную в x_init().

Примеры

Пример см. в sql/udf_example.cc в дереве исходного кода. Коллекция существующих пользовательских функций см. в https://github.com/mysqludf.

См. также

• Хранимые функции
• Хранимые агрегированные функции
• Последовательности вызова пользовательских функций