Sdílet prostřednictvím

Značky parametrů

  • Článek

Značky parametrů jsou pojmenované nebo nepojmenované zástupné proměnné typu používané k dodání values prostřednictvím rozhraní API volají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 poskytnuté values od příkazů SQL.

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

V příkazu DDL nesmíte odkazovat na značku parametru, například vygenerovanou column nebo definici DEFAULT, zobrazení nebo funkci SQL.

Výjimky jsou odkazy na značky parametrů v klauzuli IDENTIFIER, které lze použít k parametrizaci table nebo column názvů v určitých příkazech DDL. Vizklauzule .

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

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

Parameters

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ředřazení : (dvojtečka) rozlišuje obor názvů pro pojmenované značky parametrů od oboru názvů column a SQL parameters.

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 :x * :y * :z AS volume", args = { "x" : 3, "y" : 4, "z"  : 5 }).show()
// +------+
// |volume|
// +------+
// |    60|
// +------+

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í.

Syntax

 ?

Parameters

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

Poznámky

Každý výskyt nepojmenované značky parametru spotřebovává hodnotu poskytnutou rozhraním API, která vyvolá příkaz SQL v uvedeném pořadí. Pokud není žádná hodnota vázána na značku parametru, vyvolá se UNBOUND_SQL_PARAMETER chyba. Nemusíte spotřebovat všechny poskytnuté values.

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 parameters jsou nepojmenované, každá zadaná hodnota je využita 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|
// +------+