Variables de liaison¶

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 :

• Go

• JDBC

• .NET

• Node.js

• ODBC

• Python

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 ».

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 :

• Go

• JDBC

• .NET

• Node.js

• ODBC

• Python

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

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.