UDFs de scripts Snowflake¶
O Snowflake oferece suporte a funções definidas pelo usuário SQL (UDFs) que contêm linguagem de procedimento Script Snowflake. Estas UDFs são chamadas de UDFs de scripts Snowflake.
UDFs de scripts Snowflake podem ser chamadas em uma Instrução SQL, como uma instrução SELECT ou uma instrução INSERT. Portanto, eles são mais flexíveis do que um procedimento armazenado do Script Snowflake, que só pode ser chamado em um comando SQL CALL.
Uso geral¶
Uma UDF de script Snowflake avalia o código de procedimento e retorna um valor escalar (ou seja, único).
Você pode usar o seguinte subconjunto de sintaxe do Script Snowflake nos scripts Snowflake UDFs:
Tipos de dados suportados¶
UDFs de scripts Snowflake oferecem suporte aos seguintes tipos de dados para argumentos de entrada e valores de retorno:
Tipos de dados numéricos (por exemplo, INTEGER, NUMBER e FLOAT)
Tipos de dados de cadeia de caracteres e binários (por exemplo, VARCHAR e BINARY)
Tipos de dados de data e hora (por exemplo, DATE, TIME e TIMESTAMP)
Tipos de dados lógicos (por exemplo, BOOLEAN)
UDFs de scripts Snowflake oferecem suporte aos seguintes tipos de dados apenas para argumentos de entrada:
Tipos de dados semiestruturados (por exemplo, VARIANT, OBJECT e ARRAY)
Tipos de dados estruturados (por exemplo, ARRAY, OBJECT e MAP)
Limitações¶
As seguintes limitações se aplicam a UDFs de scripts Snowflake:
Os seguintes tipos de sintaxe de scripts Snowflake não são compatíveis com UDFs de scripts Snowflake:
SQL Instruções não são compatíveis com scripts Snowflake UDFs (incluindo SELECT, INSERT, UPDATE e assim por diante).
UDFs de scripts Snowflake não podem ser definidas como funções de tabela.
Os seguintes tipos de expressão não são compatíveis com UDFs de scripts Snowflake:
Funções definidas pelo usuário
Funções de agregação
Funções de janela
UDFs de scripts Snowflake não pode ser usadas ao criar uma exibição materializada.
UDFs de scripts Snowflake não podem ser usadas ao criar políticas de acesso a linhas e políticas de mascaramento.
UDFs de scripts Snowflake não podem ser usadas para especificar um valor de coluna padrão.
UDFs de scripts Snowflake não podem ser usadas em um comando COPY INTO para carregamento e descarregamento de dados.
UDFs Comando não podem ser memoizáveis.
UDFs Comando têm um limite de 500 argumentos de entrada.
Você não pode registrar mensagens em log para UDFs de scripts Snowflake.
Exemplos¶
Os exemplos a seguir criam e chamam UDFs de scripts Snowflake:
Criação de uma UDF de scripts Snowflake com lógica condicional
Criação de uma UDF de scripts Snowflake com tratamento de exceções
Criação de uma UDF de scripts Snowflake que retorna um valor para uma instrução INSERT
Criação de uma UDF de scripts Snowflake chamada em cláusulas WHERE e ORDER BY
Criação de uma UDF de scripts Snowflake com variáveis¶
Criação de uma UDF de scripts Snowflake que calcula o lucro com base nos valores de dois argumentos:
CREATE OR REPLACE FUNCTION calculate_profit(
cost NUMBER(38, 2),
revenue NUMBER(38, 2))
RETURNS number(38, 2)
LANGUAGE SQL
AS
DECLARE
profit NUMBER(38, 2) DEFAULT 0.0;
BEGIN
profit := revenue - cost;
RETURN profit;
END;
Nota
Se você usar a CLI do Snowflake, SnowSQL, o método Classic Console, execute_stream
ou execute_string
no código do Conector Python, este exemplo exigirá pequenas alterações. Para obter mais informações, consulte Usar o Snowflake Scripting no Snowflake CLI, SnowSQL, Classic Console e Python Connector.
Chame calculate_profit
em uma consulta:
SELECT calculate_profit(100, 110);
+----------------------------+
| CALCULATE_PROFIT(100, 110) |
|----------------------------|
| 10.00 |
+----------------------------+
Você pode usar a mesma UDF de scripts Snowflake e especificam colunas para os argumentos. Primeiro, crie uma tabela e insira os dados:
CREATE OR REPLACE TABLE snowflake_scripting_udf_profit(
cost NUMBER(38, 2),
revenue NUMBER(38, 2));
INSERT INTO snowflake_scripting_udf_profit VALUES
(100, 200),
(200, 190),
(300, 500),
(400, 401);
Chame calculate_profit
em uma consulta e especifique as colunas para os argumentos:
SELECT calculate_profit(cost, revenue)
FROM snowflake_scripting_udf_profit;
+---------------------------------+
| CALCULATE_PROFIT(COST, REVENUE) |
|---------------------------------|
| 100.00 |
| -10.00 |
| 200.00 |
| 1.00 |
+---------------------------------+
Criação de uma UDF de scripts Snowflake com lógica condicional¶
Criação de uma UDF de scripts Snowflake que usa lógica condicional para determinar o nome do departamento com base em um valor INTEGER de entrada:
CREATE OR REPLACE function check_dept(department_id INTEGER)
RETURNS VARCHAR
LANGUAGE SQL
AS
BEGIN
IF (department_id < 3) THEN
RETURN 'Engineering';
ELSEIF (department_id = 3) THEN
RETURN 'Tool Design';
ELSE
RETURN 'Marketing';
END IF;
END;
Nota
Se você usar a CLI do Snowflake, SnowSQL, o método Classic Console, execute_stream
ou execute_string
no código do Conector Python, este exemplo exigirá pequenas alterações. Para obter mais informações, consulte Usar o Snowflake Scripting no Snowflake CLI, SnowSQL, Classic Console e Python Connector.
Chame check_dept
em uma consulta:
SELECT check_dept(2);
+---------------+
| CHECK_DEPT(2) |
|---------------|
| Engineering |
+---------------+
Você pode usar uma variável SQL em um argumento quando você chama uma UDF de scripts Snowflake. O exemplo a seguir define uma variável SQL e, em seguida, usa a variável em uma chamada para a check_dept
UDF:
SET my_variable = 3;
SELECT check_dept($my_variable);
+--------------------------+
| CHECK_DEPT($MY_VARIABLE) |
|--------------------------|
| Tool Design |
+--------------------------+
Criação de uma UDF de scripts Snowflake com um loop¶
Criação de uma UDF de scripts Snowflake que usa um loop para contar todos os números até um número de destino fornecido em um argumento e calcular a soma de todos os números contados:
CREATE OR REPLACE function count_to(
target_number INTEGER)
RETURNS VARCHAR
LANGUAGE SQL
AS
DECLARE
counter INTEGER DEFAULT 0;
sum_total INTEGER DEFAULT 0;
BEGIN
WHILE (counter < target_number) DO
counter := counter + 1;
sum_total := sum_total + counter;
END WHILE;
RETURN 'Counted to ' || counter || '. Sum of all numbers: ' || sum_total;
END;
Nota
Se você usar a CLI do Snowflake, SnowSQL, o método Classic Console, execute_stream
ou execute_string
no código do Conector Python, este exemplo exigirá pequenas alterações. Para obter mais informações, consulte Usar o Snowflake Scripting no Snowflake CLI, SnowSQL, Classic Console e Python Connector.
Chame count_to
em uma consulta:
SELECT count_to(10);
+---------------------------------------+
| COUNT_TO(10) |
|---------------------------------------|
| Counted to 10. Sum of all numbers: 55 |
+---------------------------------------+
Criação de uma UDF de scripts Snowflake com tratamento de exceções¶
Criação de uma UDF de scripts Snowflake que declara uma exceção e depois gera a exceção:
CREATE OR REPLACE FUNCTION raise_exception(input_value INTEGER)
RETURNS VARCHAR
LANGUAGE SQL
AS
DECLARE
counter_val INTEGER DEFAULT 0;
my_exception EXCEPTION (-20002, 'My exception text');
BEGIN
WHILE (counter_val < 12) DO
counter_val := counter_val + 1;
IF (counter_val > 10) THEN
RAISE my_exception;
END IF;
END WHILE;
RETURN counter_val;
EXCEPTION
WHEN my_exception THEN
IF (input_value = 1) THEN
RETURN 'My exception caught: ' || sqlcode;
ELSEIF (input_value = 2) THEN
RETURN 'My exception caught with different path: ' || sqlcode;
END IF;
RETURN 'Default exception handling path: ' || sqlcode;
END;
Nota
Se você usar a CLI do Snowflake, SnowSQL, o método Classic Console, execute_stream
ou execute_string
no código do Conector Python, este exemplo exigirá pequenas alterações. Para obter mais informações, consulte Usar o Snowflake Scripting no Snowflake CLI, SnowSQL, Classic Console e Python Connector.
Chame raise_exception
em uma consulta e especifique 1
para o valor de entrada:
SELECT raise_exception(1);
+-----------------------------+
| RAISE_EXCEPTION(1) |
|-----------------------------|
| My exception caught: -20002 |
+-----------------------------+
Chame raise_exception
em uma consulta e especifique 2
para o valor de entrada:
SELECT raise_exception(2);
+-------------------------------------------------+
| RAISE_EXCEPTION(2) |
|-------------------------------------------------|
| My exception caught with different path: -20002 |
+-------------------------------------------------+t
Chame raise_exception
em uma consulta e especifique NULL
para o valor de entrada:
SELECT raise_exception(NULL);
+-----------------------------------------+
| RAISE_EXCEPTION(NULL) |
|-----------------------------------------|
| Default exception handling path: -20002 |
+-----------------------------------------+
Criação de uma UDF de scripts Snowflake que retorna um valor para uma instrução INSERT¶
Criação de uma UDF de scripts Snowflake que retorna um valor que é usado em uma instrução INSERT. Crie a tabela na qual os valores serão inseridos:
CREATE OR REPLACE TABLE test_sql_udf_insert (num NUMBER);
Crie uma UDF SQL que retorna um valor numérico:
CREATE OR REPLACE FUNCTION value_to_insert(l NUMBER, r NUMBER)
RETURNS number
LANGUAGE SQL
AS
BEGIN
IF (r < 0) THEN
RETURN l/r * -1;
ELSEIF (r > 0) THEN
RETURN l/r;
ELSE
RETURN 0;
END IF;
END;
Nota
Se você usar a CLI do Snowflake, SnowSQL, o método Classic Console, execute_stream
ou execute_string
no código do Conector Python, este exemplo exigirá pequenas alterações. Para obter mais informações, consulte Usar o Snowflake Scripting no Snowflake CLI, SnowSQL, Classic Console e Python Connector.
Chame value_to_insert
em várias instruções INSERT:
INSERT INTO test_sql_udf_insert SELECT value_to_insert(10, 2);
INSERT INTO test_sql_udf_insert SELECT value_to_insert(10, -2);
INSERT INTO test_sql_udf_insert SELECT value_to_insert(10, 0);
Consulte a tabela para visualizar os valores inseridos:
SELECT * FROM test_sql_udf_insert;
+-----+
| NUM |
|-----|
| 5 |
| 5 |
| 0 |
+-----+
Criação de uma UDF de scripts Snowflake chamada em cláusulas WHERE e ORDER BY¶
Criação de uma UDF de scripts Snowflake que retorna um valor que é usado em uma cláusula WHERE ou ORDER BY. Criar uma tabela e inserir valores:
CREATE OR REPLACE TABLE test_sql_udf_clauses (p1 INT, p2 INT);
INSERT INTO test_sql_udf_clauses VALUES
(100, 7),
(100, 3),
(100, 4),
(NULL, NULL);
Crie uma UDF SQL que retorna um valor numérico que é o produto da multiplicação de dois valores de entrada:
CREATE OR REPLACE FUNCTION get_product(a INTEGER, b INTEGER)
RETURNS VARCHAR
LANGUAGE SQL
AS
BEGIN
RETURN a * b;
END;
Nota
Se você usar a CLI do Snowflake, SnowSQL, o método Classic Console, execute_stream
ou execute_string
no código do Conector Python, este exemplo exigirá pequenas alterações. Para obter mais informações, consulte Usar o Snowflake Scripting no Snowflake CLI, SnowSQL, Classic Console e Python Connector.
Chame get_product
na cláusula WHERE de uma consulta para retornar as linhas onde o produto é maior que 350
:
SELECT *
FROM test_sql_udf_clauses
WHERE get_product(p1, p2) > 350;
+-----+----+
| P1 | P2 |
|-----+----|
| 100 | 7 |
| 100 | 4 |
+-----+----+
Chame get_product
na cláusula ORDER BY de uma consulta para ordenar os resultados do produto mais baixo para o mais alto retornado pela UDF:
SELECT *
FROM test_sql_udf_clauses
ORDER BY get_product(p1, p2);
+------+------+
| P1 | P2 |
|------+------|
| 100 | 3 |
| 100 | 4 |
| 100 | 7 |
| NULL | NULL |
+------+------+