Criação de funções externas de alto desempenho¶

Serviço remoto síncrono¶

Antes que um usuário possa chamar uma função externa, os desenvolvedores e administradores de conta Snowflake devem configurar o Snowflake para acessar o serviço de proxy. Normalmente, as etapas são feitas aproximadamente na ordem mostrada abaixo (começando do lado direito do diagrama acima e indo para a esquerda em direção ao Snowflake).

1. Um desenvolvedor deve escrever o serviço remoto, e esse serviço remoto deve ser exposto por meio do serviço de proxy HTTPS. Por exemplo, o serviço remoto pode ser uma função Python sendo executada no AWS Lambda e exposta por meio de um recurso no Amazon API Gateway.

2. No Snowflake, um ACCOUNTADMIN ou uma função com o privilégio CREATE INTEGRATION deve criar um objeto de “integração de API” que contenha informações de autenticação que permitam ao Snowflake se comunicar com o serviço de proxy. A integração de API é criada com o comando SQL CREATE API INTEGRATION.

3. Um usuário do Snowflake deve executar o comando SQL CREATE EXTERNAL FUNCTION. O usuário deve usar uma função que tenha o privilégio USAGE na integração de API e tenha privilégios suficientes para criar funções.

   Nota

   O comando CREATE EXTERNAL FUNCTION não cria de fato uma função externa no sentido de carregar um código que será “executado fora do Snowflake”. Em vez disso, o comando CREATE EXTERNAL FUNCTION cria um objeto de banco de dados que faz referência indiretamente ao código que executa fora do Snowflake. Mais precisamente, o comando CREATE EXTERNAL FUNCTION cria um objeto que contém:

   • A URL do recurso no serviço de proxy HTTPS que atua como uma função de relé.

   • O nome da integração de API a ser usada para autenticar para o serviço de proxy.

   • Um nome que é efetivamente um alias para o serviço remoto. Este alias é usado em comandos SQL, por exemplo SELECT MyAliasForRemoteServiceXYZ(col1) ...;

O alias no Snowflake, o nome do recurso do serviço de proxy HTTPS e o nome do serviço remoto podem ser diferentes. (Entretanto, usar o mesmo nome para todos os três pode simplificar a administração).

Embora as etapas descritas acima sejam a forma mais comum de executar uma função externa, algumas variações são permitidas. Por exemplo:

• O serviço remoto pode não ser a etapa final da cadeia; o serviço remoto pode chamar mais um serviço remoto para fazer parte do trabalho.

• Se o serviço remoto não aceitar e retornar dados no formato JSON, então o recurso do serviço de proxy HTTPS (a função relé) pode converter os dados do formato JSON em outro formato (e converter os dados retornados em JSON novamente).

• Embora o Snowflake recomende que o serviço remoto se comporte como uma função verdadeira (ou seja, uma parte do código que aceita 0 ou mais parâmetros de entrada e retorna uma saída) que não tem efeitos colaterais e não mantém informações de estado, isso não é estritamente necessário. O serviço remoto pode realizar outras tarefas, por exemplo, enviar alertas se um valor (como uma leitura de temperatura nos dados) for perigosamente alto. Em casos raros, o serviço remoto pode manter informações de estado, por exemplo, o número total de alertas emitidos.

Serviço remoto assíncrono¶

Um serviço remoto assíncrono é útil quando um serviço remoto excede o tempo limite incorporado a componentes como o serviço de proxy.

Um serviço remoto assíncrono envolve os mesmos componentes (cliente, Snowflake, serviço de proxy e serviço remoto) e as mesmas etapas gerais descritas acima. Entretanto, os detalhes das solicitações e respostas HTTP são diferentes.

O comportamento assíncrono é implementado pela pessoa que escreve o serviço remoto (e pelo Snowflake). As instruções SQL são as mesmas para serviços remotos assíncronos e para serviços remotos síncronos.

Se você estiver escrevendo seu próprio serviço remoto e quiser torná-lo compatível com o tratamento assíncrono do Snowflake, escreva o serviço remoto para comportar-se da seguinte forma:

• Quando recebe inicialmente um HTTP POST para um lote específico de linhas, o serviço remoto retorna um código HTTP 202 (“Processando…”).

• Se o serviço remoto receber qualquer solicitação HTTP GET após o POST, mas antes que a saída esteja pronta, o serviço remoto retorna o código HTTP 202.

• Após o serviço remoto ter gerado todas as linhas de saída, ele espera pelo próximo HTTP GET com a mesma ID de lote e depois retorna as linhas recebidas, juntamente com o código HTTP 200 (“Concluído com sucesso…”).

Em resumo, para cada lote recebido, o serviço remoto retorna 202 até que os resultados estejam prontos, depois o próximo GET recebe os resultados e um HTTP 200.

Para cada lote, o Snowflake trabalha com o serviço remoto assíncrono da seguinte forma:

1. O Snowflake envia um HTTP POST que contém os dados a processar, juntamente com uma ID única de lote.

2. Se o Snowflake receber uma resposta HTTP 202, então o Snowflake faz loops até que uma das seguintes afirmações seja verdadeira:

   • O Snowflake recebe os dados e um HTTP 200.

   • O tempo limite interno do Snowflake é alcançado.

   • O Snowflake recebe um erro (por exemplo, código de resposta HTTP 5XX).

   Em cada iteração do loop, o Snowflake retarda, então emite um HTTP GET que contém a mesma ID de lote que a ID de lote HTTP POST correspondente, para que o serviço remoto possa retornar informações para o lote correto.

   O atraso dentro do loop começa curto, mas fica mais longo para cada resposta HTTP 202 recebida até que o tempo limite do Snowflake seja alcançado.

3. Se o tempo limite do Snowflake for alcançado antes que HTTP 200 seja retornado, então o Snowflake anula a consulta SQL.

   Atualmente, o tempo limite do Snowflake é de 10 minutos (600 segundos) e não é configurável pelo usuário. Esse tempo limite pode mudar no futuro.

Escalabilidade do serviço remoto¶

Os desenvolvedores que escrevem serviços remotos devem considerar:

• A frequência com que o serviço remoto será chamado.

• O número de linhas enviadas por chamada.

• Os recursos necessários para processar cada linha.

• A distribuição horária das chamadas (pico vs. média).

É possível que a capacidade precise ser aumentada com o tempo quando, em vez de poucos desenvolvedores e testadores, os chamadores se tornarem uma organização inteira. Se o serviço remoto for utilizado por várias organizações, a capacidade pode precisar aumentar à medida que o número de organizações aumenta. Além disso, à medida que o número e a diversidade das organizações aumentam, o tamanho e o intervalo das cargas de trabalho podem se tornar mais difíceis de prever.

O provedor de serviços remoto é responsável por fornecer capacidade suficiente para lidar com picos de carga de trabalho. Diferentes técnicas podem ser usadas para escalonar o serviço. Se o serviço remoto é gerenciado pelo autor do serviço remoto, então o autor pode precisar fornecer explicitamente o serviço com capacidade suficiente para lidar com os picos. Alternativamente, o autor pode decidir usar um serviço hospedado elástico/de dimensionamento automático, como o AWS Lambda.

Os serviços remotos devem retornar o código de resposta HTTP 429 quando sobrecarregados. Se o Snowflake vir HTTP 429, o Snowflake reduzirá a taxa de envio de linhas e tentará enviar novamente lotes de linhas que não foram processados com sucesso.

Para obter mais informações sobre a solução de problemas de escalabilidade, consulte Solução de problemas de escalabilidade e desempenho.

Se as invocações de serviço remoto expirarem porque cada invocação individual leva muito tempo, e não porque o sistema está sobrecarregado de forma geral, então consulte a descrição de como construir um Serviço remoto assíncrono.

Escalabilidade do serviço de proxy¶

O serviço de proxy também deve escalonável. Felizmente, os serviços de proxy fornecidos pelos principais provedores de nuvem são geralmente escalonáveis.

No entanto, alguns serviços de proxy, incluindo o Amazon API Gateway e o Gerenciamento de API do Azure, têm limites de uso padrão. Quando a taxa de solicitação excede o limite, esses serviços de proxy limitam as solicitações. Se necessário, você pode pedir que a AWS ou o Azure aumente sua quota em seu serviço de proxy.

Os usuários que desenvolvem ou administram funções externas devem se lembrar das seguintes informações específicas das plataformas:

Amazon API Gateway

O Amazon API Gateway é por si só um serviço gerenciado da AWS, que tem dimensionamento automático para as cargas de trabalho dos usuários. Os usuários devem estar familiarizados com vários limites do API Gateway .

O Amazon API Gateway pode ser configurado para ajudar a escalonar o serviço remoto. Especificamente, o API Gateway pode ser configurado para permitir cache e/ou limitação de solicitações para reduzir a carga no serviço remoto, se necessário:

• Habilitar o cache

• Habilitar a limitação

Como a limitação pode afetar o tempo limite e as novas tentativas, os usuários também podem rever as informações sobre como o Snowflake lida com tempo limite e novas tentativas:

• Considerar erros de tempo limite

• Não presumir que cada linha é passada para o serviço remoto somente uma vez

Serviço de gerenciamento de API do Azure

Para o gerenciamento de API do Azure, os limites dependem da SKU escolhida para o serviço. Os limites estão documentados na seção de limites de gerenciamento de API dos Limites de serviço da assinatura do Azure .

Como a limitação pode afetar o tempo limite e as novas tentativas, os usuários também podem rever as informações sobre como o Snowflake lida com tempo limite e novas tentativas:

• Considerar erros de tempo limite

• Não presumir que cada linha é passada para o serviço remoto somente uma vez

Solução de problemas de escalabilidade e desempenho¶

• Use a função QUERY_HISTORY , QUERY_HISTORY_BY_* para observar as características de desempenho e ajudar na depuração de problemas de desempenho.

• Use a página Perfil de consulta para ver a latência média por solicitação.

• Use a página Perfil de consulta para ver quantas novas tentativas de solicitações foram feitas devido a erros transitórios, incluindo aqueles listados na seção intitulada Não presumir que cada linha é passada para o serviço remoto somente uma vez.

• Monitore o uso dos recursos de serviço remoto para ver como ele se adapta à carga, e certifique-se de que o serviço remoto tenha capacidade suficiente para atender aos picos de carga.

• Faça login no Amazon API Gateway ou no serviço remoto para obter detalhes por solicitação.

• Controle a simultaneidade com a qual o Snowflake envia solicitações para o serviço remoto. Para obter mais detalhes, consulte simultaneidade.

• Retorne o código de resposta HTTP 429 do serviço remoto quando este estiver sobrecarregado. Retorne isso o quanto antes, em vez de esperar que a latência aumente.

• Leve em conta o tempo limite do serviço de proxy. Por exemplo, a partir de julho de 2020, o tempo limite para o Amazon API Gateway é 30 segundos. O limite de tempo excedido pode ser causado por vários fatores, incluindo a sobrecarga do serviço remoto.

O Snowflake tenta fazer novas tentativas para erros transitórios/tempo limite excedido dentro de um intervalo razoável, mas se o serviço continuar sobrecarregado e as novas tentativas não forem bem-sucedidas, a consulta é anulada em um determinado momento.