Paraméterjelölők

A következőkre vonatkozik: Databricks SQL Databricks Runtime

A paraméterjelölők nevesített vagy névtelen típusú helyőrző változók, amelyek az SQL-utasítást meghívó API-tól származó értékek megadására szolgálnak.

A paraméterjelölők használata védi a kódot az SQL-injektálási támadásoktól, mivel egyértelműen elválasztja a megadott értékeket az SQL-utasítások szerkezetétől.

Az elnevezett és a névtelen paraméterjelölők nem keverhetők ugyanabban az SQL-utasításban.

A záradékban IDENTIFIER paraméterjelölőket is használhat, amelyek az objektumnevek paraméterezésére használhatók. Lásd a(z) IDENTIFIER és a(z)záradékot.

A paraméterjelölők a következőkkel adhatók meg:

• Python a pyspark.sql.SparkSession.sql() API használatával használja.
• Scala az org.apache.spark.sql.SparkSession.sql() API használatával.
• Java az org.apache.spark.sql.SparkSession.sql() API használatával.

A következő szabályok érvényesek:

• A következőre vonatkozik: Databricks SQL Databricks Runtime 17.3 LTS és korábbi

  • Paraméterjelölőre hivatkozhat egy kifejezésben
  • Nem hivatkozhat paraméterjelölőre egy DDL-utasításban, például generált oszlopra vagy DEFAULT definícióra, nézetre vagy SQL-függvényre. A kivételek a IDENTIFIER záradékban található paraméterjelölőkre mutató hivatkozások, amelyek felhasználhatók bizonyos DDL-utasítások tárgyának paraméterezésére. Lásd a(z) IDENTIFIER és a(z)záradékot.

• A következőre vonatkozik: a Databricks Runtime 18.0-s vagy újabb verzióira

  • A paraméterjelölőkre bárhol hivatkozhat, ahol a paraméterjelölő típusának literálját használhatja.

Elnevezett paraméterjelölők

A következőkre vonatkozik: Databricks Runtime 12.1 és újabb verziók esetében

Az elnevezett paraméterjelölők típusú helyettesítő változók. Az SQL-utasítást invesztő API-nak név-érték párokat kell megadnia az egyes paraméterjelölők értékhez való társításához.

Szintaxis

 :parameter_name

Paraméterek

• név_szerinti_paraméter_név

  Hivatkozás egy megadott paraméterjelölőre egy nem minősített azonosító formájában.

Jegyzetek

Ugyanarra a paraméterjelölőre többször is hivatkozhat ugyanabban az SQL-utasításban. Ha nincs érték a paraméterjelölőhöz kötve, UNBOUND_SQL_PARAMETER hiba jelenik meg. Nem szükséges az összes megadott paraméterjelölőre hivatkoznia.

A kötelező előző : (kettőspont) megkülönbözteti az elnevezett paraméterjelölők névterét az oszlopnevektől és az SQL-paraméterektől.

Példák

Az alábbi példa két paraméterjelölőt határoz meg:

• később: egy INTERVAL HOUR értékkel 3.
• x: A 15,0 értékű DOUBLE

x többször hivatkozik rá, míg a later egyszer hivatkozik rá.

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

A következőkre vonatkozik: Databricks Runtime 18.0 vagy újabb verzió

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

Névtelen paraméterjelölők

A következőkre vonatkozik: Databricks Runtime 13.3 vagy újabb

A névtelen paraméterjelölők helyőrző változók. Az SQL-utasítást invesztő API-nak egy argumentumtömböt kell megadnia, hogy az egyes paraméterjelölők egy értékkel legyenek társítva a megjelenésük sorrendjében.

Szintaxis

 ?

Paraméterek

• ?: Egy megadott paraméterjelölőre mutató hivatkozás kérdőjel formájában.

Jegyzetek

A névtelen paraméterjelölők minden előfordulása az SQL-utasítást invokáló API által biztosított értéket használja fel sorrendben. Ha nincs érték a paraméterjelölőhöz kötve, UNBOUND_SQL_PARAMETER hiba jelenik meg. Nem kell minden megadott értéket felhasználnia.

Példák

Az alábbi példa három paraméterjelölőt határoz meg:

• Egy 3 értékű INTERVAL HOUR.
• Két DOUBLE, amelyek értéke mindegyik esetében 15,0.

Mivel a paraméterek névtelenek, az egyes megadott értékeket legfeljebb egy paraméter használja.

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

A következőkre vonatkozik: Databricks Runtime 18.0 vagy újabb verzió

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

Kapcsolódó cikkek

• pyspark.sql.SparkSession.sql()
• org.apache.spark.sql.SparkSession.sql()
• IDENTIFIER klauzula
• EXECUTE IMMEDIATE
• Nevek
• SET változó