Marqueurs de paramètres

  • Article

Les marqueurs de paramètres sont nommés ou ne sont pas nommés des variables d’espace réservé typées utilisées pour fournir des valeurs à partir de l’API appelant l’instruction SQL.

L’utilisation de marqueurs de paramètres protège votre code contre les attaques par injection SQL, car elle sépare clairement les valeurs fournies des instructions SQL.

Vous ne pouvez pas combiner les marqueurs de paramètres nommés et non nommés dans la même instruction SQL.

Vous ne devez pas référencer un marqueur de paramètre dans une instruction de langage de description de données (DDL), telle qu’une colonne générée ou une définition DEFAULT, une vue ou une fonction SQL.

Les exceptions sont des références aux marqueurs de paramètres dans la clause IDENTIFIER, qui peuvent être utilisées pour paramétrer des noms de table ou de colonnes dans certaines instructions DDL. Voir la clause IDENTIFIER.

Les marqueurs de paramètres peuvent être fournis par :

Marqueurs de paramètres nommés

S’applique à : Databricks Runtime check marked yes 12.1 et versions ultérieures

Les marqueurs de paramètres nommés sont des variables d’espace réservé typées. L’API appelant l’instruction SQL doit fournir des paires nom-valeur pour associer chaque marqueur de paramètre à une valeur.

Syntaxe

 :parameter_name

Paramètres

  • named_parameter_name

    Référence à un marqueur de paramètre fourni sous forme d’identificateur non qualifié.

Notes

Vous pouvez référencer le même marqueur de paramètre plusieurs fois dans la même instruction SQL. Si aucune valeur n’a été liée au marqueur de paramètre, une erreur UNBOUND_SQL_PARAMETER est générée. Vous n’êtes pas obligé de référencer tous les marqueurs de paramètres fournis.

Le : (deux-points) précédent obligatoire différencie l’espace de noms des marqueurs de paramètres nommés de celui des noms de colonnes et des paramètres SQL.

Exemples

L’exemple suivant est une définition de deux marqueurs de paramètres :

  • ultérieure : un INTERVAL HOUR avec la valeur 3.
  • x : un DOUBLE avec la valeur 15.0

x est référencé plusieurs fois, tandis que later est référencé une seule fois.

SQL

> DECLARE stmtStr = 'SELECT current_timestamp() + :later, :x * :x AS square';
> EXECUTE IMMEDIATE stmtStr USING INTERVAL '3' HOURS AS later, 15.0 AS x;
  2024-01-19 16:17:16.692303  225.00

Scala

import org.apache.spark.sql.SparkSession

val spark = SparkSession
  .builder()
  .appName("Spark named parameter marker example")
  .getOrCreate()

val argMap = Map("later" -> java.time.Duration.ofHours(3), "x" -> 15.0)
spark.sql(
  sqlText = "SELECT current_timestamp() + :later, :x * :x AS square",
  args = argMap).show()
// +----------------------------------------+------+
// |current_timestamp() + INTERVAL '03' HOUR|square|
// +----------------------------------------+------+
// |                    2023-02-27 17:48:...|225.00|
// +----------------------------------------+------+

Java

import org.apache.spark.sql.*;
import static java.util.Map.entry;

SparkSession spark = SparkSession
  .builder()
  .appName("Java Spark named parameter marker example")
  .getOrCreate();

Map<String, String> argMap = Map.ofEntries(
  entry("later", java.time.Duration.ofHours(3)),
  entry("x", 15.0)
);

spark.sql(
  sqlText = "SELECT current_timestamp() + :later, :x * :x AS square",
  args = argMap).show();
// +----------------------------------------+------+
// |current_timestamp() + INTERVAL '03' HOUR|square|
// +----------------------------------------+------+
// |                    2023-02-27 17:48:...|225.00|
// +----------------------------------------+------+

Python

spark.sql("SELECT :x * :y * :z AS volume", args = { "x" : 3, "y" : 4, "z"  : 5 }).show()
// +------+
// |volume|
// +------+
// |    60|
// +------+

Marqueurs de paramètres non nommés

S’applique à : Databricks Runtime check marked yes 13.3 et versions ultérieures

Les marqueurs de paramètres non nommés sont des variables d’espace réservé typées. L’API appelant l’instruction SQL doit fournir un tableau d’arguments pour associer chaque marqueur de paramètre à une valeur dans l’ordre dans lequel elles apparaissent.

Syntaxe

 ?

Paramètres

  • ? : une référence à un marqueur de paramètre fourni sous la forme d’un point d’interrogation.

Notes

Chaque occurrence d’un marqueur de paramètre non nommé consomme une valeur fournie par l’API appelant l’instruction SQL dans l’ordre. Si aucune valeur n’a été liée au marqueur de paramètre, une erreur UNBOUND_SQL_PARAMETER est générée. Vous n’êtes pas obligé d’utiliser toutes les valeurs fournies.

Exemples

L’exemple suivant est une définition de trois marqueurs de paramètres :

  • Un INTERVAL HOUR avec la valeur 3.
  • Deux DOUBLE avec la valeur 15,0 chacune.

Étant donné que les paramètres sont non nommés, chaque valeur fournie est consommée par au plus un paramètre.

SQL

> DECLARE stmtStr = 'SELECT current_timestamp() + ?, ? * ? AS square';
> EXECUTE IMMEDIATE stmtStr USING INTERVAL '3' HOURS, 15.0, 15.0;
  2024-01-19 16:17:16.692303  225.00

Scala

import org.apache.spark.sql.SparkSession

val spark = SparkSession
  .builder()
  .appName("Spark unnamed parameter marker example")
  .getOrCreate()

val argArr = Array(java.time.Duration.ofHours(3), 15.0, 15.0)

spark.sql(
  sqlText = "SELECT current_timestamp() + ?, ? * ? AS square", args = argArr).show()
// +----------------------------------------+------+
// |current_timestamp() + INTERVAL '03' HOUR|square|
// +----------------------------------------+------+
// |                    2023-02-27 17:48:...|225.00|
// +----------------------------------------+------+

Java

import org.apache.spark.sql.*;

SparkSession spark = SparkSession
  .builder()
  .appName("Java Spark unnamed parameter marker example")
  .getOrCreate();

Object[] argArr = new Object[] { java.time.Duration.ofHours(3), 15.0, 15.0 }

spark.sql(
  sqlText = "SELECT current_timestamp() + ?, ? * ? AS square",
  args = argArr).show();
// +----------------------------------------+------+
// |current_timestamp() + INTERVAL '03' HOUR|square|
// +----------------------------------------+------+
// |                    2023-02-27 17:48:...|225.00|
// +----------------------------------------+------+

Python

spark.sql("SELECT ? * ? * ? AS volume", args = { 3, 4, 5 }).show()
// +------+
// |volume|
// +------+
// |    60|
// +------+