Python user-defined functions#

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

Объявление Python UDF#

Объявите Python UDF как inline или catalog UDF, выполнив следующие шаги:

Используйте ключевое слово FUNCTION для объявления имени функции и параметров.
Добавьте объявление RETURNS, чтобы указать тип возвращаемого значения.
Установите LANGUAGE в PYTHON.
Укажите имя вызываемой Python-функции через свойство handler в блоке WITH.
Используйте $$, чтобы заключить Python-код после ключевого слова AS.
Добавьте функцию, указанную в handler, и убедитесь, что она возвращает объявленный тип данных.
Расширьте блок Python-кода, реализовав функцию с использованием доступных возможностей языка Python.

Следующий фрагмент показывает псевдокод:

FUNCTION python_udf_name(input_parameter data_type)
  RETURNS result_data_type
  LANGUAGE PYTHON
  WITH (handler = 'python_function')
  AS $$
  ...
  def python_function(input):
      return ...
  ...
  $$

Минимальный пример объявляет UDF doubleup, которая возвращает входное целое значение x, умноженное на два. Пример демонстрирует объявление как Inline пользовательские функции и вызов с значением 21, что даёт результат 42.

Установите язык PYTHON, чтобы переопределить значение по умолчанию SQL для SQL пользовательские функции. Python-код заключается в $$ и должен иметь корректное форматирование.

WITH
  FUNCTION doubleup(x integer)
    RETURNS integer
    LANGUAGE PYTHON
    WITH (handler = 'twice')
    AS $$
    def twice(a):
        return a * 2
    $$
SELECT doubleup(21);
-- 42

Та же UDF может быть объявлена как Catalog user-defined functions.

Обратитесь к Example Python UDFs для более сложных примеров и сценариев использования.

Особенности языка Python#

Интеграция Python UDF в Trino использует Python 3.13.0 в изолированной среде (sandbox). Код Python выполняется внутри среды выполнения WebAssembly (WASM) в виртуальной машине Java, в которой работает Trino.

Необходимо соблюдать правила языка Python, включая отступы.

Python UDF имеют доступ только к языку Python и базовым библиотекам, включённым в изолированную среду выполнения. Доступ к внешним ресурсам (сеть, файловая система) не поддерживается. Использование сторонних библиотек Python, инструментов командной строки и менеджеров пакетов также не поддерживается.

Следующие библиотеки явно удалены из среды выполнения и недоступны в Python UDF:

bdb
concurrent
curses
ensurepip
doctest
idlelib
multiprocessing
pdb
pydoc
socketserver
sqlite3
ssl
subprocess
tkinter
turtle
unittest
venv
webbrowser
wsgiref
xmlrpc

Следующие библиотеки явно добавлены в среду выполнения и доступны в Python UDF:

attrs
bleach
charset-normalizer
defusedxml
idna
jmespath
jsonschema
pyasn1
pyparsing
python-dateutil
rsa
tomli
ua-parser

Type mapping (Сопоставление типов)#

В следующей таблице показаны поддерживаемые типы Trino и соответствующие им типы Python для входных и выходных значений Python UDF:

Trino type	Python type
`ROW`	`tuple`
`ARRAY`	`list`
`MAP`	`dict`
`BOOLEAN`	`bool`
`TINYINT`	`int`
`SMALLINT`	`int`
`INTEGER`	`int`
`BIGINT`	`int`
`REAL`	`float`
`DOUBLE`	`float`
`DECIMAL`	`decimal.Decimal`
`VARCHAR`	`str`
`VARBINARY`	`bytes`
`DATE`	`datetime.date`
`TIME`	`datetime.time`
`TIME WITH TIME ZONE`	`datetime.time` with `datetime.tzinfo`
`TIMESTAMP`	`datetime.datetime`
`TIMESTAMP WITH TIME ZONE`	`datetime.datetime` with `datetime.tzinfo`
`INTERVAL YEAR TO MONTH`	`int` as the number of months
`INTERVAL DAY TO SECOND`	`datetime.timedelta`
`JSON`	`str`
`UUID`	`uuid.UUID`
`IPADDRESS`	`ipaddress.IPv4Address` or `ipaddress.IPv6Address`

Время и временные метки#

Объекты Python datetime и time поддерживают точность только до микросекунд. Значения Trino с большей точностью округляются при преобразовании в Python, а возвращаемые из Python значения округляются, если тип Trino имеет меньшую точность.

Временные метки с часовым поясом#

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