Marcatori di parametro

  • Articolo

I marcatori di parametro sono variabili segnaposto denominate o senza nome 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 o DEFAULT una definizione generata, una vista o una funzione SQL.

Le eccezioni sono riferimenti ai marcatori di parametro nella IDENTIFIER clausola , che possono essere usati per parametrizzare i nomi di tabella o di colonna in determinate istruzioni DDL. Vedere clausola IDENTIFIER.

I marcatori di parametro possono essere forniti da:

Marcatori di parametro denominati

Si applica a: Databricks Runtime check marked yes 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

  • named_parameter_name

    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 precedente : obbligatorio (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: valore INTERVAL HOUR 3.
  • x: A 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|
// +----------------------------------------+------+

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

Marcatori di parametro senza nome

Si applica a: Databricks Runtime check marked yes 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 all'indicatore 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:

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

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