ベクトル化されたPython UDFs¶

概要¶

ベクトル化されたPython UDFs を使用すると、入力行のバッチを Pandas DataFrames として受け取り、結果のバッチを Pandas配列 または Series として返すPython関数を定義します。他のPython UDFs を呼び出すのと同じ方法で、ベクトル化されたPython UDFs を呼び出します。

デフォルトの行ごとの処理パターンと比較して、ベクトル化された UDFs を使用する利点は次のとおりです。

• Pythonコードが行のバッチで効率的に動作する場合、パフォーマンスが向上する可能性があります。

• Pandas DataFramesまたはPandas配列で動作するライブラリを呼び出す場合は、必要な変換ロジックが少なくなります。

ベクトル化されたPython UDFs を使用する場合、

• Python UDFsを使用してクエリを作成する方法を変更する必要はありません。すべてのバッチ処理は、独自のコードではなく、UDFフレームワークによって処理されます。

• ベクトル化されていない UDFs と同様に、ハンドラーコードのどのインスタンスが入力のどのバッチを参照するかは保証されません。

ベクトル化されたPython UDFs 入門¶

ベクトル化されたPython UDF を作成するには、ハンドラー関数への注釈付与でサポートされているメカニズムの1つを使用します。

CREATE FUNCTION add_one_to_inputs(x NUMBER(10, 0), y NUMBER(10, 0))
  RETURNS NUMBER(10, 0)
  LANGUAGE PYTHON
  RUNTIME_VERSION = 3.9
  PACKAGES = ('pandas')
  HANDLER = 'add_one_to_inputs'
AS $$
import pandas
from _snowflake import vectorized

@vectorized(input=pandas.DataFrame)
def add_one_to_inputs(df):
 return df[0] + df[1] + 1
$$;

CREATE FUNCTION add_one_to_inputs(x NUMBER(10, 0), y NUMBER(10, 0))
  RETURNS NUMBER(10, 0)
  LANGUAGE PYTHON
  RUNTIME_VERSION = 3.9
  PACKAGES = ('pandas')
  HANDLER = 'add_one_to_inputs'
AS $$
import pandas

def add_one_to_inputs(df):
 return df[0] + df[1] + 1

add_one_to_inputs._sf_vectorized_input = pandas.DataFrame
$$;

ターゲットバッチサイズの設定¶

Pythonハンドラー関数の呼び出しは、制限時間である180秒以内に実行する必要があり、ハンドラー関数への入力として渡される各 DataFrame には、現在最大数千行が含まれる場合があります。制限時間内にとどまるために、ハンドラー関数のターゲットバッチサイズを設定することをお勧めします。これにより、入力DataFrameごとの最大行数が制限されます。より大きな値を設定しても、Snowflakeが指定された行数のバッチをエンコードすることを保証するものではないことに注意してください。 vectorized デコレーターまたは関数の属性を使用して、ターゲットバッチサイズを設定できます。

CREATE FUNCTION add_one_to_inputs(x NUMBER(10, 0), y NUMBER(10, 0))
  RETURNS NUMBER(10, 0)
  LANGUAGE PYTHON
  RUNTIME_VERSION = 3.9
  PACKAGES = ('pandas')
  HANDLER = 'add_one_to_inputs'
AS $$
import pandas
from _snowflake import vectorized

@vectorized(input=pandas.DataFrame, max_batch_size=100)
def add_one_to_inputs(df):
 return df[0] + df[1] + 1
$$;

CREATE FUNCTION add_one_to_inputs(x NUMBER(10, 0), y NUMBER(10, 0))
  RETURNS NUMBER(10, 0)
  LANGUAGE PYTHON
  RUNTIME_VERSION = 3.9
  PACKAGES = ('pandas')
  HANDLER = 'add_one_to_inputs'
AS $$
import pandas

def add_one_to_inputs(df):
 return df[0] + df[1] + 1

add_one_to_inputs._sf_vectorized_input = pandas.DataFrame
add_one_to_inputs._sf_max_batch_size = 100
$$;

DataFrame エンコーディング¶

UDFへの引数のバッチは、入力パンダPandas DataFramesの配列としてエンコードされ、各DataFrameの行数は異なる場合があります。詳細については、 ターゲットバッチサイズの設定 をご参照ください。引数は、インデックスによってDataFrameでアクセスできます。つまり、最初の引数のインデックスは0、2番目の引数のインデックスは1というようになります。UDFハンドラーが返すPandas配列またはシリーズは、入力DataFrameと同じ長さである必要があります。

説明のために、ベクトル化されたPython UDF を次のように定義するとします。

CREATE OR REPLACE FUNCTION add_inputs(x INT, y FLOAT)
  RETURNS FLOAT
  LANGUAGE PYTHON
  RUNTIME_VERSION = 3.9
  PACKAGES = ('pandas')
  HANDLER = 'add_inputs'
AS $$
import pandas
from _snowflake import vectorized

@vectorized(input=pandas.DataFrame)
def add_inputs(df):
  return df[0] + df[1]
$$;

このUDFは、 df[0] を使用して最初の引数のPandas配列にアクセスし、 df[1] を使用して2番目の引数にアクセスします。 df[0] + df[1] は、2つの配列からの対応する要素のペアワイズ合計を持つPandas配列になります。UDFを作成した後、いくつかの入力行を使用して呼び出すことができます。

SELECT add_inputs(x, y)
FROM (
  SELECT 1 AS x, 3.14::FLOAT as y UNION ALL
  SELECT 2, 1.59 UNION ALL
  SELECT 3, -0.5
);

+------------------+
| ADD_INPUTS(X, Y) |
|------------------|
|             4.14 |
|             3.59 |
|             2.5  |
+------------------+

ここで、 add_inputs Python関数は、次のPythonコードで作成されたものに類似したDataFrameを受け取ります。

>>> import pandas
>>> df = pandas.DataFrame({0: pandas.array([1, 2, 3]), 1: pandas.array([3.14, 1.59, -0.5])})
>>> df
   0     1
0  1  3.14
1  2  1.59
2  3 -0.50

ハンドラー関数の行 return df[0] + df[1] は、次のPythonコードのような配列になります。

>>> df[0] + df[1]
0    4.14
1    3.59
2    2.50
dtype: float64