Como manter o código do manipulador em linha ou em um estágio¶

Ao criar uma função definida pelo usuário (UDF) ou procedimento armazenado com SQL, pode-se especificar se o código do manipulador está alinhado com o SQL que o cria ou externo ao SQL, como em um arquivo em um estágio. Este tópico descreve a diferença.

Nem todas as linguagens oferecem suporte ao uso de um manipulador em linha ou em estágio. Para obter a lista de idiomas compatíveis, consulte a opção de linguagem para procedimentos armazenados ou UDFs.

Neste tópico:

Diferenças práticas¶

Vantagens do manipulador em linha¶

Funções e procedimentos com manipuladores em linha podem ser mais fáceis de gerenciar. Após utilizar suas ferramentas de desenvolvimento para verificar se seu código funciona como deveria, você pode implementá-lo copiando-o para a instrução SQL que você executa para criar a função ou procedimento. Você pode manter o código lá, atualizando-o com uma instrução SQL (como com ALTER FUNCTION ou ALTER PROCEDURE) sem ter que atualizar o código em outro lugar.

Vantagens do manipulador em estágio¶

Ao usar um manipulador em estágio, você pode fazer o seguinte:

Usar o código que gerencia separadamente em um repositório Git que você está usando do Snowflake.

Para obter mais informações, consulte Como o Snowflake funciona com um repositório Git.
Usar código compilado anteriormente, como quando você já tem a saída compilada, mas não tem o código-fonte.
Usar um código de manipulador que pode ser muito grande para ser colado na instrução SQL com a qual você cria a função ou procedimento. Código inline têm um limite superior no tamanho do código-fonte.
Reutilizar código de manipulador de várias funções ou procedimentos. O código em estágio pode conter múltiplas funções de manipulador em que cada função pode ser usada por um UDF ou procedimento diferente. Ao criar múltiplos UDFs ou procedimentos, cada um deles pode especificar o mesmo arquivo do manipulador, mas especificar uma função de manipulador diferente implementada naquele arquivo.

Em contraste, o manipulador para funções ou procedimentos inline normalmente contém apenas uma função que pode ser chamada. Essa função que pode ser chamada pode chamar outras funções, e essas outras funções podem ser definidas no mesmo arquivo de código ou em outro arquivo de código em estágio.
Usar ferramentas de teste e depuração existentes para fazer a maior parte do trabalho de desenvolvimento. Isso vale particularmente se o código é grande ou complexo.

Como usar um manipulador em linha¶

Quando você estiver usando um manipulador inline, você inclui o código fonte do manipulador na cláusula AS da instrução SQL que cria a função ou procedimento. Por exemplo, você incluiria o código do manipulador na cláusula AS da instrução CREATE FUNCTION ou CREATE PROCEDURE da própria instrução.

Dentro da cláusula AS, você delimita o código com aspas simples ou um par de sinais de dólar ($$). O uso dos cifrões duplos pode ser mais fácil, por exemplo, quando o código-fonte contém aspas simples.

Se o código fonte do manipulador inline precisar ser compilado (como com um manipulador escrito em Java ou Scala), Snowflake compila o código fonte e armazena a saída (como um arquivo JAR) para uso posterior. Opcionalmente, você pode especificar um local para um arquivo de saída resultante com a cláusula TARGET_PATH.

Snowflake gerencia a saída compilada das seguintes maneiras:

Se a instrução SQL (como CREATE FUNCTION) usar TARGET_PATH para especificar um local para o arquivo de saída, Snowflake compila o código uma vez e mantém a saída compilada para uso futuro.
Se a instrução SQL não especificar um local para o arquivo, Snowflake recompila o código para cada instrução SQL que chama a função ou procedimento. O Snowflake limpa automaticamente o arquivo após o término da instrução SQL.

Nota

Como prática recomendada ao usar um manipulador Java ou Scala em linha, considere especificar um valor para o parâmetro TARGET_PATH. Isso pode aumentar o desempenho porque o Snowflake reutilizará o resultado compilado do código do manipulador em vez de recompilar o código para cada chamada ao procedimento ou UDF.

Atenção

Quando o código do manipulador é definido inline, ele será capturado como metadados. Se você não quiser que o código seja capturado como metadados, você poderá implantá-lo de outras maneiras, como usando um manipulador em estágio.

Os clientes devem garantir que nenhum dado pessoal (exceto para um objeto do usuário), dados sensíveis, dados controlados por exportação ou outros dados regulamentados sejam inseridos como metadados ao usar o serviço Snowflake. Para obter mais informações, consulte Campos de metadados no Snowflake.

Exemplo em linha com o manipulador Java¶

O código no exemplo a seguir cria um procedimento MYPROC armazenado com um manipulador inline em Java. O manipulador é o método run da classe MyJavaClass.

CREATE OR REPLACE PROCEDURE MYPROC(fromTable STRING, toTable STRING, count INT)
  RETURNS STRING
  LANGUAGE JAVA
  RUNTIME_VERSION = '11'
  PACKAGES = ('com.snowflake:snowpark:latest')
  HANDLER = 'MyJavaClass.run'
  AS
  $$
    import com.snowflake.snowpark_java.*;

    public class MyJavaClass {
      public String run(Session session, String fromTable, String toTable, int count) {
        session.table(fromTable).limit(count).write().saveAsTable(toTable);
        return "SUCCESS";
      }
    }
  $$;

Copy

Para informações de referência de CREATE PROCEDURE, consulte CREATE PROCEDURE.

Como usar um manipulador em estágio¶

Quando você está usando um manipulador em estágio, você usa a cláusula IMPORTS para referenciar o manipulador em outro local, tal como um estágio. Por exemplo, você especificaria o caminho para o manipulador com a cláusula IMPORTS de uma instrução SQL como CREATE PROCEDURE ou CREATE FUNCTION.

Ao referenciar o nome da função do manipulador com a cláusula HANDLER, é necessário qualificar o nome da função com o nome da classe ou módulo que a contém. Isso contrasta com um manipulador em linha, onde às vezes é possível simplesmente referenciar a função do manipulador apenas pelo nome.

Preparação de um manipulador para uso a partir de uma função ou procedimento¶

O seguinte descreve como adicionar um arquivo de manipulador ao ambiente no qual sua função ou procedimento é executado.

Se necessário, tal como com um manipulador escrito em Java ou Scala, compile e embale o código do manipulador para carregar em um estágio. Para obter mais informações sobre as ferramentas de construção, consulte Empacotamento do código do manipulador.

Para um manipulador escrito em Python, você pode usar a fonte do módulo do manipulador.
Carregue o arquivo do manipulador em um estágio, conforme descrito em Disponibilização das dependências para seus códigos.

Se seu manipulador for de um repositório Git que você está usando com o Snowflake, talvez seja necessário buscar as últimas informações de seu repositório remoto para o estágio do repositório do Snowflake.
Faça referência ao arquivo do manipulador quando criar a função ou procedimento.

Você faz referência ao arquivo do manipulador na cláusula IMPORTS, como descrito em Referência à dependência.

O código no exemplo a seguir cria uma UDF chamada my_udf, cujo manipulador, MyClass.myFunction está escrito em Java. A cláusula IMPORTS do código especifica que o arquivo do manipulador, chamado my_handler.jar, está no estágio mystage no subdiretório do estágio handlers. No tempo de execução, o Snowflake adiciona o JAR do manipulador ao classpath.
```
CREATE FUNCTION my_udf(i NUMBER)
  RETURNS NUMBER
  LANGUAGE JAVA
  IMPORTS = ('@mystage/handlers/my_handler.jar')
  HANDLER = 'MyClass.myFunction'
```
Copy
Para informações de referência de CREATE FUNCTION, consulte CREATE FUNCTION.

Advertências e práticas recomendadas¶

Se você excluir ou renomear o arquivo do manipulador, você não poderá mais chamar a função ou o procedimento. Se você precisar atualizar seu arquivo do manipulador:

Primeiro certifique-se de que não estejam sendo feitas chamadas para a função ou procedimento que utiliza o manipulador.
Use o comando PUT para carregar um novo arquivo do manipulador. Se o arquivo do manipulador antigo ainda estiver no estágio quando você carregar o novo, use a cláusula PUT do comando OVERWRITE=TRUE para substituir o arquivo do manipulador antigo.