Udostępnij przez

Znaczniki parametrów

Dotyczy:zaznacz pole wyboru oznaczone jako tak Databricks SQL zaznacz pole wyboru oznaczone jako tak Databricks Runtime

Znaczniki parametrów są nazwane lub nienazwane typowane jako zmienne zastępcze używane do dostarczania 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 struktury instrukcji SQL.

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

Można również użyć znaczników parametrów w klauzuli IDENTIFIER , która może służyć do parametryzacji nazw obiektów. Zobacz klauzulę IDENTIFIER.

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

  • Python przy użyciu interfejsu API pyspark.sql.SparkSession.sql().
  • Scala przy użyciu interfejsu API org.apache.spark.sql.SparkSession.sql().
  • Java przy użyciu API org.apache.spark.sql.SparkSession.sql().

Obowiązują następujące zasady:

  • Dotyczy:zaznaczone jako tak Databricks SQL zaznaczone jako tak Databricks Runtime 17.3 LTS i wcześniejsze

    • Możesz odwołać się do znacznika parametru w wyrażeniu
    • Nie można odwoływać się do znacznika parametru w instrukcji DDL, takiej jak wygenerowana kolumna lub definicja DEFAULT, 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 tematu niektórych instrukcji DDL. Zobacz klauzulę IDENTIFIER.

  • Dotyczy:zaznaczone jako tak Databricks Runtime 18.0 lub nowsze

    • Możesz odwołać się do znacznika parametru wszędzie tam, gdzie można użyć literału typu znacznika parametru.

Nazwane znaczniki parametrów

Dotyczy: Databricks Runtime zaznacz pole wyboru tak 12.1 i nowszych

Nazwane markery parametrów to 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

  • nazwa_parametru

    Odwołanie do podanego symbolu parametru jako niekwalifikowanego identyfikatora.

Notatki

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: Element INTERVAL HOUR o wartości 3.
  • x: DOUBLE o wartości 15.0

x jest przywołyyny 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|
// +------+

Dotyczy: Sprawdzanie środowiska Databricks Runtime oznaczone jako tak 18.0 lub nowsze

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

Znaczniki parametrów bez nazwy

Dotyczy: Databricks Runtime zaznacz pole wyboru tak 13.3 lub nowsze

Znaczniki parametrów bez nazwy to typowane 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.

Notatki

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

Przykłady

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

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

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

Dotyczy: Sprawdzanie środowiska Databricks Runtime oznaczone jako tak 18.0 lub nowsze

> 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;
  • Last updated on