Variáveis de vinculação¶
Os aplicativos podem aceitar dados de usuários e usá-los em instruções SQL. Por exemplo, um aplicativo pode solicitar que um usuário insira informações de contato, como endereço e número de telefone.
Para especificar essa entrada do usuário em uma instrução SQL, você pode construir programaticamente uma cadeia de caracteres para a instrução SQL concatenando a entrada do usuário com as outras partes da instrução. Como alternativa, é possível usar variáveis de vinculação. Quando você usar variáveis de vinculação, coloque um ou mais espaços reservados no texto da instrução SQL e então especifique a variável (o valor a ser usado) para cada espaço reservado.
Visão geral das variáveis de vinculação¶
Com variáveis de vinculação, você substitui literais em instruções SQL por espaços reservados. Por exemplo, a instrução SQL a seguir usa literais para os valores inseridos:
INSERT INTO t (c1, c2) VALUES (1, 'Test string');
A seguinte instrução SQL usa espaços reservados para os valores inseridos:
INSERT INTO t (c1, c2) VALUES (?, ?);
O código do seu aplicativo vincula dados a cada espaço reservado na instrução SQL. A técnica para vincular dados a um espaço reservado depende da linguagem de programação. A sintaxe do espaço reservado também varia de acordo com a linguagem de programação. É ?, :varname ou %varname.
Como usar variáveis de vinculação em procedimentos armazenados em Javascript¶
É possível usar o Javascript para criar procedimentos armazenados que executam SQL.
Para especificar variáveis de vinculação no código Javascript, use espaços reservados ?. Por exemplo, a seguinte instrução INSERT especifica variáveis de vinculação para os valores inseridos em uma linha de tabela:
INSERT INTO t (col1, col2) VALUES (?, ?)
No código Javascript, é possível usar variáveis de vinculação para os valores na maioria das instruções SQL. Para obter informações sobre limitações, consulte Limitações para variáveis de vinculação.
Para obter mais informações sobre o uso de variáveis de vinculação em Javascript, consulte Variáveis de vinculação.
Como usar variáveis de vinculação com Script Snowflake¶
É possível usar o Snowflake Scripting para criar código de procedimento que execute SQL, como blocos de código e procedimentos armazenados. Para especificar variáveis de vinculação no código do Snowflake Scripting, prefixe o nome da variável com dois pontos. Por exemplo, a seguinte instrução INSERT especifica uma variável de vinculação chamada variable1:
INSERT INTO t (c1) VALUES (:variable1)
No código do Snowflake Scripting, é possível usar variáveis de vinculação para os valores na maioria das instruções SQL. Para obter informações sobre limitações, consulte Limitações para variáveis de vinculação.
Para obter mais informações sobre o uso de variáveis de vinculação no Snowflake Scripting, consulte Como usar uma variável em uma instrução SQL (vinculação) e Uso de um argumento em uma instrução SQL (vinculação).
Como usar variáveis de vinculação com SQL API¶
Você pode usar o API de SQL do Snowflake para acessar e atualizar os dados em um banco de dados do Snowflake. Você pode criar aplicativos que usam SQL API para enviar instruções SQL e gerenciar implantações.
Ao enviar uma solicitação que executa uma instrução SQL, você pode usar variáveis de vinculação para valores na instrução. Para obter mais informações, consulte Como usar variáveis de vinculação em uma instrução.
Como usar variáveis de vinculação com drivers¶
Usando drivers do Snowflake, você pode escrever aplicativos que executam operações no Snowflake. Os drivers suportam linguagens de programação como Go, Java e Python. Para obter informações sobre como usar variáveis de vinculação em um aplicativo para um driver específico, siga o link do driver:
Nota
O driver PHP não oferece suporte a variáveis de vinculação.
Como usar variáveis de vinculação com matrizes de valores¶
Você pode vincular uma matriz de valores a variáveis em instruções SQL. Usando essa técnica, você pode melhorar o desempenho inserindo diversas linhas em um único lote, o que evita compilações e viagens de ida e volta da rede. O uso de uma vinculação de matriz também é chamado de «inserção em massa» ou «inserção em lote».
Nota
Snowflake oferece suporte a outros métodos de carregamento de dados recomendados em vez de usar vinculações de matriz. Para obter mais informações, consulte Carregamento de dados para o Snowflake e Comandos de carregamento e descarregamento de dados.
A seguir está um exemplo de vinculação de matriz no código Python:
conn = snowflake.connector.connect( ... )
rows_to_insert = [('milk', 2), ('apple', 3), ('egg', 2)]
conn.cursor().executemany(
"insert into grocery (item, quantity) values (?, ?)",
rows_to_insert)
Este exemplo especifica a seguinte lista de vínculos: [('milk', 2), ('apple', 3), ('egg', 2)]. A maneira como um aplicativo especifica uma lista de vínculos depende da linguagem de programação.
Este código insere três linhas na tabela:
+-------+----+
| C1 | C2 |
|-------+----|
| milk | 2 |
| apple | 3 |
| egg | 2 |
+-------+----+
Para obter informações sobre como usar vinculações de matriz em um aplicativo para um driver específico, siga o link do driver:
Nota
O driver PHP não oferece suporte a vinculações de matriz.
Limitações do uso de vinculações de matriz¶
As seguintes limitações se aplicam a vinculações de matriz:
Somente instruções INSERT INTO … VALUES podem conter variáveis de vinculação de matriz.
A cláusula VALUES deve ser uma lista de variáveis de vinculação de linha única. Por exemplo, a seguinte cláusula VALUES não é permitida:
VALUES (?,?), (?,?)
Como inserir múltiplas linhas sem usar vinculações de matriz¶
Uma instrução INSERT pode usar variáveis de vinculação para inserir diversas linhas sem usar uma vinculação de matriz. O exemplo a seguir insere valores em duas linhas, mas não usa uma vinculação de matriz.
INSERT INTO t VALUES (?,?), (?,?);
Por exemplo, seu aplicativo pode especificar uma lista de vinculação que seja equivalente aos seguintes valores, em ordem, para os espaços reservados: [1,'String1',2,'String2']. Como a cláusula VALUES especifica mais de uma linha, a instrução insere apenas o número exato de valores (quatro no exemplo), em vez de um número dinâmico de linhas.
Como usar variáveis de vinculação com dados semiestruturados¶
Para vincular variáveis a dados semiestruturados, vincule a variável como um tipo de cadeia de caracteres e use funções como PARSE_JSON ou ARRAY_CONSTRUCT.
O exemplo a seguir cria uma tabela com uma coluna VARIANT e depois chama a função PARSE_JSON para inserir dados semiestruturados na tabela com uma variável de vinculação:
CREATE TABLE t (a VARIANT);
-- Code that supplies a bind value for ? of '{'a': 'abc', 'x': 'xyz'}'
INSERT INTO t SELECT PARSE_JSON(a) FROM VALUES (?);
O exemplo a seguir consulta a tabela:
SELECT * FROM t;
A consulta retorna a seguinte saída:
+---------------+
| A |
|---------------|
| { |
| "a": "abc", |
| "x": "xyz" |
| } |
+---------------+
A instrução a seguir chama a função ARRAY_CONSTRUCT para inserir uma matriz de dados semiestruturados em uma coluna VARIANT com uma variável de vinculação:
INSERT INTO t SELECT ARRAY_CONSTRUCT(column1) FROM VALUES (?);
Ambos os exemplos podem inserir uma única linha ou podem usar uma vinculação de matriz para inserir várias linhas em um lote. Você pode usar esta técnica para inserir qualquer tipo de dado semiestruturado válido em uma coluna VARIANT.
Limitações para variáveis de vinculação¶
As seguintes limitações se aplicam às variáveis de vinculação:
Limitações para as instruções SELECT:
As variáveis de vinculação não podem substituir números que fazem parte de uma definição de tipo de dados (por exemplo,
NUMBER(?)) ou da especificação de agrupamento (por exemplo,COLLATE ?).As variáveis de vinculação não podem ser usadas para a fonte em uma instrução SELECT que consulta arquivos em um estágio.
Limitações dos comandos da DDL:
As variáveis de vinculação não podem ser usadas nos seguintes comandos da DDL:
CREATE/ALTER INTEGRATION
CREATE/ALTER REPLICATION GROUP
CREATE/ALTER PIPE
CREATE TABLE … USING TEMPLATE
As variáveis de vinculação não podem ser usadas nas cláusulas a seguir:
ALTER COLUMN
COMMENT ON CONSTRAINT
Nos comandos CREATE/ALTER, as variáveis de vinculação não podem ser usadas para os valores dos seguintes parâmetros:
CREDENTIALS
DIRECTORY
ENCRYPTION
IMPORTS
PACKAGES
REFRESH
TAG
Parâmetros específicos de tabelas externas
As variáveis de vinculação não podem ser usadas para propriedades que fazem parte de um valor FILE FORMAT.
Nos comandos COPY INTO, as variáveis de vinculação não podem ser usadas para os valores dos seguintes parâmetros:
CREDENTIALS
ENCRYPTION
FILE_FORMAT
Nos comandos SHOW, as variáveis de vinculação não podem ser usadas nos seguintes parâmetros:
LIKE
LIMIT
STARTS WITH
As variáveis de vinculação não podem ser usadas em um comando EXECUTE IMMEDIATE FROM.
Os valores das variáveis de vinculação não podem ser convertidos automaticamente de um tipo de dados para outro quando as variáveis de vinculação são usadas:
Código do Snowflake Scripting que especifica explicitamente o tipo de dados
Instruções DDL
Nomes de estágio
Considerações de segurança para variáveis de vinculação¶
As variáveis de vinculação não mascaram dados confidenciais em todos os casos. Por exemplo, os valores das variáveis de vinculação podem aparecer em mensagens de erro e outros artefatos.
As variáveis de vinculação podem ajudar a evitar ataques de injeção de SQL quando você constrói instruções SQL com a entrada do usuário. No entanto, as variáveis de vinculação podem apresentar riscos potenciais à segurança. Se as entradas nas instruções SQL vierem de fontes externas, certifique-se de que elas sejam validadas. Para obter mais informações, consulte Injeção de SQL.