メインコンテンツまでスキップ
バージョン: Candidate-3.5

Python UDF

このトピックでは、Python を使用してユーザー定義関数 (UDF) を開発する方法について説明します。

v3.4.0 以降、StarRocks は Python UDF の作成をサポートしています。

現在、StarRocks は Python でのスカラー UDF のみをサポートしています。

前提条件

次の要件を満たしていることを確認してください。

  • Python 3.8 以降をインストールします。
  • StarRocks で UDF を有効にするには、FE 設定ファイル fe/conf/fe.confenable_udftrue に設定し、FE ノードを再起動して設定を有効にします。詳細については、FE configuration - enable_udf を参照してください。
  • 環境変数を使用して BE インスタンスで Python インタープリタ環境の場所を設定します。変数項目 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 $$ $$]
パラメータ必須説明
GLOBALNoグローバル UDF を作成するかどうか。
function_nameYes作成したい関数の名前。このパラメータにはデータベース名を含めることができます。例: db1.my_funcfunction_name にデータベース名が含まれている場合、UDF はそのデータベースに作成されます。それ以外の場合、UDF は現在のデータベースに作成されます。新しい関数の名前とそのパラメータは、宛先データベースに既存の名前と同じにすることはできません。それ以外の場合、関数は作成できません。関数名が同じでもパラメータが異なる場合、作成は成功します。
arg_typeYes関数の引数の型。追加された引数は , ... で表すことができます。サポートされているデータ型については、SQL データ型と Python データ型のマッピング を参照してください。
return_typeYes関数の戻り値の型。サポートされているデータ型については、SQL データ型と Python データ型のマッピング を参照してください。
PROPERTIESYes作成する UDF の種類に応じて異なる関数のプロパティ。
AS $$ $$No$$ マークの間にインライン UDF コードを指定します。

プロパティには次のものが含まれます。

プロパティ必須説明
typeYesUDF の種類。Python に設定すると、Python ベースの UDF を作成することを示します。
symbolYesUDF が属する Python プロジェクトのクラス名。このパラメータの値は <package_name>.<class_name> 形式です。
inputNo入力の種類。有効な値: scalar (デフォルト) および arrow (ベクトル化された入力)。
fileNoUDF のコードを含む Python パッケージファイルをダウンロードできる HTTP URL。このパラメータの値は http://<http_server_ip>:<http_server_port>/<python_package_name> 形式です。パッケージ名には .py.zip サフィックスが必要です。デフォルト値: inline、インライン UDF を作成することを示します。

Python を使用してインラインスカラー入力 UDF を作成する

次の例では、Python を使用してスカラー入力を持つインライン echo 関数を作成します。

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

Python を使用してインラインベクトル化入力 UDF を作成する

ベクトル化入力は、UDF 処理のパフォーマンスを向上させるためにサポートされています。

次の例では、Python を使用してベクトル化入力を持つインライン add 関数を作成します。

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)
$$
;

Python を使用してパッケージ化された UDF を作成する

Python パッケージを作成する際には、モジュールを .py.zip ファイルにパッケージ化する必要があります。これらは zipimport format を満たす必要があります。

> 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/LARGEINTINT
STRINGstring
DOUBLEFLOAT
BOOLEANBOOL
DATETIMEDATETIME.DATETIME
FLOATFLOAT
CHARSTRING
VARCHARSTRING
DATEDATETIME.DATE
DECIMALDECIMAL.DECIMAL
ARRAYList
MAPDict
STRUCTCOLLECTIONS.NAMEDTUPLE
JSONdict
VECTORIZED
TYPE_BOOLEANpyarrow.lib.BoolArray
TYPE_TINYINTpyarrow.lib.Int8Array
TYPE_SMALLINTpyarrow.lib.Int15Array
TYPE_INTpyarrow.lib.Int32Array
TYPE_BIGINTpyarrow.lib.Int64Array
TYPE_FLOATpyarrow.FloatArray
TYPE_DOUBLEpyarrow.DoubleArray
VARCHARpyarrow.StringArray
DECIMALpyarrow.Decimal128Array
DATEpyarrow.Date32Array
TYPE_TIMEpyarrow.TimeArray
ARRAYpyarrow.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
  1. ディレクトリ build を作成し、そこに移動します。
mkdir build && cd build
  1. コンパイルのためのソースコードを準備します。
../configure --prefix=`pwd`/install --with-openssl=$OPENSSL_DIR
  1. Python をコンパイルします。
make -j 16 && make install
  1. PyArrow と grpcio をインストールします。
./install/bin/pip3 install pyarrow grpcio
  1. ファイルをパッケージに圧縮します。
tar -zcf ./Python-3.12.9.tar.gz install
  1. パッケージをターゲット BE サーバーに配布し、パッケージを解凍します。
tar -zxf ./Python-3.12.9.tar.gz
  1. BE 構成ファイル be.conf を修正し、次の構成項目を追加します。
python_envs=/home/disk1/sr/install