Condividi tramite

Marcatori di parametro

  • Articolo

I marcatori di parametro vengono denominati o senza nome variabili segnaposto tipate usate per fornire valori dall'API richiamando l'istruzione SQL.

L'uso di marcatori di parametro protegge il codice dagli attacchi SQL injection perché separa chiaramente i valori forniti dalle istruzioni SQL.

Non è possibile combinare marcatori di parametro denominati e senza nome nella stessa istruzione SQL.

Non è necessario fare riferimento a un marcatore di parametro in un'istruzione DDL, ad esempio una colonna generata o una definizione di DEFAULT, una vista o una funzione SQL.

Le eccezioni sono riferimenti ai marcatori di parametro nella clausola IDENTIFIER, che può essere usata per parametrizzare i nomi di tabella o di colonna in determinate istruzioni DDL. Vedi clausola IDENTIFIER.

I marcatori di parametro possono essere forniti da:

  • Python utilizzando l'API pyspark.sql.SparkSession.sql().
  • Scala usando la sua API org.apache.spark.sql.SparkSession.sql().
  • Java usando l'API org.apache.spark.sql.SparkSession.sql().

Marcatori di parametro denominati

Si applica a: Databricks Runtime spunta contrassegnata come sì 12.1 e versioni successive

I marcatori di parametro denominati sono variabili segnaposto tipate. L'API che richiama l'istruzione SQL deve fornire coppie nome-valore per associare ogni marcatore di parametro a un valore.

Sintassi

 :parameter_name

Parametri

  • nome_parametro_named

    Riferimento a un marcatore di parametro fornito sotto forma di identificatore non qualificato.

Note

È possibile fare riferimento più volte allo stesso marcatore di parametro all'interno della stessa istruzione SQL. Se al marcatore del parametro non è stato associato alcun valore viene generato un errore di UNBOUND_SQL_PARAMETER. Non è necessario fare riferimento a tutti i marcatori di parametro forniti.

Il : obbligatorio precedente (due punti) differenzia lo spazio dei nomi dei marcatori di parametri denominati da quello dei nomi di colonna e dei parametri SQL.

Esempi

L'esempio seguente definisce due marcatori di parametro:

  • in seguito: Un INTERVAL HOUR con valore 3.
  • x: Un DOUBLE con valore 15,0

x viene fatto riferimento più volte, mentre later viene fatto riferimento una sola volta.

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

Giava

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

Pitone

spark.sql("SELECT :x * :y * :z AS volume", args = { "x" : 3, "y" : 4, "z"  : 5 }).show()
// +------+
// |volume|
// +------+
// |    60|
// +------+

Marcatori di parametro senza nome

Si applica a: Databricks Runtime indicato come sì 13.3 e versioni successive

I marcatori di parametro senza nome sono variabili segnaposto tipate. L'API che richiama l'istruzione SQL deve fornire una matrice di argomenti per associare ogni marcatore di parametro a un valore nell'ordine in cui vengono visualizzati.

Sintassi

 ?

Parametri

  • ?: riferimento a un marcatore di parametro fornito sotto forma di punto interrogativo.

Note

Ogni occorrenza di un marcatore di parametro senza nome utilizza un valore fornito dall'API richiamando l'istruzione SQL in ordine. Se non è stato associato alcun valore al marcatore di parametro, viene generato un errore di UNBOUND_SQL_PARAMETER. Non è necessario utilizzare tutti i valori forniti.

Esempi

L'esempio seguente definisce tre marcatori di parametro:

  • Un INTERVAL HOUR con valore 3.
  • Due DOUBLE con valore 15,0 ciascuno.

Poiché i parametri sono senza nome, ogni valore specificato viene utilizzato al massimo da un parametro.

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

Giava

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

Pitone

spark.sql("SELECT ? * ? * ? AS volume", args = { 3, 4, 5 }).show()
// +------+
// |volume|
// +------+
// |    60|
// +------+