UDFs Python vectorisées¶

Vue d’ensemble¶

Les UDFs Python vectorisées vous permettent de définir des fonctions Python qui reçoivent des lots de lignes d’entrée sous forme de DataFrames Pandas et renvoient des lots de résultats sous forme de tableaux ou de séries Pandas. Vous appelez des UDFs Python vectorisées de la même manière que vous appelez les autres UDFs Python.

Les avantages de l’utilisation des UDFs Python vectorisées par rapport au modèle de traitement ligne par ligne par défaut sont les suivants :

• Le potentiel de meilleures performances si votre code Python fonctionne efficacement sur des lots de lignes.

• Moins de logique de transformation requise si vous faites appel à des bibliothèques qui fonctionnent sur des DataFrames Pandas ou des tableaux Pandas.

Lorsque vous utilisez des UDFs Python vectorisées :

• Vous n’avez pas besoin de modifier la façon dont vous écrivez les requêtes en utilisant des UDFs Python. Tous les lots sont gérés par le framework UDF plutôt que par votre propre code.

• Comme pour les UDFs qui ne sont pas vectorisées, il n’y a aucune garantie quant aux instances de votre code de gestionnaire qui verront les lots d’entrée.

Premiers pas avec les UDFs Python vectorisées¶

Pour créer une UDF Python vectorisée, utilisez l’un des mécanismes pris en charge pour annoter votre fonction de gestionnaire.

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

Définition d’une taille de lot cible¶

Les appels à la fonction de gestionnaire Python doivent s’exécuter dans un délai limité, qui est de 180 secondes, et chaque DataFrame transmis en entrée à la fonction de gestionnaire peut actuellement contenir jusqu’à quelques milliers de lignes. Afin de respecter la limite de temps, vous pouvez définir la taille de lot cible pour votre fonction de gestionnaire, qui impose un nombre maximal de lignes par DataFrame d’entrée. Notez que la définition d’une valeur plus grande ne garantit pas que Snowflake codera les lots avec le nombre de lignes spécifié. Vous pouvez définir la taille du lot cible en utilisant soit le décorateur vectorized soit un attribut de la fonction.

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

Encodage DataFrame¶

Les lots d’arguments de l’UDF sont codés sous forme de tableaux dans les DataFrames Pandas d’entrée, et le nombre de lignes dans chaque DataFrame peut varier. Pour plus d’informations, voir Définir une taille de lot cible. Les arguments sont accessibles dans le DataFrame par leur index, c’est-à-dire que le premier argument a un index de 0, le second a un index de 1, et ainsi de suite. Le tableau ou la série Pandas que le gestionnaire UDF renvoie doit avoir la même longueur que le DataFrame d’entrée.

Pour illustrer ce propos, supposons que vous définissiez une UDF Python vectorisée comme suit :

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

Cette UDF utilise df[0] pour accéder au tableau Pandas pour le premier argument et df[1] pour le second. df[0] + df[1] donne un tableau Pandas contenant les sommes par paires des éléments correspondants des deux tableaux. Après avoir créé l’UDF, vous pouvez l’appeler avec quelques lignes d’entrée :

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

Ici, la fonction Python add_inputs reçoit un DataFrame analogue à celui créé avec le code Python suivant :

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

La ligne return df[0] + df[1] de la fonction du gestionnaire donne un tableau similaire au code Python suivant :

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