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

Python UDF

Experimental feature

実験的機能の使用に関するアドバイス

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

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

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

前提条件​

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

  • Python 3.8 以降をインストールします。
  • StarRocks で UDF を有効にするには、FE 設定ファイル fe/conf/fe.conf で enable_udf を true に設定し、FE ノードを再起動して設定を有効にします。詳細については、FE configuration - enable_udf を参照してください。
  • Python UDFには以下のパッケージが必要です： pyarrow
  • 環境変数を使用して 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_func。function_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