Znaczniki parametrów

Dotyczy: Databricks SQL 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:

• Usługa Databricks SQL za pośrednictwem interfejsu API wykonywania instrukcji.
• 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: Databricks SQL 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: 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. Spowoduje to zniesienie powyższego ograniczenia DDL, zezwalając na znaczniki parametrów w wygenerowanych kolumnach, DEFAULT definicjach, widokach, funkcjach SQL i klauzulach DDL o wartości ciągu, takich jak LOCATION.

Nazwane znaczniki parametrów

Dotyczy: Databricks Runtime 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 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|
// +----------------------------------------+------+

Dotyczy: Sprawdzanie środowiska Databricks Runtime 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 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 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, 'comment';

Znaczniki parametrów w klauzulach ciągu DDL

Niektóre klauzule DDL, takie jak klauzula LOCATION w pliku CREATE TABLE, akceptują literały ciągu, a nie identyfikatory. Nie można użyć klauzuli IDENTIFIER dla tych klauzul, ponieważ nie są to nazwy obiektów.

Dotyczy: Sprawdzanie środowiska Databricks Runtime 18.0 lub nowsze

W środowisku Databricks Runtime w wersji 18.0 lub nowszej można używać znaczników parametrów bezpośrednio w tych klauzulach, ponieważ środowisko Databricks Runtime obsługuje znaczniki parametrów wszędzie tam, gdzie akceptuje literał tego samego typu. Przykład:

SQL

> CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path;

Python

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

Scala

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)

Java

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

W przypadku wersji środowiska Databricks Runtime wcześniejszych niż 18.0

Dotyczy: Sprawdzanie bazy danych Databricks SQL Databricks Runtime 14.3 do 17.3 LTS

W wersjach wcześniejszych niż Databricks Runtime 18.0 środowisko Databricks Runtime nie zezwala na znaczniki parametrów bezpośrednio w instrukcjach DDL (z wyjątkiem klauzuli IDENTIFIER ). Możesz użyć EXECUTE IMMEDIATE polecenia , aby dynamicznie skompilować instrukcję SQL, połączyć wartość ścieżki jako literał ciągu:

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

Note

Nie można osadzić znacznika parametru wewnątrz literału ciągu (na przykład 'abfss://:param/path'). Zamiast tego przekaż cały ciąg jako pojedynczy parametr lub użyj łączenia ciągów, aby skompilować wartość przed przekazaniem go. Na przykład użyj polecenia SET VARIABLE , CONCAT() aby skompilować pełną ścieżkę w zmiennej, a następnie przekazać zmienną do EXECUTE IMMEDIATEzmiennej .

Powiązane artykuły

• pyspark.sql.SparkSession.sql()
• org.apache.spark.sql.SparkSession.sql()
• IDENTIFIER klauzula
• EXECUTE IMMEDIATE
• Nazwy
• SET zmienna