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. Alternativamente, você pode 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. Variáveis de vinculação podem evitar ataques de injeção SQL quando você constrói instruções SQL com entrada do usuário.

Você pode usar variáveis de vinculação das seguintes maneiras com o Snowflake:

Chamadas para APIs suportadas por drivers do Snowflake
Código de procedimento escrito em Script Snowflake
Aplicativos que usam REST API SQL Snowflake

Visão geral¶

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');

Copy

A seguinte instrução SQL usa espaços reservados para os valores inseridos:

INSERT INTO t (c1, c2) VALUES (?, ?);

Copy

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. Pode ser ?, :<varname> ou %<varname>.

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 Script Snowflake¶

Você pode usar o Script Snowflake para criar código de procedimento que executa SQL, como blocos de código e procedimentos armazenados. Preceda 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)

Copy

Para obter informações sobre como usar variáveis de vinculação no Script Snowflake, consulte Como usar uma variável em uma instrução SQL (vinculação).

Como usar variáveis de vinculação com SQL API¶

Você pode usar o REST API SQL 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 vincular matrizes de valores a variáveis¶

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)

Copy

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 para 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 (?,?), (?,?)
```
Copy

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 (?,?), (?,?);

Copy

Seu aplicativo pode especificar uma lista de vínculos 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 (?);

Copy

O exemplo a seguir consulta a tabela:

SELECT * FROM t;

Copy

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 (?);

Copy

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.