Funções de tabela¶

Exemplos simples de funções de tabela¶

As seguintes são apropriadas como funções de tabela:

• Uma função que aceita um número de conta e uma data, retornando todas as cobranças faturadas para essa conta naquela data. (Mais de uma cobrança poderia ter sido faturada em uma determinada data).

• Uma função que aceita uma ID de usuário e retorna as funções do banco de dados atribuídas a esse usuário. (Um usuário pode ter múltiplas funções, incluindo “sysadmin” e “useradmin”).

Funções em que cada linha de saída depende de múltiplas linhas de entrada¶

As funções de tabela podem ser agrupadas em duas categorias com base no número de linhas de entrada que afetam cada linha de saída:

• 1-to-N

• M-to-N

As funções descritas anteriormente são funções de tabela 1-to-N: cada linha de saída depende de apenas uma linha de entrada. Por exemplo, uma função record_high_temperatures_for_date() pode produzir várias linhas de saída (uma para cada cidade que bateu um recorde naquela data). Cada linha de saída para uma data de entrada específica depende apenas dessa data; cada linha de saída é independente das linhas para todas as outras datas.

O Snowflake também oferece suporte a funções de tabela M-to-N: cada linha de saída pode depender de múltiplas linhas de entrada. Por exemplo, se uma função gera uma média móvel dos preços de ações, essa função utiliza os preços de ações de múltiplas linhas de entrada (múltiplas datas) para gerar cada linha de saída.

De forma mais geral, em uma função M-to-N, um grupo de linhas de entrada M produz um grupo de linhas de saída N. M pode ser uma ou mais linhas. N pode ser zero, uma ou mais linhas.

Por exemplo, em uma média móvel de 10 dias, M é 10. N é 1 porque cada grupo de 10 linhas de entrada produz um preço médio.

Funções de tabela internas vs. Funções de tabela definidas pelo usuário¶

O Snowflake fornece centenas de funções internas, muitas das quais são funções de tabela. As funções de tabela internas estão listadas em Funções de tabela definidas pelo sistema.

Os usuários também podem escrever suas próprias funções, chamadas de funções definidas pelo usuário ou “UDFs”. Algumas UDFs são escalares; outras são tabulares. As funções de tabela definidas pelo usuário são chamadas de “UDTFs”. Para obter mais informações sobre UDFs (incluindo UDTFs), consulte Visão geral das funções definidas pelo usuário.

As funções de tabela internas e as funções de tabela definidas pelo usuário geralmente seguem as mesmas regras; por exemplo, são chamadas da mesma forma a partir de instruções SQL.

Uso de uma função de tabela na cláusula FROM¶

Uma tabela contém um conjunto de linhas. Da mesma forma, uma função de tabela retorna um conjunto de linhas. Tanto as tabelas quanto as funções de tabela são utilizadas em contextos que esperam um conjunto de linhas. Especificamente, as funções de tabela são usadas na cláusula FROM de uma instrução SQL.

Para ajudar o compilador SQL a reconhecer uma função de tabela como uma fonte de linhas, o Snowflake precisa que a chamada da função de tabela seja delimitada pela palavra-chave TABLE().

Por exemplo, a seguinte instrução chama uma função de tabela intitulada record_high_temperatures_for_date(), que usa um valor DATE como argumento:

SELECT city_name, temperature
    FROM TABLE(record_high_temperatures_for_date('2021-06-27'::DATE))
    ORDER BY city_name;

Copy

Para obter mais informações sobre a sintaxe da TABLE(), consulte Literais de tabela.

As funções de tabela, como as funções em geral, podem aceitar zero, um ou múltiplos argumentos de entrada em cada invocação. Cada argumento deve ser uma expressão escalar.

Para obter mais detalhes sobre a sintaxe das chamadas de funções de tabela, consulte Sintaxe (neste tópico).

Como usar uma tabela como entrada para uma função de tabela¶

O argumento para uma função de tabela pode ser um literal ou uma expressão, como uma coluna de uma tabela. Por exemplo, a instrução SELECT abaixo passa valores de uma tabela como argumentos para uma função de tabela:

CREATE OR REPLACE table dates_of_interest (event_date DATE);
INSERT INTO dates_of_interest (event_date) VALUES
    ('2021-06-21'::DATE),
    ('2022-06-21'::DATE);

CREATE OR REPLACE FUNCTION record_high_temperatures_for_date(d DATE)
    RETURNS TABLE (event_date DATE, city VARCHAR, temperature NUMBER)
    as
    $$
    SELECT d, 'New York', 65.0
    UNION ALL
    SELECT d, 'Los Angeles', 69.0
    $$;

SELECT
        doi.event_date as "Date", 
        record_temperatures.city,
        record_temperatures.temperature
    FROM dates_of_interest AS doi,
         TABLE(record_high_temperatures_for_date(doi.event_date)) AS record_temperatures
      ORDER BY doi.event_date, city;
+------------+-------------+-------------+
| Date       | CITY        | TEMPERATURE |
|------------+-------------+-------------|
| 2021-06-21 | Los Angeles |          69 |
| 2021-06-21 | New York    |          65 |
| 2022-06-21 | Los Angeles |          69 |
| 2022-06-21 | New York    |          65 |
+------------+-------------+-------------+

Os argumentos para uma função de tabela podem vir de outras fontes semelhantes a tabelas, incluindo exibições e outras funções de tabela.