Como escrever manipuladores Java para procedimentos armazenados criados com SQL¶

Como escrever um manipulador Java para um procedimento armazenado¶

1. Certifique-se de que seu ambiente atenda aos pré-requisitos.

2. Se você estiver desenvolvendo localmente, configure seu ambiente para usar o Snowpark.

3. Escolha se deseja implantar seu manipulador em linha ou em um estágio.

4. Siga as diretrizes para a classe, método e performance do manipulador.

5. Implemente suporte para recursos como acesso a dados, leitura de arquivos, retorno de dados tabulares e registro e rastreamento.

6. Disponibilize as dependências do seu código no Snowflake.

7. Inclua o código do manipulador em linha ou importado de um estágio quando você criar o procedimento armazenado.

Pré-requisitos¶

Você deve usar a versão 1.3.0 ou uma versão mais recente da biblioteca do Snowpark.

Se você estiver escrevendo um procedimento armazenado, você deve compilar suas classes para serem executadas em uma das seguintes versões do Java:

• 11.x

• 17.x

Configuração do ambiente de desenvolvimento para o Snowpark¶

Se estiver desenvolvendo seu código localmente, configure seu ambiente de desenvolvimento para usar a biblioteca Snowpark. Consulte Configuração do seu ambiente de desenvolvimento para o Snowpark Java.

Como estruturar e criar um código do manipulador¶

Você pode manter o código fonte do manipulador em linha com o SQL que cria o procedimento ou manter o resultado do manipulador compilado em um local separado e referenciá-lo a partir do SQL. Para obter mais informações, consulte Como manter o código do manipulador em linha ou em um estágio.

Para saber mais sobre como criar o código-fonte do manipulador para uso com um procedimento, consulte Empacotamento do código do manipulador.

Diretrizes para a classe do manipulador¶

Ao escrever a classe, observe o seguinte:

• A classe e o método não devem ser protegidos ou privados.

• Se o método não for estático e você quiser definir um construtor, defina um construtor sem argumentos para a classe. O Snowflake ativa esse construtor sem argumentos no momento da inicialização para criar uma instância da sua classe.

• Você pode definir diferentes métodos para diferentes procedimentos armazenados na mesma classe.

Diretrizes para o método do manipulador¶

Ao escrever o método para o procedimento armazenado, observe o seguinte:

• Especifique o objeto Snowpark Session como o primeiro argumento de seu método.

  Quando você chama seu procedimento armazenado, o Snowflake cria automaticamente um objeto Session e o passa para seu procedimento armazenado. (Você, por si só, não pode criar o objeto Session).

• Para o restante dos argumentos e para o valor de retorno, use os tipos Java que correspondem aos tipos de dados Snowflake.

• Seu método deve retornar um valor. Para procedimentos armazenados em Java, é necessário um valor de retorno.

• A execução do procedimento armazenado será interrompida, a menos que o temporizador seja reiniciado pela atividade do código. Em particular, o temporizador de tempo limite é redefinido pelas interações do código com os dados, incluindo operações de arquivo, consultas e iteração por meio de um conjunto de resultados.

• Quando você executa um trabalho filho assíncrono de dentro do manipulador de um procedimento, “disparar e esquecer” não é suportado.

  Em outras palavras, se o manipulador emitir uma consulta filha que ainda esteja em execução quando o trabalho do procedimento pai for concluído, o trabalho filho será cancelado automaticamente.

Tratamento de erros¶

Você pode usar as técnicas normais de tratamento de exceções Java para detectar erros no código do manipulador.

Se ocorrer uma exceção não capturada dentro do método, o Snowflake gera um erro que inclui o rastreamento de pilha da exceção. Quando o registro de exceções não tratadas está ativado, o Snowflake registra dados sobre exceções não tratadas em uma tabela de eventos.

Diretrizes para o desempenho e a segurança do manipulador¶

Para garantir que seu código seja executado corretamente no Snowflake, siga estas diretrizes:

• Limite a quantidade de memória consumida

  O Snowflake impõe limites em um método em termos da quantidade de memória necessária. Para obter mais informações sobre como evitar o consumo excessivo, consulte Criação de manipuladores que ficam dentro das restrições impostas pelo Snowflake.

• Escreva o código thread-safe.

  Certifique-se de que o método ou função do seu manipulador seja thread-safe.

• Entenda as restrições de segurança.

  O código de seu manipulador funciona dentro de um mecanismo restrito, portanto, certifique-se de seguir as regras descritas em Práticas de segurança para UDFs e procedimentos.

• Decida sobre o uso dos direitos do proprietário ou dos direitos do chamador.

  Ao planejar escrever seu procedimento armazenado, considere se deseja que o procedimento armazenado seja executado com direitos do chamador ou direitos do proprietário.

• Lembre-se do comportamento de tempo limite para procedimentos armazenados.

  A execução do procedimento armazenado será interrompida, a menos que o temporizador seja reiniciado pela atividade do código. Em particular, o temporizador de tempo limite é redefinido pelas interações do código com os dados, incluindo operações de arquivo, consultas e iteração por meio de um conjunto de resultados.

Disponibilização das dependências para seus códigos¶

Se seu código de manipulador depender do código definido fora do próprio manipulador (como classes em um arquivo JAR) ou de arquivos de recursos, você pode disponibilizar essas dependências para seu código, carregando-os em um estágio. Ao criar o procedimento, você pode referenciar estas dependências usando a cláusula IMPORTS.

Para obter mais informações, consulte Disponibilização das dependências para seus códigos.