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:

• Databricks SQL tramite l'API di esecuzione dell'istruzione.
• 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. In questo modo viene rimossa la restrizione DDL precedente, consentendo marcatori di parametro in colonne generate, DEFAULT definizioni, viste, funzioni SQL e clausole DDL con valori di stringa, ad esempio LOCATION.

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 current_timestamp() + :later, :x * :x AS square",
  args = { "later": datetime.timedelta(hours=3), "x": 15.0 }).show()
// +----------------------------------------+------+
// |current_timestamp() + INTERVAL '03' HOUR|square|
// +----------------------------------------+------+
// |                    2023-02-27 17:48:...|225.00|
// +----------------------------------------+------+

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, 'comment';

Marcatori di parametro nelle clausole di stringa DDL

Alcune clausole DDL, ad esempio la LOCATION clausola in CREATE TABLE, accettano valori letterali stringa anziché identificatori. Non è possibile usare la IDENTIFIER clausola per queste clausole perché non sono nomi di oggetto.

Si applica a: Databricks Runtime 18.0 e versioni successive

In Databricks Runtime 18.0 e versioni successive è possibile usare marcatori di parametro direttamente in queste clausole perché Databricks Runtime supporta i marcatori di parametro ovunque accetti un valore letterale dello stesso tipo. Per esempio:

SQL

> CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path;

Pitone

spark.sql(
  "CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path",
  args = {"path": "abfss://container@account.dfs.core.windows.net/data"})

scale

val argMap = Map("path" -> "abfss://container@account.dfs.core.windows.net/data")
spark.sql(
  sqlText = "CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path",
  args = argMap)

Giava

Map<String, String> argMap = Map.ofEntries(
  entry("path", "abfss://container@account.dfs.core.windows.net/data")
);

spark.sql(
  sqlText = "CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path",
  args = argMap);

Per le versioni di Databricks Runtime precedenti alla 18.0

Si applica a: Databricks SQL Databricks Runtime 14.3 a 17.3 LTS

Nelle versioni precedenti a Databricks Runtime 18.0, Databricks Runtime non consente marcatori di parametro direttamente nelle istruzioni DDL ,ad eccezione della IDENTIFIER clausola . È possibile usare EXECUTE IMMEDIATE per compilare l'istruzione SQL in modo dinamico, concatenando il valore del percorso come valore letterale stringa:

> DECLARE path STRING DEFAULT 'abfss://container@account.dfs.core.windows.net/data';
> EXECUTE IMMEDIATE 'CREATE EXTERNAL TABLE my_table USING DELTA LOCATION \'' || path || '\'';

Note

Non è possibile incorporare un marcatore di parametro all'interno di un valore letterale stringa , ad esempio 'abfss://:param/path'. Passare invece l'intera stringa come singolo parametro o usare la concatenazione di stringhe per compilare il valore prima di passarlo. Ad esempio, usare SET VARIABLE con CONCAT() per compilare il percorso completo in una variabile, quindi passare la variabile a EXECUTE IMMEDIATE.

Articoli correlati

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