Visão geral dos procedimentos armazenados¶

Você pode escrever procedimentos armazenados para estender o sistema com código de procedimento que executa SQL. Em um procedimento armazenado, você pode usar construções programáticas para realizar ramificações e looping. Uma vez criado um procedimento armazenado, você pode reutilizá-lo várias vezes.

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.

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.

Nota

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.

Neste tópico:

O que é um procedimento armazenado?¶

Um procedimento armazenado contém a lógica que você escreve para que possa chamá-lo do SQL. A lógica de um procedimento armazenado normalmente realiza operações de banco de dados executando instruções SQL.

Com um procedimento armazenado, você também pode:

Criar e executar instruções SQL dinamicamente.
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.

Você pode querer usar um procedimento armazenado para automatizar uma tarefa que requer múltiplas instruções SQL e é executada com frequência. Por exemplo, imagine que você queira limpar um banco de dados apagando dados mais antigos que uma data especificada. Você pode escrever várias instruções DELETE, cada uma das quais exclui dados de uma tabela específica. Você pode colocar todas essas instruções em um único procedimento armazenado e passar um parâmetro que especifica a data de corte. Depois, você pode simplesmente chamar o procedimento para limpar o banco de dados. Conforme seu banco de dados muda, você pode atualizar o procedimento para limpar tabelas adicionais; se houver vários usuários que usam o comando de limpeza, eles podem chamar um procedimento, em vez de lembrar o nome de cada tabela e limpar cada tabela individualmente.

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

Linguagens compatíveis¶

Você escreve um manipulador de procedimentos – sua lógica – em qualquer uma das várias linguagens de programação. Cada linguagem permite a manipulação de dados dentro das restrições da linguagem e de seu ambiente de tempo de execução. Independentemente da linguagem do manipulador, você cria o procedimento em si da mesma forma usando SQL, especificando a linguagem idioma do manipulador e o manipulador.

Você pode escrever um manipulador em qualquer uma das seguintes linguagens:

Linguagem	Guia do desenvolvedor
Java (usando a API Snowpark)	Como escrever procedimentos armazenados em Java
JavaScript	Como escrever procedimentos armazenados em JavaScript
Python (usando a API Snowpark)	Como escrever procedimentos armazenados em Python
Scala (usando a API Snowpark)	Como escrever procedimentos armazenados em Scala
Script Snowflake (SQL)	Como escrever procedimentos armazenados no Script Snowflake

Escolha da linguagem¶

Você pode escolher uma linguagem em particular se:

Você já tem o código nesta linguagem.

Por exemplo, se você já tiver um método Java que funcionará como um manipulador, e o objeto do método estiver em um arquivo .jar, você poderia copiar o .jar para um estágio, especificar o manipulador como a classe e o método, e então especificar a linguagem como Java.
A linguagem tem capacidades que as outras não têm.
A linguagem tem bibliotecas que podem ajudar você a fazer o processamento desejado.

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

Guias do desenvolvedor¶

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

Procedimentos de criação e chamada¶

Você usa SQL para criar e chamar um procedimento.

Uma vez que você tenha escrito o código do manipulador, você pode criar um procedimento armazenado executando a instrução CREATE PROCEDURE, especificando o manipulador do procedimento. Para obter mais informações, consulte Criação de um procedimento armazenado.
Para chamar um procedimento, execute uma instrução SQL CALL que especifique o procedimento. Para obter mais informações, consulte Chamada de um procedimento armazenado.
Para criar um procedimento temporário que seja executado apenas uma vez e seja descartado, use WITH…CALL. Para obter mais informações, consulte CALL (com procedimento anônimo).