Variáveis SQL¶
Este tópico descreve como definir e usar variáveis SQL em sessões no Snowflake.
Neste tópico:
Visão geral¶
O Snowflake oferece suporte a variáveis SQL declaradas pelo usuário. Elas têm muitos usos, como o armazenamento de configurações de ambiente específicas de aplicativos.
Identificadores de variáveis¶
As variáveis SQL são identificadas globalmente usando nomes que não diferenciam maiúsculas e minúsculas.
DDL de variáveis¶
O Snowflake fornece os seguintes comandos DDL para usar as variáveis SQL:
Inicialização de variáveis¶
As variáveis podem ser definidas executando a instrução SQL SET ou definindo as variáveis na cadeia de caracteres de conexão quando você se conecta ao Snowflake.
O tamanho da cadeia de caracteres ou das variáveis binárias é limitado a 256 bytes.
Uso de SQL para inicializar variáveis em uma sessão¶
As variáveis podem ser inicializadas em SQL usando o comando SET. O tipo de dados da variável é derivado do tipo de dados do resultado da expressão avaliada.
SET MY_VARIABLE=10; SET MY_VARIABLE='example';
Múltiplas variáveis podem ser inicializadas na mesma instrução, reduzindo assim o número de comunicações de ida e volta com o servidor.
SET (VAR1, VAR2, VAR3)=(10, 20, 30); SET (VAR1, VAR2, VAR3)=(SELECT 10, 20, 30);
Definição de variáveis na conexão¶
Além de usar SET para definir variáveis dentro de uma sessão, as variáveis podem ser passadas como argumentos na cadeia de caracteres de conexão usada para inicializar uma sessão no Snowflake. Isso é especialmente útil quando se usa ferramentas em que a especificação da cadeia de caracteres de conexão é a única personalização possível.
Por exemplo, usando o driver Snowflake JDBC, você pode definir propriedades adicionais de conexão que serão interpretadas como parâmetros. Observe que a API JDBC requer que as variáveis SQL sejam cadeia de caracteres.
// build connection properties Properties properties = new Properties(); // Required connection properties properties.put("user" , "jsmith" ); properties.put("password", "mypassword"); properties.put("account" , "myaccount"); // Set some additional variables. properties.put("$variable_1", "some example"); properties.put("$variable_2", "1" ); // create a new connection String connectStr = "jdbc:snowflake://localhost:8080"; // Open a connection under the snowflake account and enable variable support Connection con = DriverManager.getConnection(connectStr, properties);
Uso de variáveis em SQL¶
Variáveis podem ser usadas no Snowflake em qualquer lugar onde uma constante literal seja permitida, exceto onde indicado na documentação. Para distingui-las dos valores de vinculação e nomes de colunas, todas as variáveis devem ser prefixadas com um sinal $.
Por exemplo:
SET (MIN, MAX)=(40, 70); SELECT $MIN; SELECT AVG(SALARY) FROM EMP WHERE AGE BETWEEN $MIN AND $MAX;
Nota
Como o sinal $ é o prefixo usado para identificar variáveis em instruções SQL, ele é tratado como um caractere especial quando usado em identificadores. Os identificadores (nomes de bancos de dados, nomes de tabelas, nomes de colunas etc.) não podem começar com caracteres especiais, a menos que o nome inteiro esteja entre aspas duplas. Para obter mais informações, consulte Identificadores de objetos.
As variáveis também podem conter nomes de identificadores, como nomes de tabelas. Para usar uma variável como identificador, você deve delimitá-la com IDENTIFIER(), por exemplo IDENTIFIER($MY_VARIABLE). Veja alguns exemplos abaixo:
CREATE TABLE IDENTIFIER($MY_TABLE_NAME) (i INTEGER); INSERT INTO IDENTIFIER($MY_TABLE_NAME) (i) VALUES (42);SELECT * FROM IDENTIFIER($MY_TABLE_NAME);DROP TABLE IDENTIFIER($MY_TABLE_NAME);
No contexto de uma cláusula FROM, você pode delimitar o nome da variável com TABLE(), como mostrado abaixo:
SELECT * FROM TABLE($MY_TABLE_NAME); +----+ | I | |----| | 42 | +----+
Para obter mais informações sobre IDENTIFIER(), consulte Literais e variáveis como identificadores.
Exibição das variáveis para a sessão¶
Para ver todas as variáveis definidas na sessão atual, use o comando SHOW VARIABLES:
SET (MIN, MAX)=(40, 70); +----------------------------------+ | status | |----------------------------------| | Statement executed successfully. | +----------------------------------+ SHOW VARIABLES; +-------------+---------------------------------+---------------------------------+------+-------+-------+---------+ | session_id | created_on | updated_on | name | value | type | comment | |-------------+---------------------------------+---------------------------------+------+-------+-------+---------| | 34359992326 | Fri, 21 Apr 2017 11:20:32 -0700 | Fri, 21 Apr 2017 11:20:32 -0700 | MAX | 70 | fixed | | | 34359992326 | Fri, 21 Apr 2017 11:20:32 -0700 | Fri, 21 Apr 2017 11:20:32 -0700 | MIN | 40 | fixed | | +-------------+---------------------------------+---------------------------------+------+-------+-------+---------+
Funções das variáveis de sessão¶
As seguintes funções de conveniência são fornecidas para manipulação de variáveis de sessão a fim de oferecer suporte à compatibilidade com outros sistemas de banco de dados e emitir SQL por meio de ferramentas que não aceitam a sintaxe $ para acessar variáveis. Note que todas essas funções aceitam e retornam valores de variáveis de sessão como cadeias de caracteres:
SYS_CONTEXT e SET_SYS_CONTEXT
SESSION_CONTEXT e SET_SESSION_CONTEXT
GETVARIABLE e SETVARIABLE
Aqui estão exemplos da utilização de GETVARIABLE. Primeiro, defina uma variável usando SET:
SET var_artist_name = 'Jackson Browne';+----------------------------------+ | status | +----------------------------------+ | Statement executed successfully. | +----------------------------------+
Retorne o valor da variável:
SELECT GETVARIABLE('var_artist_name');
Neste exemplo, a saída é NULL porque o Snowflake armazena variáveis com todas as letras maiúsculas.
Atualize o uso de letras maiúsculas e minúsculas:
SELECT GETVARIABLE('VAR_ARTIST_NAME');+--------------------------------+ | GETVARIABLE('VAR_ARTIST_NAME') | +--------------------------------+ | Jackson Browne | +--------------------------------+
Você pode usar o nome da variável em uma cláusula WHERE, por exemplo:
SELECT album_title FROM albums WHERE artist = $VAR_ARTIST_NAME;
Descarte/remoção de variáveis¶
Variáveis SQL são privadas para uma sessão. Quando uma sessão do Snowflake é encerrada, todas as variáveis criadas durante a sessão são descartadas. Isso significa que ninguém pode acessar variáveis definidas pelo usuário que tenham sido definidas em outra sessão, e quando a sessão é encerrada, essas variáveis expiram.
Além disso, as variáveis sempre podem ser explicitamente destruídas usando o comando UNSET.
Por exemplo:
UNSET MY_VARIABLE;