Parametermarkeringen

Van toepassing op: Databricks SQL Databricks Runtime

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

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

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

U kunt ook parametermarkeringen in de IDENTIFIER component gebruiken, die kunnen worden gebruikt om objectnamen te parameteriseren. Zie IDENTIFIER clausule.

Parametermarkeringen kunnen worden opgegeven door:

• Python- met behulp van de pyspark.sql.SparkSession.sql()-API.
• Scala- met behulp van de org.apache.spark.sql.SparkSession.sql()-API.
• Java gebruikmakend van de org.apache.spark.sql.SparkSession.sql()-API.

De volgende regels zijn van toepassing:

• Van toepassing op: Databricks SQL Databricks Runtime 17.3 LTS en eerder

  • U kunt verwijzen naar een parametermarkering in een expressie
  • 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 het onderwerp van bepaalde DDL-instructies te parameteriseren. Zie IDENTIFIER clausule.

• Van toepassing op: Databricks Runtime 18.0 en hoger

  • U kunt verwijzen naar een parametermarkering, waar u ook een letterlijke waarde van het type parametermarkering kunt gebruiken.

Benoemde parametermarkeringen

Van toepassing op: Databricks Runtime 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|
// +------+

Van toepassing op: Databricks Runtime 18.0 en hoger

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

Naamloze parametermarkeringen

Van toepassing op: Databricks Runtime 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|
// +------+

Van toepassing op: Databricks Runtime 18.0 en hoger

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

Verwante artikelen

• pyspark.sql.SparkSession.sql()
• org.apache.spark.sql.SparkSession.sql()
• IDENTIFIER clausule
• EXECUTE IMMEDIATE
• Namen
• SET variabele