Funções de tabela

Uma função de tabela retorna um conjunto de linhas para cada linha de entrada. O conjunto retornado pode conter zero, uma ou mais linhas. Cada linha pode conter uma ou mais colunas.

As funções de tabela são às vezes chamadas de “funções tabulares”.

Neste tópico:

O que são funções de tabela?

As funções de tabela são normalmente usadas quando uma função retorna várias linhas para cada entrada individual.

Cada vez que uma função de tabela é chamada, ela pode retornar um número diferente de linhas. Por exemplo, uma função record_high_temperatures_for_date(), que retorna uma lista de altas temperaturas recorde para uma data específica, pode retornar 0 linhas em 10 de abril, 1 linha em 10 de junho e 40 linhas em 20 de agosto.

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.

Como usar uma função de tabela

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

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.

Lista de funções de tabela definidas pelo sistema

O Snowflake fornece as seguintes funções de tabela definidas pelo sistema (ou seja, internas):

Subcategoria

Função

Notas

Carregamento de dados

INFER_SCHEMA

Para obter mais informações, consulte Carregamento de dados para o Snowflake.

VALIDATE

Geração de dados

GENERATOR

Conversão de dados

SPLIT_TO_TABLE

STRTOK_SPLIT_TO_TABLE

Análise baseada em ML

TOP_INSIGHTS (SNOWFLAKE.ML)

Para obter mais informações, consulte Funções baseadas no Snowflake Cortex ML.

Modelagem de objetos

GET_OBJECT_REFERENCES

Consultas semiestruturadas

FLATTEN

Para obter mais informações, consulte Consulta de dados semiestruturados.

Resultados de consultas

RESULT_SCAN

Pode ser usado para realizar operações SQL na saída de outra operação SQL (por exemplo, SHOW).

Perfil de consulta

GET_QUERY_OPERATOR_STATS

Informações de histórico e uso

(Snowflake Information Schema, Account Usage):

Login de usuário

LOGIN_HISTORY , LOGIN_HISTORY_BY_USER

Consultas

QUERY_HISTORY , QUERY_HISTORY_BY_*

QUERY_ACCELERATION_HISTORY

Para obter mais informações, consulte Uso do Query Acceleration Service.

Uso de warehouse e armazenamento

DATABASE_STORAGE_USAGE_HISTORY

WAREHOUSE_LOAD_HISTORY

WAREHOUSE_METERING_HISTORY

STAGE_STORAGE_USAGE_HISTORY

Segurança em nível de coluna e em nível de linha

POLICY_REFERENCES

Marcação de objetos

TAG_REFERENCES

Função de tabela Information Schema.

TAG_REFERENCES_ALL_COLUMNS

Função de tabela Information Schema.

TAG_REFERENCES_WITH_LINEAGE

Função de tabela Account Usage.

Replicação de contas

REPLICATION_GROUP_REFRESH_HISTORY

Para obter mais informações, consulte Introdução à replicação e failover em várias contas

REPLICATION_GROUP_REFRESH_PROGRESS, REPLICATION_GROUP_REFRESH_PROGRESS_BY_JOB

REPLICATION_GROUP_USAGE_HISTORY

Replicação de banco de dados

DATABASE_REFRESH_HISTORY

Para obter mais informações, consulte Replicação de bancos de dados em várias contas.

DATABASE_REFRESH_PROGRESS , DATABASE_REFRESH_PROGRESS_BY_JOB

DATABASE_REPLICATION_USAGE_HISTORY

Carregamento de dados e transferência

COPY_HISTORY

DATA_TRANSFER_HISTORY

PIPE_USAGE_HISTORY

STAGE_DIRECTORY_FILE_REGISTRATION_HISTORY

VALIDATE_PIPE_LOAD

Clustering de dados (dentro de tabelas)

AUTOMATIC_CLUSTERING_HISTORY

Para obter mais informações, consulte Clustering automático.

Tabelas dinâmicas

DYNAMIC_TABLE_GRAPH_HISTORY

Para obter mais informações, consulte Sobre como trabalhar com tabelas dinâmicas.

DYNAMIC_TABLE_REFRESH_HISTORY

Funções externas

EXTERNAL_FUNCTIONS_HISTORY

Para obter mais informações, consulte Como escrever funções externas.

Tabelas externas

AUTO_REFRESH_REGISTRATION_HISTORY

Para obter mais informações, consulte Como trabalhar com tabelas externas.

EXTERNAL_TABLE_FILES

EXTERNAL_TABLE_FILE_REGISTRATION_HISTORY

Manutenção de exibições materializadas

MATERIALIZED_VIEW_REFRESH_HISTORY

Para obter mais informações, consulte Como trabalhar com exibições materializadas.

Notificações

NOTIFICATION_HISTORY

Para obter mais informações, consulte Envio de notificações por e-mail.

Manutenção de SCIM

REST_EVENT_HISTORY

Para obter mais informações, consulte Auditoria com SCIM

Manutenção de otimização de pesquisa

SEARCH_OPTIMIZATION_HISTORY

Para obter mais informações, consulte Serviço de otimização de pesquisa.

Fluxos

SYSTEM$STREAM_BACKLOG

Para obter mais informações, consulte Rastreamento de alterações usando fluxos de tabela.

Tarefas

COMPLETE_TASK_GRAPHS

Para obter mais informações, consulte Execução de instruções SQL em um cronograma utilizando tarefas.

CURRENT_TASK_GRAPHS

SERVERLESS_TASK_HISTORY

TASK_DEPENDENTS

TASK_HISTORY

Regras de rede

NETWORK_RULE_REFERENCES

Função de tabela Information Schema. Para obter mais detalhes, consulte Regras de rede.

Sintaxe

SELECT ...
  FROM [ <input_table> [ [AS] <alias_1> ] ,
         [ LATERAL ]
       ]
       TABLE( <table_function>( [ <arg_1> [, ... ] ] ) ) [ [ AS ] <alias_2> ];
Copy

Para a sintaxe específica da função, consulte a documentação para as funções de tabela individuais definidas pelo sistema.

Notas de uso

  • As funções de tabela também podem ser aplicadas a um conjunto de linhas usando a construção LATERAL.

  • Para habilitar o uso de expressões de tabela, o Snowflake oferece suporte à sintaxe padrão ANSI/ISO para expressões de tabela na cláusula FROM de consultas e subconsultas. Essa sintaxe é usada para indicar que uma expressão retorna uma coleção de linhas em vez de uma única linha.

  • Essa sintaxe ANSI/ISO é válida somente na cláusula FROM da lista SELECT. Você não pode omitir essas palavras-chave e parênteses de uma especificação da subconsulta de coleção em outros contextos.