Parametermarkierungen

Gilt für: Databricks SQL Databricks Runtime

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 der Struktur der SQL-Anweisungen trennt.

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

Sie können auch Parametermarkierungen in der IDENTIFIER Klausel verwenden, die zum Parametrisieren von Objektnamen verwendet werden können. Siehe IDENTIFIER Klausel.

Parametermarkierungen können folgendermaßen bereitgestellt werden:

• Databricks SQL über die Anweisungsausführungs-API.
• In Python mit der pyspark.sql.SparkSession.sql()-API.
• In Scala mit der org.apache.spark.sql.SparkSession.sql()-API.
• In Java mit der org.apache.spark.sql.SparkSession.sql()-API

Es gelten die folgenden Regeln:

• Gilt für: Databricks SQL Databricks Runtime 17.3 LTS und frühere Versionen

  • Sie können auf eine Parametermarkierung in einem Ausdruck verweisen.
  • 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 des Betreffs bestimmter DDL-Anweisungen verwendet werden können. Siehe IDENTIFIER Klausel.

• Gilt für: Databricks Runtime 18.0 und höher

  • Sie können auf eine Parameter-Markierung verweisen, wo immer Sie ein Literal des Typs der Parameter-Markierung verwenden können. Dadurch wird die vorherige DDL-Einschränkung aufgehoben, sodass Parametermarkierungen in generierten Spalten, DEFAULT Definitionen, Ansichten, SQL-Funktionen und Zeichenfolgenwert-DDL-Klauseln wie .LOCATION

Benannte Parametermarkierungen

Gilt für: Databricks Runtime  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 current_timestamp() + :later, :x * :x AS square",
  args = { "later": datetime.timedelta(hours=3), "x": 15.0 }).show()
// +----------------------------------------+------+
// |current_timestamp() + INTERVAL '03' HOUR|square|
// +----------------------------------------+------+
// |                    2023-02-27 17:48:...|225.00|
// +----------------------------------------+------+

Gilt für: Databricks Runtime und höher

> 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;

Unbenannte Parametermarkierungen

Gilt für: Databricks Runtime  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|
// +------+

Gilt für: Databricks Runtime und höher

> 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, 'comment';

Parametermarkierungen in DDL-Zeichenfolgenklauseln

Einige DDL-Klauseln, z. B. die LOCATION Klausel in CREATE TABLE, akzeptieren Zeichenfolgenliterale anstelle von Bezeichnern. Sie können die IDENTIFIER Klausel für diese Klauseln nicht verwenden, da sie keine Objektnamen sind.

Gilt für: Databricks Runtime und höher

In Databricks Runtime 18.0 und höher können Sie Parametermarkierungen direkt in diesen Klauseln verwenden, da Databricks Runtime Parametermarkierungen unterstützt, wo sie ein Literal desselben Typs akzeptiert. Beispiel:

SQL

> CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path;

Python

spark.sql(
  "CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path",
  args = {"path": "abfss://container@account.dfs.core.windows.net/data"})

Scala

val argMap = Map("path" -> "abfss://container@account.dfs.core.windows.net/data")
spark.sql(
  sqlText = "CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path",
  args = argMap)

Java

Map<String, String> argMap = Map.ofEntries(
  entry("path", "abfss://container@account.dfs.core.windows.net/data")
);

spark.sql(
  sqlText = "CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path",
  args = argMap);

Für Databricks-Runtime-Versionen vor 18.0

Gilt für: Databricks SQL Databricks Runtime 14.3 to 17.3 LTS

In Versionen vor Databricks Runtime 18.0 lässt Databricks Runtime parametermarkierungen nicht direkt in DDL-Anweisungen zu (mit Ausnahme der IDENTIFIER Klausel). Sie können EXECUTE IMMEDIATE die SQL-Anweisung dynamisch erstellen und den Pfadwert als Zeichenfolgenliteral verketten:

> DECLARE path STRING DEFAULT 'abfss://container@account.dfs.core.windows.net/data';
> EXECUTE IMMEDIATE 'CREATE EXTERNAL TABLE my_table USING DELTA LOCATION \'' || path || '\'';

Verwandte Artikel

• pyspark.sql.SparkSession.sql()
• org.apache.spark.sql.SparkSession.sql()
• IDENTIFIER Klausel
• EXECUTE IMMEDIATE
• Namen
• SET Variable