Penanda parameter

  • Artikel

Penanda parameter diberi nama atau variabel tempat penampung yang diketik tanpa nama yang digunakan untuk menyediakan 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 pernyataan SQL.

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

Anda tidak boleh mereferensikan penanda parameter dalam pernyataan DDL, seperti kolom atau DEFAULT definisi yang dihasilkan, tampilan, atau fungsi SQL.

Pengecualian adalah referensi ke penanda parameter dalam IDENTIFIER klausa, yang dapat digunakan untuk membuat parameter nama tabel atau kolom dalam pernyataan DDL tertentu. Lihat klausa PENGIDENTIFIKASI.

Penanda parameter dapat disediakan oleh:

Penanda parameter bernama

Berlaku untuk: Databricks Runtime check marked yes 12.1 ke atas

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

Sintaks

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

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

Contoh

Contoh berikut mendefinisikan dua penanda parameter:

  • nanti: Dengan INTERVAL HOUR nilai 3.
  • x: A DOUBLE dengan 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|
// +------+

Penanda parameter yang tidak disebutkan namanya

Berlaku untuk: Databricks Runtime check marked yes 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.

Sintaks

 ?

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:

  • Dengan INTERVAL HOUR 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|
// +------+