Parametermarkeringen

  • Artikel

Parametermarkeringen zijn benoemde of niet-benoemde tijdelijke aanduidingsvariabelen die worden gebruikt om waarden op te geven van 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 component, die kunnen worden gebruikt voor het IDENTIFIER parameteriseren van tabel- of kolomnamen in bepaalde DDL-instructies. Zie de ID-component.

Parametermarkeringen kunnen worden opgegeven door:

Benoemde parametermarkeringen

Van toepassing op: Databricks Runtime check marked yes 12.1 en hoger

Benoemde parametermarkeringen zijn tijdelijke aanduidingen voor variabelen getypt. 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 id.

Opmerkingen

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 : punt (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: A DOUBLE met waarde 15,0

x wordt meerdere keren naar verwezen, terwijl later er eenmaal naar 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 check marked yes 13.3 en hoger

Niet-benoemde parametermarkeringen zijn tijdelijke aanduidingen voor variabelen getypt. 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.

Opmerkingen

Elke instantie van een niet-benoemde parametermarkering verbruikt een waarde die wordt geleverd door de API die de SQL-instructie in de volgorde aanroept. 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 elke waarde 15,0.

Omdat de parameters een niet-naam hebben, wordt elke opgegeven waarde verbruikt 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|
// +------+