Introdução às funções externas¶

Este tópico descreve funções externas, que chamam um código executável que é desenvolvido, mantido, armazenado e executado fora do Snowflake.

Este tópico ajuda a:

Entender o que é uma função externa.
Decidir se uma função externa é a melhor maneira de implementar uma UDF (função definida pelo usuário).
Escolher a plataforma de nuvem para sua função externa.

Neste tópico:

O que é uma função externa?¶

Uma função externa chama um código que é executado fora do Snowflake.

O código executado remotamente é conhecido como um serviço remoto.

As informações enviadas a um serviço remoto são geralmente retransmitidas por um serviço de proxy.

O Snowflake armazena informações sobre funções externas relacionadas à segurança em uma integração de API.

O diagrama abaixo mostra o fluxo de informações básicas a partir de um programa cliente, passando pelo Snowflake e indo para o serviço remoto:

../_images/external-functions-overview-07.png

Cada um dos componentes-chave é descrito em mais detalhes abaixo.

Função externa:

Uma função externa é um tipo de UDF. Ao contrário de outras UDFs, uma função externa não contém seu próprio código; em vez disso, a função externa chama um código que é armazenado e executado fora do Snowflake.

Dentro do Snowflake, a função externa é armazenada como um objeto de banco de dados que contém informações que o Snowflake utiliza para chamar o serviço remoto. Essas informações armazenadas incluem a URL do serviço de proxy que retransmite informações de/para o serviço remoto. Essas informações são especificadas como parte do comando CREATE EXTERNAL FUNCTION.

O objeto de banco de dados que representa a função externa é criado em um banco de dados e esquema específicos. A função externa pode ser chamada usando a notação de ponto para representar o nome totalmente qualificado. Por exemplo:

select my_database.my_schema.my_external_function(col1) from table1;

Copy

Serviço remoto:

O código executado remotamente é conhecido como um serviço remoto.

O serviço remoto deve agir como uma função. Por exemplo, ele deve devolver um valor.

O Snowflake oferece suporte a funções externas escalares; o serviço remoto deve retornar exatamente uma linha para cada linha recebida.

Para ser chamado pelo recurso de função externa do Snowflake, o serviço remoto deve:

Aceitar entradas JSON e retornar saídas JSON. (Para obter mais informações sobre cabeçalhos HTTP e dados em formato JSON compatíveis com o Snowflake, consulte Formatos de dados de entrada e saída de serviços remotos).
Expor um ponto de extremidade HTTPS.

Por exemplo, um serviço remoto pode ser implementado como:

Uma função AWS Lambda.
Uma função do Microsoft Azure.
Um servidor HTTPS (por exemplo, Node.js) executando em uma instância EC2.

Serviço de proxy:

O Snowflake não chama um serviço remoto diretamente. Em vez disso, o Snowflake chama um serviço de proxy, que retransmite os dados para o serviço remoto.

O serviço de proxy pode aumentar a segurança por meio da autenticação de solicitações para o serviço remoto.

O serviço de proxy pode aceitar o faturamento por assinatura para um serviço remoto. Por exemplo, o serviço de proxy pode verificar se um chamador para o serviço remoto é um assinante pago.

O serviço de proxy também retransmite a resposta do serviço remoto de volta ao Snowflake.

Exemplos de serviços de proxy incluem:

Amazon API Gateway.
Serviço de gerenciamento de API do Microsoft Azure.

Integração de API:

Uma integração é um objeto Snowflake que fornece uma interface entre o Snowflake e serviços de terceiros. Uma integração de API armazena informações, como informações de segurança, que são necessárias para trabalhar com um serviço de proxy ou serviço remoto.

Uma integração de API é criada com o comando CREATE API INTEGRATION.

Os usuários podem escrever e chamar seus próprios serviços remotos, ou chamar serviços remotos escritos por terceiros. Esses serviços remotos podem ser escritos usando qualquer pilha de servidor HTTP, incluindo serviços de computação sem servidor na nuvem, como AWS Lambda.

Da perspectiva de um usuário executando uma instrução SQL, uma função externa comporta-se como qualquer outra UDF . As funções externas seguem estas regras:

As funções externas retornam um valor.
As funções externas podem aceitar parâmetros.

Uma função externa pode aparecer em qualquer cláusula de uma instrução SQL na qual outros tipos de UDF podem aparecer. Por exemplo:

select my_external_function_2(column_1, column_2)
    from table_1;

select col1
    from table_1
    where my_external_function_3(col2) < 0;

create view view1 (col1) as
    select my_external_function_5(col1)
        from table9;

Copy

Uma função externa pode ser parte de uma expressão mais complexa:

select upper(zipcode_to_city_external_function(zipcode))
  from address_table;

Copy

O valor retornado pode ser um valor composto, como um VARIANT que contém JSON.
As funções externas podem ser sobrecarregadas; duas funções diferentes podem ter o mesmo nome, mas assinaturas diferentes (números ou tipos de dados diferentes de parâmetros de entrada).

Como funcionam as funções externas¶

O Snowflake não chama diretamente um serviço remoto. Em vez disso, o Snowflake chama o serviço remoto por meio de um serviço de proxy HTTPS nativo de um provedor de nuvem, por exemplo API Gateway na AWS.

Os principais passos para chamar uma função externa são:

O programa cliente de um usuário passa ao Snowflake uma instrução SQL que chama uma função externa.
Ao avaliar a função externa como parte da execução da consulta, o Snowflake lê a definição da função externa e as informações de integração de API correspondentes.
- As informações da definição da função externa incluem:
  - URL do serviço de proxy.
  - O nome da integração de API correspondente.
- As informações da integração de API incluem:
  - O recurso de serviço de proxy a ser utilizado. O recurso contém informações sobre o serviço remoto, como a localização desse serviço.
  - As informações de autenticação para esse recurso de serviço de proxy.
O Snowflake então compõe um comando HTTP POST que inclui:
- Os dados a serem processados. Esses dados estão no formato JSON.
- Informações de cabeçalho HTTP. (Os detalhes estão documentados em CREATE EXTERNAL FUNCTION.)
- Informações de autenticação da integração de API.
O Snowflake então envia a solicitação POST ao serviço de proxy.
O serviço de proxy recebe o POST e então processa e encaminha a solicitação para o serviço remoto real. Você pode pensar, de certa forma, no recurso e serviço de proxy como uma “função de relé” que chama o serviço remoto.
O serviço remoto processa os dados e retorna o resultado, que é passado pela cadeia para a instrução SQL original.
Se o serviço remoto responder com um código HTTP para sinalizar o processamento assíncrono, então o Snowflake envia uma ou mais solicitações HTTP GET para recuperar o resultado do serviço remoto. O Snowflake continua a enviar solicitações GET desde que receba o código de resposta para continuar solicitando, ou até que a função externa expire ou retorne um erro.

Normalmente, quando uma consulta tem um grande número de linhas para enviar a um serviço remoto, as linhas são divididas em lotes. Os lotes geralmente permitem um maior paralelismo e consultas mais rápidas. Em alguns casos, os lotes reduzem a sobrecarga do serviço remoto.

Um serviço remoto retorna 1 lote de linhas para cada lote recebido. Para uma função externa escalar, o número de linhas no lote devolvido é igual ao número de linhas no lote recebido.

Cada lote tem uma ID única de lote, que é incluída em cada solicitação enviada pelo Snowflake para o serviço remoto.

As operações de nova tentativa (por exemplo, devido a expirações do tempo limite) são normalmente feitas em nível de lote.

Vantagens das funções externas¶

As funções externas têm as seguintes vantagens em relação a outras UDFs:

O código para o serviço remoto pode ser escrito em linguagens nas quais outras UDFs não podem ser escritas, inclusive:
- Go
- C#
Os serviços remotos podem utilizar funções e bibliotecas que não podem ser acessadas por UDFs internas. Por exemplo, serviços remotos podem fazer interface com bibliotecas de terceiros disponíveis comercialmente, como bibliotecas de pontuação de machine learning.
Os desenvolvedores podem escrever serviços remotos que podem ser chamados do Snowflake e de outros software escritos para usar a mesma interface.

Limitações das funções externas¶

As funções externas têm as seguintes limitações, que podem ser agrupadas livremente em limitações de tempo de criação e limitações de tempo de execução.

Limitações e requisitos de tempo de criação¶

Antes que uma função externa possa ser chamada pela primeira vez, um administrador deve fazer algum trabalho de configuração. Esse trabalho requer conhecimento da plataforma de nuvem (por exemplo, AWS ou Microsoft Azure), especialmente sobre segurança.
O Snowflake chama serviços remotos indiretamente por meio de um serviço de proxy HTTP na nuvem (como o Amazon API Gateway), portanto, deve ser possível chamar o serviço remoto para uma função externa a partir de um serviço de proxy. Felizmente, quase todas as funções que podem atuar como um ponto de extremidade HTTPS podem ser acessadas como uma função externa por meio de um serviço de proxy. O autor da função deve programar o serviço de proxy para chamar o serviço remoto (por exemplo, uma função em execução no AWS Lambda).
Algumas plataformas de nuvem podem ter requisitos específicos. Por exemplo, na AWS, funções externas requerem pontos de extremidade regionais ou pontos de extremidade privados. Para obter mais detalhes, consulte Plataformas com suporte. Para obter mais detalhes sobre os pontos de extremidade regionais e privados do Amazon API Gateway, consulte Como escolher seu tipo de ponto de extremidade: ponto de extremidade regional vs. ponto de extremidade privado.
Somente funções, não procedimentos armazenados, podem ser escritas usando o recurso de funções externas.
Futuras concessões de privilégios sobre funções externas não são suportadas.

Limitações e problemas de tempo de execução¶

Como o serviço remoto é opaco para o Snowflake, o otimizador pode não ser capaz de realizar algumas otimizações que ele poderia realizar para funções internas equivalentes.
As funções externas têm mais sobrecarga do que as internas (tanto as funções internas quanto as UDFs internas) e normalmente executam mais lentamente.
Atualmente, as funções externas devem ser funções escalares. Uma função externa escalar retorna um único valor para cada linha de entrada.
Atualmente, as funções externas não podem ser compartilhadas com os consumidores de dados via Secure Data Sharing.
O tamanho máximo de resposta por lote é 10MB.
As funções externas não podem ser utilizadas nas seguintes situações:
- Como parte de um objeto de banco de dados (por exemplo, tabela, exibição, UDF ou política de mascaramento) compartilhado via Secure Data Sharing. Por exemplo, não é possível criar uma exibição compartilhada que utilize uma função externa. O seguinte não é aceito:
  CREATE VIEW my_shared_view AS SELECT my_external_function(x) ...; CREATE SHARE things_to_share; ... GRANT SELECT ON VIEW my_shared_view TO SHARE things_to_share; ...
  Copy
- Uma cláusula DEFAULT de uma instrução CREATE TABLE. Em outras palavras, o valor padrão para uma coluna não pode ser uma expressão que chame uma função externa. Se você tentar incluir uma função externa em uma cláusula DEFAULT, a instrução CREATE TABLE falha.
- Uma transformação COPY.
As funções externas podem levantar questões adicionais de segurança. Por exemplo, se você chamar a função de um terceiro, esse terceiro pode manter cópias dos dados passados para a função.

Faturamento para uso de funções externas¶

O uso de funções externas acarreta custos normais associados ao seguinte:

Além disso, pode ser necessário pagar encargos indiretos ou de terceiros, incluindo tacas do provedor do serviço remoto. As taxas podem variar de fornecedor para fornecedor.

Nota

Dados enviados por meio de pontos de extremidade privados do Amazon API Gateway incorrem em cobranças do AWSPrivateLink para entrada e saída.

Plataformas com suporte¶

Plataformas que oferecem suporte à chamada de uma função externa¶

Em geral, uma função externa pode ser chamada a partir de uma conta Snowflake em qualquer plataforma de nuvem compatível com o Snowflake:

Amazon Web Services (AWS)
Microsoft Azure
Google Cloud Platform (GCP)

As exceções estão listadas abaixo:

Uma função externa acessada por meio de um ponto de extremidade privado do AWS API Gateway pode ser acessado somente de uma VPC (nuvem virtual privada) do Snowflake na AWS e na mesma região da AWS. Para obter mais detalhes sobre os pontos de extremidade privados em AWS, consulte Como escolher seu tipo de ponto de extremidade: ponto de extremidade regional vs. ponto de extremidade privado.

A sintaxe SQL para chamar uma função externa é a mesma em todas as plataformas.

As instruções SQL (CREATE EXTERNAL FUNCTION e CREATE API INTEGRATION) que configuram o acesso a esses serviços são as mesmas para todas as plataformas. Entretanto, as cláusulas dentro dessas instruções variam, dependendo das plataformas que hospedam o serviço de proxy e o serviço remoto.

Plataformas que oferecem suporte à criação de um serviço remoto e serviço de proxy para uma função externa¶

Embora uma função externa possa ser chamada de qualquer plataforma, o serviço remoto e o serviço de proxy da função externa devem ser criados em plataformas compatíveis específicas.

Em muitos casos, a plataforma e a conta para o serviço remoto são as mesmas que a plataforma e a conta para o serviço de proxy. No entanto, isso não é obrigatório. Por exemplo, uma consulta SQL poderia chamar um Azure Function (serviço remoto) por meio de um AWS API Gateway (serviço de proxy). A própria consulta SQL poderia estar sendo executada em uma instância do Snowflake rodando na GCP.

Plataformas que oferecem suporte a um serviço remoto¶

Você precisa de uma pilha de servidor HTTP para hospedar o serviço remoto. Qualquer pilha de servidor HTTP compatível com o serviço remoto deve ser compatível com funções externas.

Para criar seu serviço remoto, você normalmente precisa de:

Uma conta com o provedor de uma plataforma de nuvem (por exemplo, uma conta Microsoft Azure para criar um Azure Function). Essa conta fornece serviços de armazenamento e computação para o serviço remoto. Essa conta é separada da sua conta Snowflake.

O Snowflake fornece instruções para a criação de um serviço remoto como:

Uma função AWS Lambda.
Uma função do Microsoft Azure.
Uma Google Cloud Function.

Plataformas que oferecem suporte a um serviço de proxy¶

Você precisa de uma instância de um serviço de proxy HTTP nativo em uma plataforma de nuvem.

Para configurar seu serviço de proxy, você normalmente precisa de:

Uma conta com o provedor de uma plataforma de nuvem (por exemplo, uma conta Amazon para usar a AWS). Essa conta fornece serviços de armazenamento e computação para o serviço de proxy. Essa conta é separada da sua conta Snowflake.
Uma função de plataforma de nuvem que tenha os privilégios necessários para configurar um serviço de proxy. Essa função de plataforma de nuvem é separada de suas funções no Snowflake.

Os seguintes serviços de proxy HTTPS são aceitos:

Amazon API Gateway.
Serviço de gerenciamento de API do Microsoft Azure.
Google Cloud API Gateway.

As seções abaixo contêm informações específicas de plataformas que os usuários devem conhecer antes de escolher uma plataforma.

Restrições específicas de plataformas¶

AWS

Este recurso oferece suporte apenas a pontos de extremidade regionais e privados para o Amazon API Gateway. (Para uma descrição dos diferentes tipos de pontos de extremidade, consulte pontos de extremidade .)
As funções externas do Snowflake e as integrações de API não oferecem suporte a domínios personalizados da AWS. Para acessar um Amazon API Gateway a partir do Snowflake, use a URL padrão gerada pela AWS, semelhante ao seguinte:
```
https://api-id.execute-api.region.amazonaws.com/stage
```
Copy