Penanda parameter

Berlaku untuk: Databricks SQL Databricks Runtime

Penanda parameter adalah variabel placeholder bertipe yang dinamai atau tidak dinamai yang digunakan untuk menyuplai nilai dari API yang memanggil pernyataan SQL.

Menggunakan penanda parameter melindungi kode Anda dari serangan injeksi SQL karena dengan jelas memisahkan nilai yang disediakan dari struktur pernyataan SQL.

Anda tidak dapat mencampur penanda parameter bernama dan tanpa nama dalam pernyataan SQL yang sama.

Anda juga dapat menggunakan penanda parameter dalam IDENTIFIER klausa, yang dapat digunakan untuk membuat parameter nama objek. Lihat klausa IDENTIFIER.

Penanda parameter dapat disediakan oleh:

• Python menggunakan API pyspark.sql.SparkSession.sql().
• Scala menggunakan API org.apache.spark.sql.SparkSession.sql().
• Java menggunakan org.apache.spark.sql.SparkSession.sql() API.

Aturan berikut ini akan berlaku:

• Berlaku untuk: Databricks SQL Databricks Runtime 17.3 LTS dan sebelumnya

  • Anda dapat mereferensikan penanda parameter dalam ekspresi
  • Anda tidak boleh mereferensikan penanda parameter dalam pernyataan DDL, seperti kolom yang dihasilkan atau definisi DEFAULT, tampilan, atau fungsi SQL. Pengecualian adalah referensi ke penanda parameter dalam IDENTIFIER klausul, yang dapat digunakan untuk membuat parameter subjek pernyataan DDL tertentu. Lihat klausa IDENTIFIER.

• Berlaku untuk: Databricks Runtime 18.0 ke atas

  • Anda dapat merujuk pada penanda parameter di mana pun Anda dapat menggunakan literal dari jenis penanda parameter.

Penanda parameter yang diberi nama

Berlaku untuk: Databricks Runtime 12.1 ke atas

Penanda parameter yang dinamai adalah variabel tempat yang diketikkan. API yang memanggil pernyataan SQL harus menyediakan pasangan nama-nilai untuk mengaitkan setiap penanda parameter dengan nilai.

Sintaksis

 :parameter_name

Parameter

• named_parameter_name

  Referensi ke penanda parameter yang disediakan dalam bentuk pengidentifikasi yang tidak memenuhi syarat.

Catatan

Anda dapat mereferensikan penanda parameter yang sama beberapa kali dalam Pernyataan SQL yang sama. Jika tidak ada nilai yang terikat ke penanda parameter, kesalahan UNBOUND_SQL_PARAMETER dimunculkan. Anda tidak diharuskan untuk mereferensikan semua penanda parameter yang disediakan.

: (titik dua) sebelumnya wajib membedakan namespace penanda parameter bernama dari nama kolom dan parameter SQL.

Contoh

Contoh berikut mendefinisikan dua penanda parameter:

• nanti: INTERVAL HOUR dengan nilai 3.
• x: Sebuah DOUBLE yang memiliki nilai 15,0

x dirujuk beberapa kali, sementara later dirujuk sekali.

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

Berlaku untuk: Databricks Runtime 18.0 ke atas

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

Penanda parameter yang tidak disebutkan namanya

Berlaku untuk: Databricks Runtime 13.3 ke atas

Penanda parameter yang tidak disebutkan namanya adalah variabel tempat penampung yang ditik. API yang memanggil pernyataan SQL harus menyediakan array argumen untuk mengaitkan setiap penanda parameter dengan nilai dalam urutan munculnya.

Sintaksis

 ?

Parameter

• ?: Referensi ke penanda parameter yang disediakan dalam bentuk tanda tanya.

Catatan

Setiap kemunculan penanda parameter yang tidak disebutkan namanya menggunakan nilai yang disediakan oleh API yang memanggil pernyataan SQL secara berurutan. Jika tidak ada nilai yang terikat ke penanda parameter, kesalahan UNBOUND_SQL_PARAMETER akan muncul. Anda tidak diharuskan untuk mengonsumsi semua nilai yang disediakan.

Contoh

Contoh berikut mendefinisikan tiga penanda parameter:

• Sebuah INTERVAL HOUR dengan nilai 3.
• Dua DOUBLE dengan nilai masing-masing 15,0.

Karena parameter tidak disebutkan namanya, setiap nilai yang disediakan dikonsumsi oleh paling banyak satu parameter.

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

Berlaku untuk: Databricks Runtime 18.0 ke atas

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

Artikel terkait

• pyspark.sql.SparkSession.sql()
• org.apache.spark.sql.SparkSession.sql()
• IDENTIFIER klausa
• EXECUTE IMMEDIATE
• Names
• SET variabel