Visão geral dos procedimentos armazenados¶

Você pode escrever procedimentos armazenados para ampliar o sistema com código de procedimento. Com um procedimento, você pode usar ramificação, looping e outras construções programáticas. Você pode reutilizar um procedimento várias vezes, chamando-o de outro código.

Com um procedimento armazenado, você pode:

Automatizar as tarefas que exigem várias operações de banco de dados realizadas com frequência.
Criar e executar dinamicamente operações de banco de dados.
Execute o código com os privilégios da função proprietária do procedimento, e não com os privilégios da função que executa o procedimento.

Isso permite que o proprietário do procedimento armazenado delegue a capacidade de realizar operações especificadas a usuários que não poderiam executá-las. No entanto, há limitações dos procedimentos armazenados desses direitos do proprietário.

Por exemplo, imagine que você queira limpar um banco de dados apagando dados mais antigos que uma data especificada. Você pode executar a operação de exclusão várias vezes em seu código, cada vez excluindo dados de uma tabela específica. Você pode colocar todas essas instruções em um único procedimento armazenado e, em seguida, passar um parâmetro que especifique a data de corte.

Com o procedimento implementado, você pode chamá-lo para limpar o banco de dados. À medida que o banco de dados muda, é possível atualizar o procedimento para limpar tabelas adicionais; se houver vários usuários que usam o novo comando de limpeza, eles poderão chamar um procedimento, em vez de lembrar o nome de cada tabela e limpar cada tabela individualmente.

Uma UDF é como um procedimento armazenado, mas os dois diferem de forma importante. Para obter mais informações, consulte Escolha se deseja escrever um procedimento armazenado ou uma função definida pelo usuário.

Um procedimento é apenas uma maneira de estender o Snowflake. Para outras forma, veja o seguinte:

Linguagens e ferramentas compatíveis¶

Você pode criar e gerenciar procedimentos armazenados (e outras entidades do Snowflake) usando qualquer uma das várias ferramentas, dependendo de como prefere trabalhar.

Linguagem	Abordagem	Suporte
SQL Com manipulador em Java, JavaScript, Python, Scala ou SQL Scripting	Escreva o código SQL no Snowflake para criar e gerenciar entidades do Snowflake. Escreva a lógica do procedimento em uma das linguagens de manipulador compatíveis.	Java JavaScript Python Scala SQL Scripting
Java, Python ou Scala API Snowpark	No cliente, escreva o código das operações que são enviadas ao Snowflake para processamento.	Java Python Scala
Interface de linha de comando CLI Snowflake	Use a linha de comando para criar e gerenciar entidades Snowflake, especificando propriedades como propriedades de objetos JSON.	Gerenciamento de objetos Snowflake
Python Snowflake Python API	No cliente, escreva o código que executa operações de gerenciamento no Snowflake.	Gerenciamento de procedimentos armazenados
REST Snowflake REST API	Faça solicitações de pontos de extremidade RESTful para criar e gerenciar entidades Snowflake.	Gerenciamento de procedimentos

Você escreve a lógica de um procedimento – seu manipulador – em uma das linguagens suportadas. Uma vez que você tenha um manipulador, você pode criar um procedimento com um comando CREATE PROCEDURE, depois chamar o procedimento com uma instrução CALL.

A partir de um procedimento armazenado, você pode retornar um único valor ou (se suportado com a linguagem do manipulador) dados tabulares. Para obter mais informações sobre os tipos de retorno suportados, consulte CREATE PROCEDURE.

Ao escolher uma linguagem, considere também os locais do manipulador suportados. Nem todas as linguagens oferecem suporte à referência ao manipulador em um estágio (o código do manipulador deve ser em linha em vez disso). Para obter mais informações, consulte Como manter o código do manipulador em linha ou em um estágio.

Linguagem	Localização do manipulador
Java	Inline ou no estágio
JavaScript	Inline
Python	Inline ou no estágio
Scala	Inline ou no estágio
Script Snowflake	Inline

Nota

Para criar e chamar um procedimento anônimo, use CALL (com procedimento anônimo). Criar e chamar um procedimento anônimo não exige uma função com privilégios de esquema CREATE PROCEDURE.

Exemplo de procedimento armazenado¶

O código no exemplo a seguir cria um procedimento armazenado chamado myproc com um manipulador Python chamado run.

CREATE OR REPLACE PROCEDURE myproc(from_table STRING, to_table STRING, count INT)
  RETURNS STRING
  LANGUAGE PYTHON
  RUNTIME_VERSION = '3.9'
  PACKAGES = ('snowflake-snowpark-python')
  HANDLER = 'run'
as
$$
def run(session, from_table, to_table, count):
  session.table(from_table).limit(count).write.save_as_table(to_table)
  return "SUCCESS"
$$;

Copy

O código no exemplo a seguir chama o procedimento armazenado myproc.

CALL myproc('table_a', 'table_b', 5);

Copy

Diretrizes e restrições¶

Dicas:: Para dicas sobre como escrever procedimentos armazenados, consulte Como trabalhar com procedimentos armazenados.
Restrições do Snowflake:: Você pode garantir a estabilidade dentro do ambiente Snowflake desenvolvendo dentro das restrições do Snowflake. Para obter mais informações, consulte Criação de manipuladores que ficam dentro das restrições impostas pelo Snowflake.
Nomeação:: Certifique-se de nomear os procedimentos de forma a evitar colisões com outros procedimentos. Para obter mais informações, consulte Como nomear e sobrecarregar procedimentos e UDFs.
Argumentos:: Especifique os argumentos do seu procedimento armazenado e indique quais argumentos são opcionais. Para obter mais informações, consulte Definição de argumentos para UDFs e procedimentos armazenados.
Mapeamentos de tipos de dados:: Para cada linguagem do manipulador, há um conjunto separado de mapeamentos entre os tipos de dados da linguagem e os tipos SQL usados para valores de retorno e argumentos. Para saber mais sobre os mapeamentos para cada linguagem, consulte Mapeamentos de tipos de dados entre linguagens do manipulador e SQL.

Como escrever o manipulador¶

Linguagens do manipulador:: Para obter conteúdo específico da linguagem ao escrever um manipulador, consulte Linguagens e ferramentas compatíveis.
Acesso à rede externa:: Você pode acessar locais de rede externos com acesso à rede externa. Você pode criar acesso seguro a locais de rede específicos externos ao Snowflake e usar esse acesso de dentro do código do manipulador.
Registro e rastreamento:: Você pode registrar a atividade do código capturando mensagens de registro e eventos de rastreamento e armazenando os dados em um banco de dados que poderá consultar posteriormente.

Segurança¶

Se você optar por ter um procedimento armazenado com os direitos do chamador ou os direitos do proprietário, isso pode ter impacto nas informações a que tem acesso e nas tarefas que pode ser autorizado a realizar. Para obter mais informações, consulte Procedimentos armazenados com direitos do chamador e direitos do proprietário.

Os procedimentos armazenados compartilham certas preocupações de segurança com funções definidas pelo usuário (UDFs). Para obter mais informações, consulte o seguinte:

Você pode ajudar o código do manipulador de um procedimento a ser executado com segurança, seguindo as práticas recomendadas descritas em Práticas de segurança para UDFs e procedimentos
Certifique-se de que as informações sensíveis sejam ocultadas dos usuários que não deveriam ter acesso a elas. Para obter mais informações, consulte Proteção de informações sensíveis com UDFs e procedimentos armazenados seguros

Implementação do código do manipulador¶

Ao criar um procedimento, você pode especificar seu manipulador – que implementa a lógica do procedimento – como código em linha com a instrução CREATE PROCEDURE ou como código externo à instrução, como o código compilado em pacote e copiado em um estágio.

Para obter mais informações, consulte Como manter o código do manipulador em linha ou em um estágio.