Python UDF

Experimental feature

Рекомендации по использованию экспериментальных функций

В этом разделе описывается, как разрабатывать пользовательские функции (UDF) с использованием Python.

Начиная с версии 3.4.0, Selena поддерживает создание Python UDF.

В настоящее время Selena поддерживает только скалярные UDF на Python.

Предварительные требования

Перед началом работы убедитесь, что выполнены следующие требования:

• Установлен Python 3.8 или более поздняя версия.
• UDF включены в Selena путём установки параметра enable_udf в значение true в файле конфигурации FE fe/conf/fe.conf, после чего необходимо перезапустить узлы FE для применения конфигурации. Подробнее см. Конфигурация FE - enable_udf.
• Для Python UDF требуется пакет pyarrow.
• Установите местоположение среды интерпретатора Python в экземпляре BE с помощью переменной окружения. Добавьте переменную python_envs и установите её значение в путь установки интерпретатора Python, например, /opt/Python-3.8/.

Разработка и использование Python UDF

Синтаксис:

CREATE [GLOBAL] FUNCTION function_name(arg_type [, ...])
RETURNS return_type
{PROPERTIES ("key" = "value" [, ...]) | key="value" [...] }
[AS $$ $$]

Параметр	Обязательный	Описание
GLOBAL	Нет	Создать ли глобальную UDF.
function_name	Да	Имя создаваемой функции. Вы можете включить имя базы данных в этот параметр, например, db1.my_func. Если function_name содержит имя базы данных, UDF создаётся в этой базе данных. В противном случае UDF создаётся в текущей базе данных. Имя новой функции и её параметры не должны совпадать с существующим именем в целевой базе данных. В противном случае функция не может быть создана. Создание выполняется успешно, если имя функции совпадает, но параметры отличаются.
arg_type	Да	Тип аргумента функции. Добавленный аргумент может быть представлен как , .... Поддерживаемые типы данных см. в Соответствие между типами данных SQL и Python.
return_type	Да	Тип возвращаемого значения функции. Поддерживаемые типы данных см. в Соответствие между типами данных SQL и Python.
PROPERTIES	Да	Свойства функции, которые зависят от типа создаваемой UDF.
AS $$ $$	Нет	Укажите встроенный код UDF между метками $$.

Свойства включают:

Свойство	Обязательное	Описание
type	Да	Тип UDF. Значение Python указывает на создание UDF на основе Python.
symbol	Да	Имя класса для проекта Python, к которому принадлежит UDF. Значение этого параметра имеет формат <package_name>.<class_name>.
input	Нет	Тип входных данных. Допустимые значения: scalar (по умолчанию) и arrow (векторизованный ввод).
file	Нет	HTTP-URL, по которому можно загрузить файл пакета Python, содержащий код для UDF. Значение этого параметра имеет формат http://<http_server_ip>:<http_server_port>/<python_package_name>. Обратите внимание, что имя пакета должно иметь суффикс .py.zip. Значение по умолчанию: inline, что означает создание встроенной UDF.

Создание встроенной скалярной UDF с использованием Python

Следующий пример создаёт встроенную функцию echo со скалярным вводом с использованием Python.

CREATE FUNCTION python_echo(INT)
RETURNS INT
type = 'Python'
symbol = 'echo'
file = 'inline'
AS
$$
def echo(x):
    return x
$$
;

Создание встроенной векторизованной UDF с использованием Python

Поддерживается векторизованный ввод для повышения производительности обработки UDF.

Следующий пример создаёт встроенную функцию add с векторизованным вводом с использованием Python.

CREATE FUNCTION python_add(INT)
RETURNS INT
type = 'Python'
symbol = 'add'
input = "arrow"
AS
$$
import pyarrow.compute as pc
def add(x):
    return pc.add(x, 1)
$$
;

Создание пакетной UDF с использованием Python

При создании пакета Python вы должны упаковать модуль в файлы .py.zip, которые должны соответствовать формату zipimport.

> tree .
.
├── main.py
└── yaml
    ├── composer.py
    ├── constructor.py
    ├── cyaml.py
    ├── dumper.py
    ├── emitter.py
    ├── error.py
    ├── events.py
    ├── __init__.py
    ├── loader.py
    ├── nodes.py
    ├── parser.py

> cat main.py
import numpy
import yaml

def echo(a):
    return yaml.__version__

CREATE FUNCTION py_pack(string)
RETURNS  string
symbol = "add"
type = "Python"
file = "http://HTTP_IP:HTTP_PORT/m1.py.zip"
symbol = "main.echo"
;

Приложение

Соответствие между типами данных SQL и Python

Тип SQL	Тип Python 3
SCALAR
TINYINT/SMALLINT/INT/BIGINT/LARGEINT	INT
STRING	string
DOUBLE	FLOAT
BOOLEAN	BOOL
DATETIME	DATETIME.DATETIME
FLOAT	FLOAT
CHAR	STRING
VARCHAR	STRING
DATE	DATETIME.DATE
DECIMAL	DECIMAL.DECIMAL
ARRAY	List
MAP	Dict
STRUCT	COLLECTIONS.NAMEDTUPLE
JSON	dict
VECTORIZED
TYPE_BOOLEAN	pyarrow.lib.BoolArray
TYPE_TINYINT	pyarrow.lib.Int8Array
TYPE_SMALLINT	pyarrow.lib.Int15Array
TYPE_INT	pyarrow.lib.Int32Array
TYPE_BIGINT	pyarrow.lib.Int64Array
TYPE_FLOAT	pyarrow.FloatArray
TYPE_DOUBLE	pyarrow.DoubleArray
VARCHAR	pyarrow.StringArray
DECIMAL	pyarrow.Decimal128Array
DATE	pyarrow.Date32Array
TYPE_TIME	pyarrow.TimeArray
ARRAY	pyarrow.ListArray

Компиляция Python

Выполните следующие шаги для компиляции Python:

1. Получите пакет OpenSSL.

   wget 'https://github.com/openssl/openssl/archive/OpenSSL_1_1_1m.tar.gz'

2. Распакуйте пакет.

   tar -zxf OpenSSL_1_1_1m.tar.gz

3. Перейдите в распакованную папку.

   cd openssl-OpenSSL_1_1_1m

4. Установите переменную окружения OPENSSL_DIR.

   export OPENSSL_DIR=`pwd`/install

5. Подготовьте исходный код для компиляции.

   ./Configure --prefix=`pwd`/install
   ./config --prefix=`pwd`/install

6. Скомпилируйте OpenSSL.

   make -j 16 && make install

7. Установите переменную окружения LD_LIBRARY_PATH.

   LD_LIBRARY_PATH=$OPENSSL_DIR/lib:$LD_LIBRARY_PATH

8. Вернитесь в рабочий каталог и получите пакет Python.

   wget 'https://www.python.org/ftp/python/3.12.9/Python-3.12.9.tgz'

9. Распакуйте пакет.

   tar -zxf ./Python-3.12.9.tgz

10. Перейдите в распакованную папку.

cd Python-3.12.9

11. Создайте и перейдите в каталог build.

mkdir build && cd build

12. Подготовьте исходный код для компиляции.

../configure --prefix=`pwd`/install --with-openssl=$OPENSSL_DIR

13. Скомпилируйте Python.

make -j 16 && make install

14. Установите PyArrow и grpcio.

./install/bin/pip3 install pyarrow grpcio

15. Сожмите файлы в пакет.

tar -zcf ./Python-3.12.9.tar.gz install

16. Распространите пакет на целевой сервер BE и распакуйте пакет.

tar -zxf ./Python-3.12.9.tar.gz

17. Измените файл конфигурации BE be.conf, добавив следующий элемент конфигурации.

python_envs=/home/disk1/sr/install