Como escrever procedimentos armazenados em Scala¶

Pré-requisitos¶

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

Se você estiver escrevendo um procedimento armazenado cujo código do manipulador será copiado em um estágio você deverá compilar suas classes para executar na versão Java 11.x.

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

Configure seu ambiente de desenvolvimento para usar a biblioteca do Snowpark. Consulte Configuração do seu ambiente de desenvolvimento para o Snowpark Scala.

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

Limitações¶

Os Procedimentos Armazenados Snowpark têm as seguintes limitações:

• Não há suporte para simultaneidade. Por exemplo, de dentro de seu código, você não pode enviar consultas a partir de múltiplos threads. O código que emite simultaneamente múltiplas consultas produzirá um erro.

• Se você estiver executando seu procedimento armazenado a partir de uma tarefa, você deve especificar um warehouse ao criar a tarefa. (Você não pode usar recursos computacionais gerenciados pelo Snowflake para executar a tarefa).

• A leitura e escrita de arquivos de código do manipulador de procedimentos armazenados em Scala ainda não é completamente suportada. A leitura e a escrita de arquivos pode resultar em comportamento instável. Isso inclui receber um InputStream como argumento e usar métodos disponíveis da classe FileOperation (que você normalmente acessa através do método Session.file), incluindo put e get.

• Considere as seguintes limitações para usar algumas APIs do Snowpark em seu procedimento armazenado.

  • Quando você usa APIs que executam os comandos PUT e GET (incluindo Session.sql("PUT ...") e Session.sql("GET ...")), você pode escrever somente no diretório /tmp no sistema de arquivos com suporte de memória fornecido para a consulta que chama o procedimento.

  • Não use APIs para ações assíncronas.

  • Não use APIs que criem novas sessões (por exemplo, Session.builder().configs(...).create()).

  • O uso de session.jdbcConnection (e a conexão retornada a partir dele) não é aceito porque pode resultar em um comportamento que não é seguro.

• A criação de objetos temporários nomeados não é suportada em um procedimento armazenado de direitos do proprietário. Um procedimento de armazenamento de direitos do proprietário é um procedimento armazenado que funciona com os privilégios do proprietário do procedimento armazenado. Para obter mais informações, consulte direitos do chamador ou direitos do proprietário.

Planejamento para escrever seu procedimento armazenado¶

Escrita da classe ou objeto¶

O método ou função que você define deve ser parte de uma classe ou objeto.

Ao escrever a classe ou objeto, observe o seguinte:

• A classe (ou objeto) 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 ou objeto.

Escrita do método ou função¶

Ao escrever o método ou função para o procedimento armazenado, observe o seguinte:

• Especifique o objeto Session Snowpark como o primeiro argumento de seu método ou função.

  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 Scala que correspondem aos tipos de dados Snowflake.

• Seu método ou função deve retornar um valor. Para procedimentos armazenados em Scala, é 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.

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.

Acesso aos dados no Snowflake a partir do seu procedimento armazenado¶

Para acessar dados no Snowflake, use as APIs da biblioteca do Snowpark.

Ao tratar uma chamada para seu procedimento armazenado em Scala, o Snowflake cria um objeto Session Snowpark e passa o objeto para o método ou função do seu procedimento armazenado.

Como no caso de procedimentos armazenados em outras linguagens, o contexto da sessão (por exemplo, os privilégios, a base de dados e o esquema atual etc.) é determinado pela condição de o procedimento armazenado ser executado com os direitos do chamador ou com os direitos do proprietário. Para obter mais detalhes, consulte Acesso e definição do estado da sessão.

Você pode usar este objeto Session para chamar APIs na Biblioteca do Snowpark. Por exemplo, você pode criar um DataFrame para uma tabela ou executar uma instrução SQL.

Consulte o Guia do Desenvolvedor do Snowpark para Scala para obter mais informações.

object MyObject
{
  def myProcedure(session: com.snowflake.snowpark.Session, fromTable: String, toTable: String, count: Int): String =
  {
    session.table(fromTable).limit(count).write.saveAsTable(toTable)
    return "Success"
  }
}

object MyObject
{
  val myProcedure = (session: com.snowflake.snowpark.Session, fromTable: String, toTable: String, count: Int): String =>
  {
    session.table(fromTable).limit(count).write.saveAsTable(toTable)
    "Success"
  }
}

Acesso a outras classes e arquivos de recursos¶

Se seu código depender de classes definidas fora do procedimento armazenado (por exemplo, classes em um arquivo JAR separado) ou arquivos de recursos, você pode disponibilizar essas dependências para o manipulador, carregando-as em um estágio. Para obter mais informações, consulte Disponibilização das dependências para seus códigos.

Depois, quando executar a instrução CREATE PROCEDURE, use a cláusula IMPORTS para apontar para esses arquivos.

Compilação e empacotamento do seu código Scala¶

Para facilitar a configuração do seu procedimento armazenado, construa um arquivo JAR que contenha todas as dependências necessárias para seu procedimento armazenado. Depois, você precisará carregar o arquivo JAR para um estágio e apontar para o arquivo JAR de sua instrução CREATE PROCEDURE. Esse processo é mais simples se você tiver menos arquivos JAR para carregar e para os quais apontar.

Carregamento de arquivos para um estágio¶

Para disponibilizar a lógica de seu procedimento (e outras dependências, se houver) para o procedimento, você precisará carregar os arquivos necessários em um estágio. Para obter mais informações, consulte Disponibilização das dependências para seus códigos.

Exemplo¶

Os exemplos nesta seção ilustram o retorno de valores tabulares de um procedimento que filtra por linhas onde uma coluna corresponde a uma cadeia de caracteres.

CREATE OR REPLACE TABLE employees(id NUMBER, name VARCHAR, role VARCHAR);
INSERT INTO employees (id, name, role) VALUES (1, 'Alice', 'op'), (2, 'Bob', 'dev'), (3, 'Cindy', 'dev');

CREATE OR REPLACE PROCEDURE filter_by_role(table_name VARCHAR, role VARCHAR)
RETURNS TABLE(id NUMBER, name VARCHAR, role VARCHAR)
LANGUAGE SCALA
RUNTIME_VERSION = '2.12'
PACKAGES = ('com.snowflake:snowpark:latest')
HANDLER = 'Filter.filterByRole'
AS
$$
import com.snowflake.snowpark.functions._
import com.snowflake.snowpark._

object Filter {
    def filterByRole(session: Session, tableName: String, role: String): DataFrame = {
        val table = session.table(tableName)
        val filteredRows = table.filter(col("role") === role)
        return filteredRows
    }
}
$$;

CREATE OR REPLACE PROCEDURE test_return_geography_table_1()
RETURNS TABLE(g GEOGRAPHY)
...

CALL test_return_geography_table_1();

Stored procedure execution error: data type of returned table does not match expected returned table type

CREATE OR REPLACE PROCEDURE test_return_geography_table_1()
RETURNS TABLE()
...

CREATE OR REPLACE PROCEDURE filter_by_role(table_name VARCHAR, role VARCHAR)
RETURNS TABLE()
LANGUAGE SCALA
RUNTIME_VERSION = '2.12'
PACKAGES = ('com.snowflake:snowpark:latest')
HANDLER = 'Filter.filterByRole'
AS
$$
import com.snowflake.snowpark.functions._
import com.snowflake.snowpark._

object Filter {
    def filterByRole(session: Session, tableName: String, role: String): DataFrame = {
        val table = session.table(tableName)
        val filteredRows = table.filter(col("role") === role)
        return filteredRows
    }
}
$$;

CALL filter_by_role('employees', 'dev');

+----+-------+------+
| ID | NAME  | ROLE |
+----+-------+------+
| 2  | Bob   | dev  |
| 3  | Cindy | dev  |
+----+-------+------+