Freigeben über

Parametermarkierungen

  • Artikel

Parametermarkierungen sind benannte oder nicht benannte typbehaftete Platzhaltervariablen zum Bereitstellen von Werten aus der API, die die SQL-Anweisung aufruft.

Die Verwendung von Parametermarkierungen schützt Ihren Code vor SQL-Einfügungsangriffen, da er die bereitgestellten Werte eindeutig von den SQL-Anweisungen trennt.

Sie können benannte und nicht benannte Parametermarkierungen nicht in derselben SQL-Anweisung kombinieren.

Sie dürfen nicht auf eine Parametermarkierung in einer DDL-Anweisung verweisen, z. B. auf eine generierte Spalte oder DEFAULT Definition, eine Ansicht oder eine SQL-Funktion.

Ausnahmen sind Verweise auf Parametermarkierungen in der IDENTIFIER-Klausel, die zum Parametrisieren von Tabellen- oder Spaltennamen in bestimmten DDL-Anweisungen verwendet werden können. Siehe IDENTIFIER Klausel.

Parametermarkierungen können folgendermaßen bereitgestellt werden:

Benannte Parametermarkierungen

Gilt für: Databricks Runtime mit „Ja“ markiert 12.1 und höher

Benannte Parametermarker sind typierte Platzhaltervariablen. Die API, die die SQL-Anweisung aufruft, muss Name-Wert-Paare angeben, um jede Parametermarkierung einem Wert zuzuordnen.

Syntax

 :parameter_name

Parameter

  • named_parameter_name

    Ein Verweis auf eine angegebene Parametermarkierung in Form eines nicht qualifizierten Bezeichners.

Hinweise

Sie können mehrmals innerhalb derselben SQL-Anweisung auf dieselbe Parametermarkierung verweisen. Wenn kein Wert an die Parametermarkierung gebunden wurde, wird ein UNBOUND_SQL_PARAMETER Fehler ausgelöst. Sie müssen nicht auf alle angegebenen Parametermarkierungen verweisen.

Der obligatorische vorangehende Doppelpunkt (:) unterscheidet den Namespace der benannten Parametermarkierungen von denen von Spaltennamen und SQL-Parametern.

Beispiele

Im folgenden Beispiel werden zwei Parametermarkierungen definiert:

  • later: ein INTERVAL HOUR-Element mit dem Wert 3
  • x: ein DOUBLE-Element mit dem Wert 15,0

x wird mehrmals referenziert, während later einmal referenziert wird.

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

Unbenannte Parametermarkierungen

Gilt für: Databricks Runtime mit „Ja“ markiert 13.3 und höher

Nicht benannte Parametermarkierungen sind typierte Platzhaltervariablen. Die API, die die SQL-Anweisung aufruft, muss ein Array von Argumenten bereitstellen, um jede Parametermarkierung einem Wert in der Reihenfolge zuzuordnen, in der sie angezeigt werden.

Syntax

 ?

Parameter

  • ?: Ein Verweis auf eine angegebene Parametermarkierung in Form eines Fragezeichens.

Hinweise

Jedes Vorkommen einer nicht benannten Parametermarkierung verbraucht in der Reihenfolge einen Wert, der von der API bereitgestellt wird, die die SQL-Anweisung aufruft. Wenn kein Wert an die Parametermarkierung gebunden wurde, wird ein UNBOUND_SQL_PARAMETER Fehler ausgelöst. Sie müssen nicht alle bereitgestellten Werte verwenden.

Beispiele

Im folgenden Beispiel werden drei Parametermarkierungen definiert:

  • Ein INTERVAL HOUR-Element mit dem Wert 3
  • Zwei DOUBLE jeweils mit dem Wert 15,0.

Da die Parameter nicht benannt sind, wird jeder bereitgestellte Wert von höchstens einem Parameter verwendet.

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