Marcatori di parametro

Si applica a: Databricks SQL Databricks Runtime

I marcatori di parametro sono denominati o senza nome, variabili segnaposto tipizzate utilizzate dall'API per fornire valori all'istruzione SQL richiamata.

L'uso di marcatori di parametro protegge il codice dagli attacchi SQL injection poiché separa chiaramente i valori forniti dalla struttura delle istruzioni SQL.

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

È anche possibile usare i marcatori di parametro nella IDENTIFIER clausola , che può essere usato per parametrizzare i nomi degli oggetti. 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 utilizzando l'API org.apache.spark.sql.SparkSession.sql().

Si applicano le seguenti regole:

• Si applica a: Databricks SQL Databricks Runtime 17.3 LTS e versioni precedenti

  • È possibile fare riferimento a un marcatore di parametro in un'espressione
  • 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 IDENTIFIER clausola , che possono essere usati per parametrizzare l'oggetto di determinate istruzioni DDL. Vedi clausola IDENTIFIER.

• Si applica a: Databricks Runtime 18.0 e versioni successive

  • È possibile fare riferimento a un marcatore di parametro ovunque sia possibile usare un valore letterale del tipo di marcatore di parametro.

Marcatori di parametro denominati

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

scale

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

Si applica a: Databricks Runtime 18.0 e versioni successive

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

Marcatori di parametro senza nome

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

scale

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

Si applica a: Databricks Runtime 18.0 e versioni successive

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

Articoli correlati

• pyspark.sql.SparkSession.sql()
• org.apache.spark.sql.SparkSession.sql()
• IDENTIFIER clausola
• EXECUTE IMMEDIATE
• Names
• SET variabile