Execução de uma UDF¶

Você pode executar uma função definida pelo usuário (UDF) ou uma função de tabela definida pelo usuário (UDTF) da mesma forma que executa outras funções.

Ferramentas para execução de UDFs¶

Escolha a ferramenta para executar a função.


Linguagem	Abordagem
SQL Execute um comando SQL, por exemplo, usando Snowsight.	Execute o comando SQL SELECT para executar uma UDF.
Java, Python ou Scala com Snowpark Escreva o código localmente em uma das linguagens compatíveis, fazendo com que o código seja executado no Snowflake.	Execute o código do cliente que usa as Snowpark APIs em um dos seguintes idiomas. Java Python Scala
Linha de comando Crie e gerencie entidades Snowflake executando comandos a partir da linha de comando.	Execute comandos do Snowflake CLI: Para executar os comandos SQL. Para executar comandos do Snowpark.
Python No cliente, escreva o código que executa operações de gerenciamento no Snowflake.	Execute o código que usa a Snowflake Python API.
RESTful APIs (independente da linguagem) Faça solicitações de pontos de extremidade RESTful para criar e gerenciar entidades Snowflake.	Faça uma solicitação para criar uma função usando a Snowflake REST API

Como chamar uma UDF com o SQL¶

Em geral, você chama uma UDF da mesma forma que você chama outras funções.

Se uma UDF tem argumentos, você pode especificá-los por nome ou posição.

Por exemplo, a seguinte UDF aceita três argumentos:

CREATE OR REPLACE FUNCTION udf_concatenate_strings(
    first_arg VARCHAR,
    second_arg VARCHAR,
    third_arg VARCHAR)
  RETURNS VARCHAR
  LANGUAGE SQL
  AS
  $$
    SELECT first_arg || second_arg || third_arg
  $$;

Ao chamar a UDF, você pode especificar os argumentos por nome:

SELECT udf_concatenate_strings(
  first_arg => 'one',
  second_arg => 'two',
  third_arg => 'three');

+--------------------------+
| UDF_CONCATENATE_STRINGS( |
|   FIRST_ARG => 'ONE',    |
|   SECOND_ARG => 'TWO',   |
|   THIRD_ARG => 'THREE')  |
|--------------------------|
| onetwothree              |
+--------------------------+

Se você especificar os argumentos por nome, não precisará especificá-los em nenhuma ordem específica:

SELECT udf_concatenate_strings(
  third_arg => 'three',
  first_arg => 'one',
  second_arg => 'two');

+--------------------------+
| UDF_CONCATENATE_STRINGS( |
|   THIRD_ARG => 'THREE',  |
|   FIRST_ARG => 'ONE',    |
|   SECOND_ARG => 'TWO')   |
|--------------------------|
| onetwothree              |
+--------------------------+

Você também pode especificar os argumentos por posição:

SELECT udf_concatenate_strings(
  'one',
  'two',
  'three');

+--------------------------+
| UDF_CONCATENATE_STRINGS( |
|   'ONE',                 |
|   'TWO',                 |
|   'THREE')               |
|--------------------------|
| onetwothree              |
+--------------------------+

Você também pode especificar os argumentos por posição e por nome:

SELECT udf_concatenate_strings(
  'one',
  'two',
  third_arg => 'three');

+--------------------------+
| UDF_CONCATENATE_STRINGS( |
|   'ONE',                 |
|   'TWO',                 |
|   THIRD_ARG => 'THREE')  |
|--------------------------|
| onetwothree              |
+--------------------------+

Nota

Quando você mistura argumentos por posição e por nome, todos os argumentos posicionais devem vir antes de todos os argumentos nomeados.
Quando você especifica um argumento por nome, não pode usar aspas duplas no nome do argumento.

Se duas funções tiverem o mesmo nome, mas tipos de argumento diferentes, você poderá usar os nomes dos argumentos para especificar qual função será executada, se os nomes dos argumentos forem diferentes. Para obter mais informações, consulte Sobrecarga de procedimentos e funções.

Como chamar uma UDF que tem argumentos opcionais¶

Se a UDF tiver argumentos opcionais, você poderá omitir os argumentos opcionais na chamada. Cada argumento opcional possui um valor padrão que é usado quando o argumento é omitido.

Por exemplo, a seguinte UDF tem um argumento obrigatório e dois argumentos opcionais. Cada argumento opcional possui um valor padrão.

CREATE OR REPLACE FUNCTION build_string_udf(
    word VARCHAR,
    prefix VARCHAR DEFAULT 'pre-',
    suffix VARCHAR DEFAULT '-post'
  )
  RETURNS VARCHAR
  AS
  $$
    SELECT prefix || word || suffix
  $$
  ;

Você pode omitir qualquer um dos argumentos opcionais na chamada. Quando você omite um argumento, o valor padrão do argumento é usado.

SELECT build_string_udf('hello');

+---------------------------+
| BUILD_STRING_UDF('HELLO') |
|---------------------------|
| pre-hello-post            |
+---------------------------+

SELECT build_string_udf('hello', 'before-');

+--------------------------------------+
| BUILD_STRING_UDF('HELLO', 'BEFORE-') |
|--------------------------------------|
| before-hello-post                    |
+--------------------------------------+

Se precisar omitir um argumento opcional e especificar outro argumento opcional que apareça após o argumento omitido na assinatura, use argumentos nomeados, em vez de argumentos posicionais.

Por exemplo, suponha que você queira omitir o argumento prefix e especificar o argumento suffix. O argumento suffix aparece após prefix na assinatura, portanto você deve especificar os argumentos por nome:

SELECT build_string_udf(word => 'hello', suffix => '-after');

+-------------------------------------------------------+
| BUILD_STRING_UDF(WORD => 'HELLO', SUFFIX => '-AFTER') |
|-------------------------------------------------------|
| pre-hello-after                                       |
+-------------------------------------------------------+

Como chamar uma UDTF¶

Você pode chamar uma UDTF da mesma forma como você chamaria qualquer função de tabela. Ao chamar uma UDTF na cláusula FROM de uma consulta, especifique o nome e os argumentos da UDTF dentro dos parênteses que seguem a palavra-chave TABLE, como você faria ao chamar uma função de tabela interna.

Em outras palavras, use um formulário como o seguinte para a palavra-chave TABLE quando chamar uma UDTF:

SELECT ...
  FROM TABLE ( udtf_name (udtf_arguments) )

O código no exemplo a seguir chama a função de tabela my_java_udtf, especificando um literal DATE no argumento '2021-01-16'::DATE.

SELECT ...
  FROM TABLE(my_java_udtf('2021-01-16'::DATE));

O argumento para uma função de tabela pode ser uma expressão e não apenas um literal. Por exemplo, uma função de tabela pode ser chamada usando uma coluna de uma tabela. Alguns exemplos estão abaixo, inclusive na seção Exemplos.

Assim como ao chamar UDFs, você pode especificar os argumentos por nome ou por posição.

Para obter mais informações sobre as funções de tabela em geral, consulte função de tabela.

Nota

Você não pode chamar uma UDF dentro da cláusula DEFAULT de uma instrução CREATE TABLE.

Como usar uma tabela ou UDTF como entrada para uma UDTF¶

A entrada para uma função de tabela pode vir de uma tabela ou de outra UDTF, como documentado em Como usar uma tabela como entrada para uma função de tabela.

O exemplo abaixo mostra como utilizar uma tabela para fornecer entrada para a UDTF split_file_into_words:

create table file_names (file_name varchar);
insert into file_names (file_name) values ('sample.txt'),
                                          ('sample_2.txt');

select f.file_name, w.word
   from file_names as f, table(split_file_into_words(f.file_name)) as w;

A saída se assemelha ao seguinte:

+-------------------+------------+
| FILE_NAME         | WORD       |
+-------------------+------------+
| sample_data.txt   | some       |
| sample_data.txt   | words      |
| sample_data_2.txt | additional |
| sample_data_2.txt | words      |
+-------------------+------------+

A cláusula IMPORTS da UDTF deve especificar o nome e o caminho de cada arquivo passado para a UDTF. Por exemplo:

create function split_file_into_words(inputFileName string)
    ...
    imports = ('@inline_jars/sample.txt', '@inline_jars/sample_2.txt')
    ...

Cada arquivo já deve ter sido copiado para um estágio (neste caso, o estágio denominado @inline_jars) antes que a UDTF leia o arquivo.

Para obter um exemplo de uso de uma UDTF como entrada para outra UDTF, consulte Exemplos estendidos usando valores de tabela e outras UDTFs como entrada na documentação UDTF de JavaScript.

Funções de tabela e partições¶

Antes que linhas sejam passadas para funções de tabela, elas podem ser agrupadas em partições. A criação de partições tem dois benefícios principais:

A criação de partições permite que o Snowflake divida a carga de trabalho para melhorar a paralelização e, assim, o desempenho.
A criação de partições permite que o Snowflake processe todas as linhas com uma característica comum como um grupo. Você pode retornar resultados que são baseados em todas as linhas do grupo e não apenas em linhas individuais.

Por exemplo, você pode particionar dados de preços de ações em um grupo por ação. Todos os preços de ações de uma empresa individual podem ser analisados em conjunto, enquanto os preços das ações de cada empresa podem ser analisados independentemente de qualquer outra empresa.

Dados podem ser particionados de forma explícita ou implícita.

Particionamento explícito¶

Particionamento explícito em vários grupos

A instrução a seguir chama a UDTF chamada my_udtf em partições individuais. Cada partição contém todas as linhas para as quais a expressão PARTITION BY é avaliada como o mesmo valor (por exemplo, a mesma empresa ou símbolo de ação).

SELECT *
    FROM stocks_table AS st,
         TABLE(my_udtf(st.symbol, st.transaction_date, st.price) OVER (PARTITION BY st.symbol))

Particionamento explícito em um único grupo

A instrução a seguir chama a UDTF chamada my_udtf em uma partição. A cláusula PARTITION BY <constante> (neste caso PARTITION BY 1) coloca todas as linhas na mesma partição.

SELECT *
    FROM stocks_table AS st,
         TABLE(my_udtf(st.symbol, st.transaction_date, st.price) OVER (PARTITION BY 1))

Para obter um exemplo mais completo e realista, consulte Exemplos de como chamar UDTFs Java em consultas, em particular a subseção intitulada Partição única.

Como ordenar linhas para partições

Para processar as linhas de cada partição em uma ordem especificada, inclua uma cláusula ORDER BY. Isso diz ao Snowflake para passar as linhas para o método do manipulador por linha na ordem especificada.

Por exemplo, se você quiser calcular a média móvel do preço de uma ação ao longo do tempo, ordene os preços das ações por carimbo de data/hora (e particione por símbolo de ação). O exemplo a seguir mostra como fazer isso:

SELECT *
     FROM stocks_table AS st,
          TABLE(my_udtf(st.symbol, st.transaction_date, st.price) OVER (PARTITION BY st.symbol ORDER BY st.transaction_date))

Uma cláusula OVER pode conter uma cláusula ORDER BY mesmo sem uma cláusula PARTITION BY.

Lembre-se de que incluir uma cláusula ORDER BY dentro de uma cláusula OVER não é o mesmo que colocar uma cláusula ORDER BY no nível mais externo da consulta. Se você quiser que todos os resultados da consulta sejam encomendados, você precisa de uma cláusula ORDER BY separada. Por exemplo:

SELECT *
    FROM stocks_table AS st,
         TABLE(my_udtf(st.symbol, st.transaction_date, st.price) OVER (PARTITION BY st.symbol ORDER BY st.transaction_date))
    ORDER BY st.symbol, st.transaction_date, st.transaction_time;

Notas de uso para particionamento explícito

Ao utilizar uma UDTF com uma cláusula PARTITION BY, a cláusula PARTITION BY deve utilizar uma referência de coluna ou uma expressão literal, não uma expressão geral. Por exemplo, o seguinte não é permitido:

SELECT * FROM udtf_table, TABLE(my_func(col1) OVER (PARTITION BY udtf_table.col2 * 2));   -- NO!

Particionamento implícito¶

Se uma função de tabela não particiona explicitamente as linhas usando uma cláusula PARTITION BY, o Snowflake normalmente divide as linhas implicitamente para usar processamento paralelo para melhorar o desempenho.

O número de partições normalmente é baseado em fatores como o tamanho do warehouse que processa a função e a cardinalidade da relação de entrada. As linhas normalmente são atribuídas a partições específicas com base em fatores como a localização física das linhas (por exemplo, por micropartição), de modo que o agrupamento da partição não tem significado.