Como escrever uma UDTF em Python¶

Como definir um método process¶

Defina um método process que receba como valores os argumentos da UDTF convertidos de tipos do SQL, retornando dados que o Snowflake usará para criar o valor de retorno tabular da UDTF.

A assinatura do método deve ser da seguinte forma:

def process(self, *args):

Seu método process deve:

• Ter um parâmetro self.

• Declarar parâmetros do método correspondentes aos parâmetros da UDTF.

  Os nomes de parâmetros do método não precisam corresponder aos nomes de parâmetros da UDTF, mas os parâmetros do método devem ser declarados na mesma ordem que os parâmetros da UDTF.

  Ao passar valores de argumento da UDTF para seu método, o Snowflake converterá os valores dos tipos de SQL para os tipos de Python que você usa no método. Para obter mais informações sobre como o Snowflake mapeia entre tipos de dados de SQL e de Python, consulte Mapeamentos de tipos de dados SQL-Python.

• Produza uma ou mais tuplas (ou retorne um iterável contendo tuplas) na qual a sequência de tuplas corresponde à sequência de colunas de valores de retorno da UDTF.

  Os elementos de tupla devem aparecer na mesma ordem em que as colunas de valor de retorno da UDTF são declaradas. Para obter mais informações, consulte Como retornar um valor neste tópico.

  O Snowflake converterá valores dos tipos de Python para tipos de SQL exigidos pela declaração da UDTF. Para obter mais informações sobre como o Snowflake mapeia entre tipos de dados de SQL e de Python, consulte Mapeamentos de tipos de dados SQL-Python.

Se um método na classe do manipulador gerar uma exceção, o processamento será interrompido. A consulta que chamou a UDTF falhará com uma mensagem de erro. Se o método process retornar None, o processamento será interrompido. (O método end_partition ainda é invocado mesmo que o método process retorne None).

Exemplo do método process

O código no exemplo a seguir mostra uma StockSale classe de manipulador com um método process que processa três argumentos de UDTF (symbol, quantity e price), retornando uma única linha com duas colunas (symbol e total). Observe que os parâmetros do método process são declarados na mesma ordem que os parâmetros stock_sale. Os argumentos na instrução process do método yield estão na mesma ordem que as colunas declaradas na cláusula stock_sale RETURNS TABLE.

create or replace function stock_sale(symbol varchar, quantity number, price number(10,2))
returns table (symbol varchar, total number(10,2))
language python
runtime_version=3.8
handler='StockSale'
as $$
class StockSale:
    def process(self, symbol, quantity, price):
      cost = quantity * price
      yield (symbol, cost)
$$;

O código no exemplo a seguir chama a UDF anterior, passando valores das colunas symbol, quantity e price da tabela stocks_table.

select stock_sale.symbol, total
  from stocks_table, table(stock_sale(symbol, quantity, price) over (partition by symbol));

Como retornar um valor¶

Ao retornar linhas de saída, você pode usar yield ou return (mas não ambos) para retornar tuplas com o valor tabular. Se o método retornar ou produzir None, o processamento para a linha atual será interrompido.

• Ao usar yield, execute uma instrução yield separada para cada linha de saída. Essa é a prática recomendada, pois a avaliação lenta que vem com o yield permite um processamento mais eficiente e pode ajudar a evitar o esgotamento do tempo limite.

  Cada elemento na tupla torna-se um valor de coluna no resultado retornado pela UDTF. A ordem dos argumentos do yield deve corresponder à ordem das colunas declaradas para o valor de retorno na cláusula RETURNS TABLE de CREATE FUNCTION.

  O código no exemplo a seguir retorna valores que representam duas linhas.

  def process(self, symbol, quantity, price):
    cost = quantity * price
    yield (symbol, cost)
    yield (symbol, cost)
  

  Copy

  Observe que como o argumento do yield é uma tupla, você deve incluir uma vírgula final ao passar um único valor na tupla, como no exemplo a seguir.

  yield (cost,)
  

  Copy

• Ao usar return, retorne um iterável com tuplas.

  Cada valor em uma tupla torna-se um valor de coluna no resultado retornado pela UDTF. A ordem dos valores das colunas em uma tupla deve corresponder à ordem das colunas declaradas para o valor de retorno na cláusula RETURNS TABLE de CREATE FUNCTION.

  O código no exemplo a seguir retorna duas linhas, cada uma com duas colunas: símbolo e total.

  def process(self, symbol, quantity, price):
    cost = quantity * price
    return [(symbol, cost), (symbol, cost)]
  

  Copy

Como pular linhas¶

Para pular uma linha de entrada e processar a próxima linha (como quando você estiver validando as linhas de entrada), faça com que o método process retorne um dos seguintes:

• Ao usar return, retorne None, uma lista contendo None ou uma lista vazia para pular a linha.

• Ao usar yield, retorne None para pular uma linha.

  Note que se você tiver várias chamadas para yield, quaisquer chamadas após uma chamada que retorna None serão ignoradas pelo Snowflake.

O código no exemplo a seguir retorna apenas as linhas para as quais number é um número inteiro positivo. Se number não for positivo, o método retornará None para pular a linha atual e continuar processando a próxima linha.

def process(self, number):
  if number < 1:
    yield None
  else:
    yield (number)

Processamento com e sem estado¶

Você pode implementar o manipulador para processar linhas levando em conta as partições ou para processá-las simplesmente linha por linha.

• No processamento levando em conta as partições, o manipulador inclui o código para gerenciar o estado no escopo da partição. Isso inclui um método __init__ que é executado no início do processamento da partição e um método end_partition que o Snowflake invoca após processar a última linha da partição. Para obter mais informações, consulte Processamento de partições neste tópico.

• Em processamento sem levar em conta as partições, o manipulador é executado sem estado, ignorando os limites das partições.

  Para que o manipulador seja executado dessa forma, não inclua um método __init__ ou end_partition.

Como finalizar o processamento da partição¶

Opcionalmente, você pode implementar um método end_partition em sua classe do manipulador que o Snowflake invocará depois de ter processado todas as linhas em uma partição. Nesse método, você pode executar o código para uma partição depois que todas as linhas da partição tiverem sido processadas. Seu método end_partition pode produzir linhas de saída, de modo a retornar os resultados de um cálculo no escopo da partição. Para obter mais informações, consulte Processamento de partições neste tópico.

A assinatura do método deve ser da seguinte forma:

def end_partition(self):

O Snowflake espera o seguinte de sua implementação do método end_partition:

• Ele não deve ser estático.

• Ele não pode ter nenhum outro parâmetro além de self.

• Como alternativa ao retorno de um valor tabular, ele pode produzir uma lista vazia ou None.

Exemplo de tratamento de partições¶

O código no exemplo a seguir calcula o custo total pago em compras para um estoque calculando o custo por compra e somando as compras em conjunto (no método process). O código retorna o total no método end_partition.

Para obter um exemplo de uma UDTF que inclui este manipulador, juntamente com a chamada da UDTF, consulte Exemplo de classe do manipulador.

class StockSaleSum:
  def __init__(self):
    self._cost_total = 0
    self._symbol = ""

  def process(self, symbol, quantity, price):
    self._symbol = symbol
    cost = quantity * price
    self._cost_total += cost
    yield (symbol, cost)

  def end_partition(self):
    yield (self._symbol, self._cost_total)

Ao processar as partições, tenha em mente o seguinte:

• Seu código pode tratar de partições que não estejam explicitamente especificadas em uma chamada para a UDTF. Mesmo quando uma chamada para a UDTF não inclui uma cláusula PARTITION BY, o Snowflake particiona os dados implicitamente.

• Seu método process receberá dados de linha na ordem especificada pela cláusula ORDER BY da partição, se houver.