Marqueurs de paramètres

S’applique à : case cochée oui Databricks SQL Databricks Runtime

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 de la structure 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 pouvez également utiliser des marqueurs de paramètres dans la IDENTIFIER clause, qui peuvent être utilisés pour paramétrer les noms d’objets. Consultez la clause IDENTIFIER.

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

Python à l’aide de son API pyspark.sql.SparkSession.sql().
Scala à l’aide de son API org.apache.spark.sql.SparkSession.sql().
Java à l’aide de son API org.apache.spark.sql.SparkSession.sql().

Les règles suivantes s’appliquent :

S’applique à : Databricks SQL Databricks Runtime 17.3 LTS et versions antérieures
- Vous pouvez référencer un marqueur de paramètre dans une expression
- Vous ne devez pas référencer un marqueur de paramètre dans une instruction 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 à des marqueurs de paramètres dans la IDENTIFIER clause, qui peuvent être utilisées pour paramétrer l’objet de certaines instructions DDL. Consultez la clause IDENTIFIER.
S’applique à : Databricks Runtime 18.0 et versions ultérieures
- Vous pouvez référencer un marqueur de paramètre partout où un littéral de ce type peut être utilisé.

Marqueurs de paramètres nommés

s’applique à : Databricks Runtime cochez « oui » 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é.

Remarques

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 définit deux marqueurs de paramètre :

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|
// +------+

S’applique à : Databricks Runtime coché oui 18.0 et versions ultérieures

> EXECUTE IMMEDIATE 'SELECT 1::DECIMAL(:precision, :scale)' USING 6 AS precision, 4 AS scale;
  1.0000

> EXECUTE IMMEDIATE 'CREATE VIEW v(c1 INT) AS SELECT :val AS c1' USING 10 AS val;
> SELECT * FROM v;
  10

> EXECUTE IMMEDIATE 'CREATE TABLE T(c1 INT DEFAULT :def COMMENT \'This is a \' :com)' USING 17 AS def, 'comment' as com;

Marqueurs de paramètres sans nom

S’applique à : Databricks Runtime case cochée oui 13.3 et versions ultérieures

Les marqueurs de paramètre non désignés sont des variables d’espace de substitution 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

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

Remarques

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 définit trois marqueurs de paramètre :

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

Étant donné que les paramètres ne sont pas 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|
// +------+

S’applique à : Databricks Runtime coché oui 18.0 et versions ultérieures

> EXECUTE IMMEDIATE 'SELECT 1::DECIMAL(?, ?)' USING 6, 4;
  1.0000

> EXECUTE IMMEDIATE 'CREATE VIEW v(c1 INT) AS SELECT ? AS c1' USING 10;
> SELECT * FROM v;
  10

> EXECUTE IMMEDIATE 'CREATE TABLE T(c1 INT DEFAULT ? COMMENT \'This is a \' ?)' USING 17 AS def, ? as com;

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-01-17

Partager via

Marqueurs de paramètres

Marqueurs de paramètres nommés

Syntaxe

Paramètres

Remarques

Exemples

SQL

Scala

Java

Python

Marqueurs de paramètres sans nom

Syntaxe

Paramètres

Remarques

Exemples

SQL

Scala

Java

Python

Articles connexes

Commentaires

Ressources supplémentaires