Delen via

Parametermarkeringen

Parametermarkeringen zijn benoemde of niet-benoemde getypte tijdelijke aanduidingsvariabelen die gebruikt worden om waarden te leveren vanuit de API die de SQL-instructie aanroept.

Door parametermarkeringen te gebruiken, wordt uw code beschermd tegen SQL-injectieaanvallen, omdat deze duidelijk opgegeven waarden van de SQL-instructies scheidt.

U kunt benoemde en niet-benoemde parametermarkeringen niet combineren in dezelfde SQL-instructie.

U mag niet verwijzen naar een parametermarkering in een DDL-instructie, zoals een gegenereerde kolom of DEFAULT definitie, een weergave of een SQL-functie.

Uitzonderingen zijn verwijzingen naar parametermarkeringen in de IDENTIFIER-component, die kunnen worden gebruikt om tabel- of kolomnamen in bepaalde DDL-instructies te parameteriseren. Zie IDENTIFIER clausule.

Parametermarkeringen kunnen worden opgegeven door:

Benoemde parametermarkeringen

Van toepassing op: Databricks Runtime met vinkje voor ja 12.1 en hoger

Benoemde parametermarkeringen zijn getype placeholders voor variabelen. De API die de SQL-instructie aanroept, moet naam-waardeparen opgeven om elke parametermarkering te koppelen aan een waarde.

Syntaxis

 :parameter_name

Parameters

  • named_parameter_name

    Een verwijzing naar een opgegeven parametermarkering in de vorm van een niet-gekwalificeerde identificator.

Notities

U kunt meerdere keren verwijzen naar dezelfde parametermarkering binnen dezelfde SQL-instructie. Als er geen waarde is gebonden aan de parametermarkering, wordt er een UNBOUND_SQL_PARAMETER fout gegenereerd. U hoeft niet te verwijzen naar alle opgegeven parametermarkeringen.

De verplichte voorafgaande : (dubbele punt) onderscheidt de naamruimte van benoemde parametermarkeringen van die van kolomnamen en SQL-parameters.

Voorbeelden

In het volgende voorbeeld worden twee parametermarkeringen gedefinieerd:

  • later: een INTERVAL HOUR met waarde 3.
  • x: een DOUBLE met de waarde 15,0

x meerdere keren wordt verwezen, terwijl er eenmaal naar later wordt verwezen.

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

Naamloze parametermarkeringen

Van toepassing op: Databricks Runtime aangevinkt ja 13.3 en hoger

Niet-benoemde parametermarkeringen zijn getypte tijdelijke aanduidingen voor variabelen. De API die de SQL-instructie aanroept, moet een matrix met argumenten opgeven om elke parametermarkering te koppelen aan een waarde in de volgorde waarin ze worden weergegeven.

Syntaxis

 ?

Parameters

  • ?: Een verwijzing naar een opgegeven parametermarkering in de vorm van een vraagteken.

Notities

Elk voorkomen van een naamloze parameter verbruikt een waarde die in volgorde door de API wordt geleverd bij het aanroepen van de SQL-instructie. Als er geen waarde is gebonden aan de parametermarkering, wordt er een UNBOUND_SQL_PARAMETER fout gegenereerd. U hoeft niet alle opgegeven waarden te gebruiken.

Voorbeelden

In het volgende voorbeeld worden drie parametermarkeringen gedefinieerd:

  • Een INTERVAL HOUR met waarde 3.
  • Twee DOUBLE met elk een waarde van 15,0.

Omdat de parameters zonder naam zijn, wordt elke opgegeven waarde gebruikt door maximaal één parameter.

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