Znaczniki parametrów

  • Artykuł

Znaczniki parametrów są nazwane lub nienazwane zmienne zastępcze typu używane do podawania wartości z interfejsu API wywołującego instrukcję SQL.

Użycie znaczników parametrów chroni kod przed atakami polegającymi na wstrzyknięciu kodu SQL, ponieważ wyraźnie oddziela podane wartości od instrukcji SQL.

Nie można mieszać znaczników nazwanych i nienazwanych parametrów w tej samej instrukcji SQL.

Nie można odwoływać się do znacznika parametru w instrukcji DDL, takiej jak wygenerowana kolumna lub DEFAULT definicja, widok lub funkcja SQL.

Wyjątki to odwołania do znaczników parametrów w IDENTIFIER klauzuli , które mogą służyć do parametryzacji nazw tabel lub kolumn w niektórych instrukcjach DDL. Zobacz klauzulę IDENTIFIER.

Znaczniki parametrów mogą być udostępniane przez:

Nazwane znaczniki parametrów

Dotyczy: Databricks Runtime check marked yes 12.1 lub nowszy

Nazwane znaczniki parametrów są typizowane zmienne zastępcze. Interfejs API wywołujący instrukcję SQL musi podać pary name-value, aby skojarzyć każdy znacznik parametru z wartością.

Składnia

 :parameter_name

Parametry

  • named_parameter_name

    Odwołanie do podanego znacznika parametru w postaci niekwalifikowanego identyfikatora.

Uwagi

Możesz odwoływać się do tego samego znacznika parametru wiele razy w ramach tej samej instrukcji SQL. Jeśli żadna wartość nie została powiązana ze znacznikiem parametru, zostanie zgłoszony błąd UNBOUND_SQL_PARAMETER . Nie musisz odwoływać się do wszystkich podanych znaczników parametrów.

Obowiązkowy poprzedni : (dwukropek) odróżnia przestrzeń nazw nazwanych znaczników parametrów od nazw kolumn i parametrów SQL.

Przykłady

W poniższym przykładzie zdefiniowano dwa znaczniki parametrów:

  • później: an INTERVAL HOUR o wartości 3.
  • x: A DOUBLE z wartością 15.0

x jest przywołyny wiele razy, podczas gdy later jest przywołyny raz.

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

Znaczniki parametrów bez nazwy

Dotyczy: Databricks Runtime check marked yes 13.3 i nowsze

Znaczniki parametrów bez nazwy są typizowane zmienne zastępcze. Interfejs API wywołujący instrukcję SQL musi podać tablicę argumentów, aby skojarzyć każdy znacznik parametru z wartością w kolejności ich wyświetlania.

Składnia

 ?

Parametry

  • ?: odwołanie do podanego znacznika parametru w postaci znaku zapytania.

Uwagi

Każde wystąpienie nienazwanego znacznika parametru zużywa wartość podaną przez interfejs API wywołując instrukcję SQL w kolejności. Jeśli żadna wartość nie została powiązana ze znacznikiem parametru, zostanie zgłoszony błąd UNBOUND_SQL_PARAMETER . Nie musisz używać wszystkich podanych wartości.

Przykłady

W poniższym przykładzie zdefiniowano trzy znaczniki parametrów:

  • Obiekt INTERVAL HOUR o wartości 3.
  • Dwa DOUBLE z wartością 15,0 każda.

Ponieważ parametry są nienazwane, każda podana wartość jest zużywana przez co najwyżej jeden parametr.

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