Značky parametrů

Platí pro: označeno jako ano Databricks SQL Databricks Runtime

Značky parametrů jsou pojmenované nebo nepojmenované zástupné proměnné typu, které se používají k předání hodnot z rozhraní API vyvolávajícího příkaz SQL.

Použití značek parametrů chrání váš kód před útoky prostřednictvím injektáže SQL, protože jasně odděluje zadané hodnoty od struktury příkazů SQL.

Ve stejném příkazu SQL nelze kombinovat pojmenované a nepojmenované značky parametrů.

V klauzuli můžete také použít značky IDENTIFIER parametrů, které lze použít k parametrizaci názvů objektů. Vizklauzule .

Značky parametrů mohou být poskytovány:

Databricks SQL prostřednictvím rozhraní API pro spouštění příkazů
Python pomocí svého API pyspark.sql.SparkSession.sql().
Scala s použitím API org.apache.spark.sql.SparkSession.sql().
Java pomocí jeho rozhraní API org.apache.spark.sql.SparkSession.sql().

Platí následující pravidla:

Platí pro: Databricks SQL Databricks Runtime 17.3 LTS a starší verze
- Ve výrazu můžete odkazovat na značku parametru.
- V příkazu DDL nesmíte odkazovat na značku parametru, jako je vygenerovaný sloupec nebo definice DEFAULT, zobrazení nebo funkce SQL. Výjimky jsou odkazy na značky parametrů v IDENTIFIER klauzuli, které lze použít k parametrizaci předmětu určitých příkazů DDL. Vizklauzule .
Platí pro: Databricks Runtime 18.0 a vyšší
- Odkazovat na značku parametru můžete všude tam, kde můžete použít literál stejného typu jako značka parametru. Tím se zvětšuje předchozí omezení DDL, což umožňuje značky parametrů ve generovaných sloupcích, DEFAULT definicích, zobrazeních, funkcích SQL a klauzulích DDL s řetězcovou hodnotou, jako LOCATIONjsou .

Pojmenované značky parametrů

platí pro: Databricks Runtime zaškrtněte políčko Ano 12.1 a vyšší

Pojmenované značky parametrů jsou zástupné proměnné typu. Rozhraní API, které vyvolá příkaz SQL, musí zadat páry name-value pro přidružení každé značky parametru k hodnotě.

Syntaxe

 :parameter_name

Parametry

named_parameter_name

Odkaz na zadanou značku parametru ve formě nekvalifikovaného identifikátoru.

Poznámky

Stejnou značku parametru můžete v rámci stejného příkazu SQL odkazovat vícekrát. Pokud nebyla na značku parametru vázána žádná hodnota, je vyvolána UNBOUND_SQL_PARAMETER chyba. Nemusíte odkazovat na všechny zadané značky parametrů.

Povinný předcházející : (dvojtečka) rozlišuje obor názvů pojmenovaných značek parametrů od názvů sloupců a parametrů SQL.

Příklady

Následující příklad definuje dvě značky parametrů:

později: INTERVAL HOUR s hodnotou 3.
x: DOUBLE s hodnotou 15,0

x se odkazuje vícekrát, zatímco later se odkazuje jednou.

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

Platí pro: Databricks Runtime zaškrtnuto ano 18.0 a vyšší

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

Nepojmenované značky parametrů

platí pro: Databricks Runtime zaškrtněte políčko Ano 13.3 a vyšší

Nepojmenované značky parametrů jsou zástupné proměnné typu. Rozhraní API, které vyvolá příkaz SQL, musí zadat pole argumentů pro přidružení každé značky parametru k hodnotě v pořadí, ve kterém se zobrazí.

Syntaxe

Parametry

?: Odkaz na zadanou značku parametru ve formě otazníku.

Poznámky

Každý výskyt nepojmenované značky parametru použije hodnotu poskytnutou rozhraním API při volání SQL příkazu ve stanoveném pořadí. Pokud není žádná hodnota vázána na značku parametru, vyvolá se UNBOUND_SQL_PARAMETER chyba. Nemusíte využívat všechny zadané hodnoty.

Příklady

Následující příklad definuje tři značky parametrů:

INTERVAL HOUR s hodnotou 3.
Dvě DOUBLE, každé s hodnotou 15,0.

Vzhledem k tomu, že parametry nejsou pojmenovány, každá zadaná hodnota je spotřebována maximálně jedním parametrem.

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

Platí pro: Databricks Runtime zaškrtnuto ano 18.0 a vyšší

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

Značky parametrů v klauzulích řetězců DDL

Některé klauzule DDL, například LOCATION klauzule v CREATE TABLE, přijímají řetězcové literály místo identifikátorů. Klauzuli IDENTIFIER pro tyto klauzule nelze použít, protože nejsou názvy objektů.

Platí pro: Databricks Runtime zaškrtnuto ano 18.0 a vyšší

V Databricks Runtime 18.0 a novějších můžete použít značky parametrů přímo v těchto klauzulích, protože Databricks Runtime podporuje značky parametrů všude, kde přijímá literál stejného typu. Příklad:

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

Verze Databricks Runtime starší než 18.0

Platí pro: check marked yes Databricks SQL Databricks Runtime 14.3 to 17.3 LTS

Ve verzích starších než Databricks Runtime 18.0 databricks Runtime nepovoluje značky parametrů přímo v příkazech DDL (s výjimkou klauzule IDENTIFIER ). Příkaz SQL můžete použít EXECUTE IMMEDIATE k dynamickému sestavení příkazu SQL a zřetězení hodnoty cesty jako řetězcového literálu:

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

Note

Značku parametru nelze vložit do řetězcového literálu (například 'abfss://:param/path'). Místo toho předejte celý řetězec jako jeden parametr nebo před předáním hodnoty pomocí zřetězení řetězců. Použijte SET VARIABLECONCAT() například k sestavení úplné cesty v proměnné a předání proměnné do EXECUTE IMMEDIATE.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-06-01

Značky parametrů

Pojmenované značky parametrů

Syntaxe

Parametry

Poznámky

Příklady

SQL

Scala

Java

Python

Nepojmenované značky parametrů

Syntaxe

Parametry

Poznámky

Příklady

SQL

Scala

Java

Python

Značky parametrů v klauzulích řetězců DDL

SQL

Python

Scala

Java

Verze Databricks Runtime starší než 18.0

Související články

Váš názor

Další materiály