Como manter o código do manipulador inline 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.

Neste tópico:

Diferenças práticas¶

Vantagens do manipulador inline¶

Geralmente é mais fácil de implementar. 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 utilizar um manipulador em estágio, você:

Pode usar código compilado anteriormente, como quando você já tem a saída compilada, mas não tem a fonte.
Pode usar o código do manipulador que pode ser muito grande para colar 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.
Pode reutilizar código de manipulador de múltiplas 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.
Talvez seja mais conveniente usar as 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.

Uso de um manipulador inline¶

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 inline 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.

Uso de 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.

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.
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.