Variables de liaison¶
Les applications peuvent accepter des données de la part des utilisateurs et les utiliser dans des instructions SQL. Par exemple, une application peut demander à un utilisateur de saisir des informations de contact, comme une adresse et un numéro de téléphone.
Pour spécifier cette entrée utilisateur dans une instruction SQL, vous pouvez construire par programme une chaîne pour l’instruction SQL en concaténant l’entrée utilisateur avec les autres parties de l’instruction. Vous pouvez également utiliser les variables de liaison. Pour lier des variables de liaison, insérez un ou plusieurs caractères de remplacement dans le texte de l’instruction SQL, puis spécifiez la variable (la valeur à utiliser) pour chaque caractère de remplacement.
Aperçu des variables de liaison¶
Avec les variables de liaison, vous remplacez les valeurs littérales des instructions SQL par des caractères de remplacement. Par exemple, l’instruction SQL suivante utilise des littéraux pour les valeurs insérées :
INSERT INTO t (c1, c2) VALUES (1, 'Test string');
L’instruction SQL suivante utilise des caractères de remplacement pour les valeurs insérées :
INSERT INTO t (c1, c2) VALUES (?, ?);
Votre code d’application lie les données à chaque caractère de remplacement dans l’instruction SQL. La technique de liaison des données avec un caractère de remplacement dépend du langage de programmation. La syntaxe du caractère de remplacement varie également en fonction du langage de programmation. Soit ?
, :varname
ou %varname
.
Utilisation de variables de liaison dans les procédures stockées Javascript¶
Vous pouvez utiliser Javascript pour créer des procédures stockées qui exécutent SQL.
Pour spécifier des variables de liaison dans le code Javascript, utilisez des caractères de remplacement ?
. Par exemple, l’instruction INSERT suivante spécifie des variables de liaison pour les valeurs insérées dans la ligne d’une table :
INSERT INTO t (col1, col2) VALUES (?, ?)
Dans le code Javascript, vous pouvez utiliser des variables de liaison pour les valeurs de la plupart des instructions SQL. Pour des informations sur les limites, voir Limites relatives aux variables de liaison.
Pour plus d’informations sur l’utilisation des variables de liaison en Javascript, voir Variables de liaison.
Utilisation de variables de liaison avec l’exécution de scripts Snowflake¶
Vous pouvez utiliser Snowflake Scripting pour créer du code procédural qui exécute SQL, comme les blocs de code et les procédures stockées. Pour spécifier des variables de liaison dans le code Snowflake Scripting, faites précéder le nom de la variable d’un deux-points. Par exemple, l’instruction INSERT suivante spécifie une variable de liaison nommée variable1
:
INSERT INTO t (c1) VALUES (:variable1)
Dans le code Snowflake Scripting, vous pouvez utiliser des variables de liaison pour les valeurs de la plupart des instructions SQL. Pour des informations sur les limites, voir Limites relatives aux variables de liaison.
Pour plus d’informations sur l’utilisation des variables de liaison dans Snowflake Scripting, voir Utiliser une variable dans une instruction SQL (liaison) et Utilisation d’un argument dans une instruction SQL (liaison).
Utilisation de variables de liaison avec l’API SQL¶
Vous pouvez utiliser l” API SQL Snowflake pour accéder aux données d’une base de données Snowflake et les mettre à jour. Vous pouvez créer des applications qui utilisent l’API SQL pour soumettre des instructions SQL et gérer des déploiements.
Lorsque vous soumettez une requête qui exécute une instruction SQL, vous pouvez utiliser des variables de liaison pour les valeurs de l’instruction. Pour plus d’informations, voir Utilisation de variables de liaison dans une instruction.
Utilisation de variables de liaison avec des pilotes¶
En utilisant des pilotes Snowflake, vous pouvez écrire des applications qui effectuent des opérations sur Snowflake. Les pilotes prennent en charge des langages de programmation tels que Go, Java et Python. Pour plus d’informations sur l’utilisation des variables de liaison dans une application pour un pilote spécifique, suivez le lien correspondant au pilote :
Note
Le pilote PHP ne prend pas en charge les variables de liaison.
Utilisation de variables de liaison avec des tableaux de valeurs¶
Vous pouvez lier un tableau de valeurs à des variables dans des instructions SQL. Cette technique permet d’améliorer les performances en insérant plusieurs lignes en un seul lot, ce qui évite les allers-retours sur le réseau et les compilations. L’utilisation d’une liaison de tableaux est également appelée « insertion en masse » ou « insertion par lots ».
Note
Snowflake prend en charge d’autres méthodes de chargement de données qui sont recommandées au lieu d’utiliser des liaisons de tableaux. Pour plus d’informations, voir Charger des données dans Snowflake et Commandes de chargement et de déchargement des données.
Voici un exemple de liaison de tableaux en code 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)
Cet exemple spécifie la liste de liaisons suivantes : [('milk', 2), ('apple', 3), ('egg', 2)]
. La manière dont une application spécifie une liste de liaisons dépend du langage de programmation.
Ce code insère trois lignes dans le tableau :
+-------+----+
| C1 | C2 |
|-------+----|
| milk | 2 |
| apple | 3 |
| egg | 2 |
+-------+----+
Pour plus d’informations sur l’utilisation des liaisons de tableaux dans une application pour un pilote spécifique, suivez le lien correspondant au pilote :
Note
Le pilote PHP ne prend pas en charge les liaisons de tableaux.
Limitations relatives à l’utilisation de liaisons de tableaux¶
Les limitations suivantes s’appliquent aux liaisons de tableaux :
Seules les instructions INSERT INTO … VALUES peuvent contenir des variables de liaison de tableaux.
La clause VALUES doit être une liste à une seule ligne de variables de liaison. Par exemple, la clause VALUES suivante n’est pas autorisée :
VALUES (?,?), (?,?)
Insertion de plusieurs lignes sans utiliser de liaisons de tableaux¶
Une instruction INSERT peut utiliser des variables de liaison pour insérer plusieurs lignes sans utiliser de liaison de tableau. L’exemple suivant insère des valeurs dans deux lignes, mais sans utiliser de liaison de tableau.
INSERT INTO t VALUES (?,?), (?,?);
Par exemple, votre application peut spécifier une liste de liaison équivalente aux valeurs suivantes, dans l’ordre, pour les caractères de remplacement : [1,'String1',2,'String2']
. Comme la clause VALUES spécifie plus d’une ligne, l’instruction n’insère que le nombre exact de valeurs (quatre dans l’exemple), plutôt qu’un nombre dynamique de lignes.
Utilisation de variables de liaison avec des données semi-structurées¶
Pour lier des variables avec des données semi-structurées, liez la variable en tant que type de chaîne et utilisez des fonctions telles que PARSE_JSON ou ARRAY_CONSTRUCT.
L’exemple suivant crée une table avec une colonne VARIANT, puis appelle la fonction PARSE_JSON pour insérer des données semi-structurées dans la table à l’aide d’une variable de liaison :
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 (?);
L’exemple suivant interroge la table :
SELECT * FROM t;
La requête renvoie le résultat suivant :
+---------------+
| A |
|---------------|
| { |
| "a": "abc", |
| "x": "xyz" |
| } |
+---------------+
L’instruction suivante appelle la fonction ARRAY_CONSTRUCT pour insérer un tableau de données semi-structurées dans une colonne VARIANT avec une variable de liaison :
INSERT INTO t SELECT ARRAY_CONSTRUCT(column1) FROM VALUES (?);
Ces deux exemples peuvent insérer une seule ligne ou utiliser une liaison de tableaux pour insérer plusieurs lignes en une seule fois. Vous pouvez utiliser cette technique pour insérer n’importe quel type de données semi-structurées valides dans une colonne VARIANT.
Limites relatives aux variables de liaison¶
Les limites suivantes s’appliquent aux variables de liaison :
Limites relatives aux instructions SELECT :
Les variables de liaison ne peuvent pas remplacer les nombres qui font partie de la définition d’un type de données (par exemple,
NUMBER(?)
) ou spécification de classement (par exemple,COLLATE ?
).Les variables de liaison ne peuvent pas être utilisées comme source dans une instruction SELECT qui interroge des fichiers sur une zone de préparation interne.
Limites relatives aux commandes DDL :
Les variables de liaison ne peuvent pas être utilisées dans les commandes DDL suivantes :
CREATE/ALTER INTEGRATION
CREATE/ALTER REPLICATION GROUP
CREATE/ALTER PIPE
CREATE TABLE … USING TEMPLATE
Les variables de liaison ne peuvent pas être utilisées dans les clauses suivantes :
ALTER COLUMN
COMMENT ON CONSTRAINT
Dans les commandes CREATE/ALTER, les variables de liaison ne peuvent pas être utilisées pour les valeurs des paramètres suivants :
CREDENTIALS
DIRECTORY
ENCRYPTION
IMPORTS
PACKAGES
REFRESH
TAG
Paramètres spécifiques aux tables externes
Les variables de liaison ne peuvent pas être utilisées pour les propriétés qui font partie d’une valeur FILE FORMAT.
Dans les commandes COPY INTO, les variables de liaison ne peuvent pas être utilisées pour les valeurs des paramètres suivants :
CREDENTIALS
ENCRYPTION
FILE_FORMAT
Dans les commandes SHOW, les variables de liaison ne peuvent pas être utilisées dans les paramètres suivants :
LIKE
LIMIT
STARTS WITH
Les variables de liaison ne peuvent pas être utilisées dans une commande EXECUTE IMMEDIATE FROM.
Les valeurs des variables de liaison ne peuvent pas être converties automatiquement d’un type de données à un autre lorsque les variables de liaison sont utilisées dans ce qui suit :
Code Snowflake Scripting qui spécifie explicitement le type de données
Instructions DDL
Noms de zones de préparation
Considérations de sécurité pour les variables de liaison¶
Les variables de liaison ne masquent pas les données sensibles dans tous les cas. Par exemple, les valeurs des variables de liaison peuvent apparaître dans les messages d’erreur et autres artefacts.
Les variables de liaison peuvent empêcher les attaques par injection SQL lorsque vous construisez des instructions SQL avec une entrée de l’utilisateur. Cependant, les variables de liaison peuvent présenter des risques potentiels pour la sécurité. Si les entrées effectuées dans les instructions SQL proviennent de sources externes, assurez-vous qu’elles sont validées. Pour plus d’informations, voir injection SQL.