Penanda parameter

Berlaku untuk: Ditandai centang ya 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:

Databricks SQL melalui API Eksekusi Pernyataan.
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. Ini mengangkat pembatasan DDL sebelumnya, memungkinkan penanda parameter dalam kolom, definisi, DEFAULT tampilan, fungsi SQL, dan klausa DDL bernilai string seperti LOCATION.

Penanda parameter yang diberi nama

Berlaku untuk: Databricks Runtime centang bertanda ya 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 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|
// +----------------------------------------+------+

Berlaku untuk: Databricks Runtime dicentang ya 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 centang bertanda ya 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 dicentang ya 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, 'comment';

Penanda parameter dalam klausa string DDL

Beberapa klausa DDL, seperti LOCATION klausul dalam CREATE TABLE, terima literal string daripada pengidentifikasi. Anda tidak dapat menggunakan IDENTIFIER klausa untuk klausul ini karena bukan nama objek.

Berlaku untuk: Databricks Runtime dicentang ya 18.0 ke atas

Di Databricks Runtime 18.0 ke atas, Anda dapat menggunakan penanda parameter langsung dalam klausul ini karena Databricks Runtime mendukung penanda parameter di mana pun ia menerima literal jenis yang sama. Contohnya:

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

Untuk versi Databricks Runtime sebelum 18.0

Berlaku untuk: check ditandai ya pemeriksaan Databricks SQL Databricks Runtime 14.3 hingga 17.3 LTS

Dalam versi sebelum Databricks Runtime 18.0, Databricks Runtime tidak mengizinkan penanda parameter langsung dalam pernyataan DDL (kecuali melalui IDENTIFIER klausa). Anda dapat menggunakan EXECUTE IMMEDIATE untuk membangun pernyataan SQL secara dinamis, menggabungkan nilai jalur sebagai string literal:

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

Note

Anda tidak dapat menyematkan penanda parameter di dalam string literal (misalnya, 'abfss://:param/path'). Sebagai gantinya, teruskan seluruh string sebagai parameter tunggal, atau gunakan perangkaian string untuk membangun nilai sebelum meneruskannya. Misalnya, gunakan SET VARIABLE dengan CONCAT() untuk membangun jalur lengkap dalam variabel, lalu teruskan variabel ke EXECUTE IMMEDIATE.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-06-01

Penanda parameter

Penanda parameter yang diberi nama

Sintaksis

Parameter

Catatan

Contoh

SQL

Scala

Java

Python

Penanda parameter yang tidak disebutkan namanya

Sintaksis

Parameter

Catatan

Contoh

SQL

Scala

Java

Python

Penanda parameter dalam klausa string DDL

SQL

Python

Scala

Java

Untuk versi Databricks Runtime sebelum 18.0

Artikel terkait

Saran dan Komentar

Sumber Daya Tambahan: