EXECUTE IMMEDIATE FROM¶

EXECUTE IMMEDIATE FROM executa as instruções SQL especificadas em um arquivo em um estágio. O arquivo pode conter instruções SQL ou blocos do Script Snowflake. As instruções devem ser instruções SQL sintaticamente corretas.

Você pode usar o comando EXECUTE IMMEDIATE FROM para executar as instruções em um arquivo de qualquer sessão do Snowflake.

Esse recurso fornece um mecanismo para controlar a implantação e o gerenciamento de objetos e códigos do Snowflake. Por exemplo, você pode executar um script armazenado para criar um ambiente Snowflake padrão para todas as suas contas. O script de configuração pode incluir instruções que criam usuários, funções, bancos de dados e esquemas para cada nova conta.

Criação de modelos Jinja2¶

EXECUTE IMMEDIATE FROM também pode executar um arquivo de modelo usando a linguagem de modelos Jinja2. Um modelo pode conter variáveis e expressões, permitindo o uso de loops, condicionais, substituição de variáveis, macros e muito mais.

Para obter mais informações sobre a linguagem de modelagem, consulte a Documentação do Jinja2.

O arquivo de modelo a ser executado deve ser:

Um modelo Jinja2 sintaticamente válido.
Localizado em um estágio ou repositório Git.
Capaz de processar instruções SQL sintaticamente válidas.

A criação de modelos permite estruturas de controle e parametrização mais flexíveis usando variáveis de ambiente. Por exemplo, você pode usar um modelo para escolher dinamicamente o destino de implantação dos objetos definidos no script. Para usar um modelo para renderizar um script SQL, use a diretriz de modelagem ou adicione uma cláusula USING com pelo menos uma variável de modelo.

Diretriz de modelagem¶

Você pode usar qualquer uma das duas diretrizes de modelagem.

A diretriz recomendada usa a sintaxe SQL válida:

--!jinja

Copy

Opcionalmente, você pode usar a diretriz alternativa:

#!jinja

Copy

Nota

Somente uma marca de ordem de bytes e até 10 caracteres de espaço em branco (novas linhas, tabulações, espaços) podem ser colocados antes da diretriz. Quaisquer caracteres que vierem depois da diretriz na mesma linha serão ignorados.

Consulte também:: EXECUTE IMMEDIATE

Sintaxe¶

EXECUTE IMMEDIATE
  FROM { absoluteFilePath | relativeFilePath }
  [ USING ( <key> => <value> [ , <key> => <value> [ , ... ] ]  )  ]

Copy

Onde:

absoluteFilePath ::=
   @[ <namespace>. ]<stage_name>/<path>/<filename>

Copy

relativeFilePath ::=
  '[ / | ./ | ../ ]<path>/<filename>'

Copy

Parâmetros obrigatórios¶

Caminho absoluto do arquivo (`absoluteFilePath`)¶

namespace: Banco de dados e/ou esquema no qual está o estágio interno ou externo, na forma de database_name.schema_name ou schema_name. O namespace é opcional se um banco de dados e esquema estiverem em uso atualmente para a sessão do usuário; caso contrário, ele é obrigatório.
stage_name: Nome do estágio interno ou externo.
path: Caminho que diferencia maiúsculas de minúsculas para o arquivo no estágio.
filename: Nome do arquivo a ser executado. Deve conter instruções SQL sintaticamente corretas e válidas. Cada instrução deve ser separada por ponto e vírgula.

Caminho relativo do arquivo (`relativeFilePath`)¶

path: Caminho relativo que diferencia maiúsculas de minúsculas para o arquivo no estágio. Caminhos relativos oferecem suporte a convenções estabelecidas, como um / inicial para indicar a raiz do sistema de arquivos de um estágio, ./ para se referir ao diretório atual (o diretório no qual o arquivo pai está localizado) e ../ para se referir ao diretório pai. Para obter mais informações, consulte Notas de uso.
filename: Nome do arquivo a ser executado. Deve conter instruções SQL sintaticamente corretas e válidas. Cada instrução deve ser separada por ponto e vírgula.

Parâmetros opcionais¶

USING ( <key> => <value> [ , <key> => <value> [ , ... ] ] )

Permite que você passe um ou mais pares chave-valor que podem ser usados para parametrizar a expansão do modelo. Os pares chave-valor devem formar uma lista separada por vírgulas.

Quando a cláusula USING está presente, o arquivo é primeiro renderizado como um modelo Jinja2 antes de ser executado como um script SQL.

Onde:

key é o nome da variável do modelo. O nome da variável do modelo pode, opcionalmente, ser colocado entre aspas duplas (").

value é o valor a ser atribuído à variável no modelo. Os valores da cadeia de caracteres devem ser colocados entre ' ou $$. Para um exemplo, veja Notas de uso de modelagem.

Retornos¶

EXECUTE IMMEDIATE FROM retorna:

O resultado da última instrução no arquivo se todas as instruções forem executadas com sucesso.
A mensagem de erro, se alguma instrução no arquivo falhar.

Se houver um erro em qualquer instrução do arquivo, o comando EXECUTE IMMEDIATE FROM falhará e retornará a mensagem de erro da instrução com falha.

Nota

Se o comando EXECUTE IMMEDIATE FROM falhar e retornar uma mensagem de erro, todas as instruções no arquivo anteriores à instrução com falha foram concluídas com êxito.

Requisitos de controle de acesso¶

A função usada para executar o comando EXECUTE IMMEDIATE FROM deve ter o privilégio USAGE (estágio externo) ou READ (estágio interno) no estágio onde o arquivo está localizado.

A função usada para executar o arquivo só pode executar as instruções do arquivo para as quais possui privilégios. Por exemplo, se houver uma instrução CREATE TABLE no arquivo, a função deverá ter os privilégios necessários para criar uma tabela na conta ou a instrução falhará.

Observe que operar em qualquer objeto de um esquema também requer o privilégio USAGE no banco de dados e esquema principais.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Notas de uso¶

As instruções SQL em um arquivo a ser executado podem incluir instruções EXECUTE IMMEDIATE FROM:
- Instruções EXECUTE IMMEDIATE FROM aninhadas podem usar caminhos de arquivo relativos.
  
  Os caminhos relativos são avaliados em relação ao estágio e ao caminho do arquivo pai. Se o caminho relativo do arquivo começar com /, o caminho começará no diretório raiz do estágio que contém o arquivo pai.
  
  Para obter um exemplo, consulte Exemplos.
- Caminhos de arquivos relativos devem obrigatoriamente ser colocados entre aspas simples (') ou $$.
- A profundidade máxima de execução para arquivos aninhados é 5.
Caminhos de arquivo absolutos podem opcionalmente ser colocados entre aspas simples (') ou $$.
O arquivo a ser executado não pode ter tamanho maior que 10MB.
O arquivo a ser executado deve estar codificado em UTF-8.
O arquivo a ser executado deve estar descompactado. Se você usar o comando PUT para carregar um arquivo para um estágio interno, deverá definir explicitamente o parâmetro AUTO_COMPRESS como FALSE.

Por exemplo, carregue my_file.sql para my_stage:
```
PUT file://~/sql/scripts/my_file.sql @my_stage/scripts/
  AUTO_COMPRESS=FALSE;
```
Copy
A execução de todos os arquivos em um diretório não é suportada. Por exemplo, EXECUTE IMMEDIATE FROM @stage_name/scripts/ resulta em um erro.

Notas de uso de modelagem¶

Nomes de variáveis em modelos diferenciam maiúsculas de minúsculas.
O nome da variável do modelo pode ser opcionalmente colocado entre aspas duplas. Incluir o nome da variável pode ser útil se alguma palavras-chave reservada for usada como nome de variáveis.
Os seguintes tipos de parâmetros são suportados na cláusula USING:
- Cadeia de caracteres. Deve ser incluído por ' ou $$. Por exemplo, USING (a => 'a', b => $$b$$).
- Número (decimal e inteiro). Por exemplo, USING (a => 1, b => -1.23).
- Booleano. Por exemplo, USING (a => TRUE, b => FALSE).
- NULL. Por exemplo, USING (a => NULL).
  
  Nota
  
  O mecanismo de modelagem Jinja2 interpreta um valor NULL como o tipo NoneType de Python.
- Variáveis de sessão. Por exemplo, USING (a => $var). Somente variáveis de sessão que contenham valores de tipos de dados suportados são permitidas.
- Variáveis de vinculação. Por exemplo, USING (a => :var). Somente variáveis de vinculação que contenham valores de tipos de dados suportados são permitidas. Você pode usar variáveis de vinculação para passar argumentos de procedimento armazenado para um modelo.
O tamanho máximo do resultado para renderização do modelo é 100.000 bytes.
Os modelos são renderizados usando o mecanismo de criação de modelos Jinja2 versão 3.1.2.

Solução de problemas de EXECUTE IMMEDIATE FROM¶

Esta seção contém alguns erros comuns que resultam de uma instrução EXECUTE IMMEDIATE FROM e como você pode resolvê-los.

Erros de arquivo
Erros de estágio
Erros de controle de acesso
Erros de modelagem

Erros de arquivo¶

Erro	001501 (02000): File '<directory_name>' not found in stage '<stage_name>'.
Causa	Existem várias causas para este erro: O arquivo não existe. O nome do arquivo é a raiz de um diretório. Por exemplo `@stage_name/scripts/`.
Solução	Verifique o nome do arquivo e confirme se ele existe. A execução de todos os arquivos em um diretório não é suportada.

Erro

001501 (02000): File '<directory_name>' not found in stage '<stage_name>'.

Causa

Existem várias causas para este erro:

O arquivo não existe.
O nome do arquivo é a raiz de um diretório. Por exemplo @stage_name/scripts/.

Solução

Verifique o nome do arquivo e confirme se ele existe. A execução de todos os arquivos em um diretório não é suportada.

Erro	001503 (42601): Relative file references like '<filename.sql>' cannot be used in top-level EXECUTE IMMEDIATE calls.
Causa	A instrução foi executada usando um caminho de arquivo relativo fora de uma execução de arquivo.
Solução	Um caminho de arquivo relativo só pode ser usado em instruções EXECUTE IMMEDIATE FROM em um arquivo. Use o caminho absoluto do arquivo para o arquivo. Para obter mais informações, consulte Notas de uso.

Erro	001003 (42000): SQL compilation error: syntax error line <n> at position <m> unexpected '<string>'.
Causa	O arquivo contém erros de sintaxe SQL.
Solução	Corrija os erros de sintaxe no arquivo e reenvie o arquivo para o estágio.

Erros de estágio¶

Erro	002003 (02000): SQL compilation error: Stage '<stage_name>' does not exist or not authorized.
Causa	O estágio não existe ou você não tem acesso ao estágio.
Solução	Verifique o nome do estágio e confirme se ele existe. Execute a instrução usando uma função que tenha os privilégios necessários para acessar o estágio. Para obter mais informações, consulte Requisitos de controle de acesso.

Erros de controle de acesso¶

Erro	003001 (42501): Uncaught exception of type 'STATEMENT_ERROR' in file <file_name> on line <n> at position <m>: SQL access control error: Insufficient privileges to operate on schema '<schema_name>'
Causa	A função usada para executar a instrução não possui os privilégios necessários para executar algumas ou todas as instruções no arquivo.
Solução	Use uma função que tenha os privilégios apropriados para executar as instruções no arquivo. Para obter mais informações, consulte Requisitos de controle de acesso.

Consulte também: Erros de estágio.

Erros de modelagem¶

Erro	001003 (42000): SQL compilation error: syntax error line [n] at position [m] unexpected '{'.
Causa	O arquivo contém construções de modelos (por exemplo, `{{ table_name }}`) mas não é renderizado usando o mecanismo de modelagem. Se o modelo não for renderizado, as linhas de texto no modelo serão executadas como instruções SQL. As construções de modelos no arquivo provavelmente resultarão em erros de sintaxe de SQL.
Solução	Adicione uma diretriz de modelagem ou reexecute a instrução com a cláusula USING e especifique pelo menos uma variável de modelo.

Erro	000005 (XX000): Python Interpreter Error: jinja2.exceptions.UndefinedError: '<key>' is undefined in template processing
Causa	Se alguma variável usada no modelo for deixada sem especificação na cláusula USING, ocorre um erro.
Solução	Verifique os nomes e o número de variáveis no modelo e atualize a cláusula USING para incluir valores para todas as variáveis de modelo.

Erro	001510 (42601): Unable to use value of template variable '<key>'
Causa	O valor da variável `key` é um tipo não suportado.
Solução	Verifique se você está usando um tipo de parâmetro suportado para o valor da variável de modelo. Para obter mais informações, consulte o Notas de uso de modelagem.

Erro	001518 (42601): Size of expanded template exceeds limit of 100,000 bytes.
Causa	O tamanho do modelo renderizado excede o limite atual.
Solução	Divida seu arquivo de modelo em vários modelos menores e adicione um novo script para executá-los sequencialmente, enquanto passa variáveis de modelo aos scripts aninhados.

Exemplos¶

Exemplo básico¶

Este exemplo executa o arquivo create-inventory.sql localizado no estágio my_stage.

Crie um arquivo denominado create-inventory.sql com as seguintes instruções:

CREATE OR REPLACE TABLE my_inventory(
  sku VARCHAR,
  price NUMBER
);

EXECUTE IMMEDIATE FROM './insert-inventory.sql';

SELECT sku, price
  FROM my_inventory
  ORDER BY price DESC;

Copy

Crie um arquivo denominado insert-inventory.sql com as seguintes instruções:

INSERT INTO my_inventory
  VALUES ('XYZ12345', 10.00),
         ('XYZ81974', 50.00),
         ('XYZ34985', 30.00),
         ('XYZ15324', 15.00);

Copy

Crie um estágio interno my_stage:
```
CREATE STAGE my_stage;
```
Copy

Carregue dois arquivos locais para o estágio usando o comando PUT:

PUT file://~/sql/scripts/create-inventory.sql @my_stage/scripts/
  AUTO_COMPRESS=FALSE;

PUT file://~/sql/scripts/insert-inventory.sql @my_stage/scripts/
  AUTO_COMPRESS=FALSE;

Copy

Execute o script create-inventory.sql localizado em my_stage:

EXECUTE IMMEDIATE FROM @my_stage/scripts/create-inventory.sql;

Copy

Retorna:

+----------+-------+
| SKU      | PRICE |
|----------+-------|
| XYZ81974 |    50 |
| XYZ34985 |    30 |
| XYZ15324 |    15 |
| XYZ12345 |    10 |
+----------+-------+

Um exemplo de modelo simples¶

Crie um arquivo de modelo setup.sql com duas variáveis e a diretriz de modelagem:

--!jinja

CREATE SCHEMA {{env}};

CREATE TABLE RAW (COL OBJECT)
    DATA_RETENTION_TIME_IN_DAYS = {{retention_time}};

Copy

Crie um estágio — opcional se você já tiver um estágio para o qual possa enviar arquivos.

Por exemplo, crie um estágio interno no Snowflake:
```
CREATE STAGE my_stage;
```
Copy
Carregue o arquivo em seu estágio.

Por exemplo, use o comando PUT do seu ambiente local para fazer upload do arquivo setup.sql para o estágio my_stage:
```
PUT file://path/to/setup.sql @my_stage/scripts/
  AUTO_COMPRESS=FALSE;
```
Copy

Execute o arquivo setup.sql:

EXECUTE IMMEDIATE FROM @my_stage/scripts/setup.sql
    USING (env=>'dev', retention_time=>0);

Copy

Um exemplo de modelo com um condicional e um loop¶

Crie um arquivo de modelo e inclua a diretriz do modelo.

Por exemplo, crie um arquivo setup-env.sql no seu ambiente local:

--!jinja2

{% if DEPLOYMENT_TYPE == 'prod' %}
  {% set environments = ['prod1', 'prod2'] %}
{% else %}
  {% set environments = ['dev', 'qa', 'staging'] %}
{% endif %}

{% for environment in environments %}
  CREATE DATABASE {{ environment }}_db;
  USE DATABASE {{ environment }}_db;
  CREATE TABLE {{ environment }}_orders (
    id NUMBER,
    item VARCHAR,
    quantity NUMBER);
  CREATE TABLE {{ environment }}_customers (
    id NUMBER,
    name VARCHAR);
{% endfor %}

Copy

Crie um estágio — opcional se você já tiver um estágio para o qual possa enviar arquivos.

Por exemplo, crie um estágio interno no Snowflake:
```
CREATE STAGE my_stage;
```
Copy
Carregue o arquivo em seu estágio.

Por exemplo, use o comando PUT do seu ambiente local para fazer upload do arquivo setup-env.sql para o estágio my_stage:
```
PUT file://path/to/setup-env.sql @my_stage/scripts/
  AUTO_COMPRESS=FALSE;
```
Copy

Execute o arquivo setup-env.sql:

EXECUTE IMMEDIATE FROM @my_stage/scripts/setup-env.sql
  USING (DEPLOYMENT_TYPE => 'staging');

Copy

EXECUTE IMMEDIATE FROM¶

Criação de modelos Jinja2¶

Diretriz de modelagem¶

Sintaxe¶

Parâmetros obrigatórios¶

Caminho absoluto do arquivo (absoluteFilePath)¶

Caminho relativo do arquivo (relativeFilePath)¶

Parâmetros opcionais¶

Retornos¶

Requisitos de controle de acesso¶

Notas de uso¶

Notas de uso de modelagem¶

Solução de problemas de EXECUTE IMMEDIATE FROM¶

Erros de arquivo¶

Erros de estágio¶

Erros de controle de acesso¶

Erros de modelagem¶

Exemplos¶

Exemplo básico¶

Um exemplo de modelo simples¶

Um exemplo de modelo com um condicional e um loop¶

Caminho absoluto do arquivo (`absoluteFilePath`)¶

Caminho relativo do arquivo (`relativeFilePath`)¶