UDFs vetorizadas de Python¶

Visão geral¶

As UDFs de Python vetorizadas permitem que você defina funções Python que recebem lotes de linhas de entrada como DataFrames do Pandas e retornam lotes de resultados como matrizes ou séries do Pandas. Você chama UDFs vetorizadas de Python da mesma forma que você chama outras UDFs de Python.

As vantagens de usar as UDFs vectorizadas Python em comparação com o padrão de processamento linha por linha incluem:

• O potencial de melhor desempenho se seu código de Python operar eficientemente em lotes de linhas.

• Menos lógica de transformação necessária se você estiver chamando bibliotecas que operam em DataFrames ou Arrays do Pandas.

Quando você utiliza UDFs vetorizadas de Python:

• Você não precisa mudar a forma de escrever consultas usando UDFs de Python. Todos os lotes são tratados pelo framework da UDF e não pelo seu próprio código.

• Como no caso de UDFs não vetorizadas, não há garantia de quais instâncias de seu código do manipulador verão quais lotes de entrada.

Introdução às UDFs vetorizadas de Python¶

Para criar uma UDF vetorizada de Python, use um dos mecanismos suportados para anotar sua função do manipulador.

create function add_one_to_inputs(x number(10, 0), y number(10, 0))
returns number(10, 0)
language python
runtime_version = 3.8
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.8
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
$$;

Como definir um tamanho alvo de lote¶

Chamadas para a função do manipulador do Python devem ser executadas dentro de um limite de tempo, que é de 180 segundos, e cada DataFrame passado como entrada para a função do manipulador pode conter atualmente até alguns milhares de linhas. Para de permanecer dentro do limite de tempo, você pode querer definir o tamanho alvo do lote para sua função do manipulador, que impõe um número máximo de linhas por DataFrame de entrada. Observe que a definição de um valor maior não garante que o Snowflake codifique lotes com o número especificado de linhas. Você pode definir o tamanho alvo do lote usando o decorador vectorized ou um atributo na função.

create function add_one_to_inputs(x number(10, 0), y number(10, 0))
returns number(10, 0)
language python
runtime_version = 3.8
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.8
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
$$;

Codificação do DataFrame¶

Lotes de argumentos para a UDF são codificados como arrays nos DataFramesde entrada do Pandas, e o número de linhas em cada DataFrame pode variar. Para obter mais informações, consulte Como definir um tamanho alvo de lote. Argumentos podem ser acessados no DataFrame pelo índice, ou seja, o primeiro argumento tem um índice de 0, o segundo tem um índice de 1, e assim por diante. O objeto Array ou Series do Pandas que o manipulador da UDF retorna deve ter o mesmo comprimento que o DataFrame de entrada.

Para ilustrar, suponha que você defina uma UDF vetorizada de Python da seguinte forma:

create or replace function add_inputs(x int, y float)
returns float
language python
runtime_version = 3.8
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]
$$;

Essa UDF usa df[0] para acessar a array do Pandas para o primeiro argumento, e df[1] para o segundo. O df[0] + df[1] resulta em uma array do Pandas com as somas em pares dos elementos correspondentes das duas arrays. Depois de criar a UDF, você pode chamá-la com algumas linhas de entrada:

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  |
+------------------+

Aqui a função add_inputs do Python recebe um DataFrame análogo a um criado com o seguinte código de Python:

>>> 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

A linha return df[0] + df[1] na função do manipulador resulta em uma array semelhante ao seguinte código de Python:

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