علامات المعلمات
علامات المعلمات هي متغيرات عنصر نائب مكتوبة مسماة أو غير مسماة تستخدم لتوفير القيم من واجهة برمجة التطبيقات التي تستدعي عبارة SQL.
يحمي استخدام علامات المعلمات التعليمات البرمجية الخاصة بك من هجمات حقن SQL لأنه يفصل بوضوح القيم المقدمة من عبارات SQL.
لا يمكنك خلط علامات المعلمات المسماة وغير المسماة في نفس عبارة SQL.
يجب عدم الإشارة إلى علامة معلمة في عبارة DDL، مثل عمود أو DEFAULT
تعريف تم إنشاؤه أو طريقة عرض أو دالة SQL.
الاستثناءات هي مراجع إلى علامات المعلمات في IDENTIFIER
عبارة ، والتي يمكن استخدامها لتحديد معلمات أسماء الجداول أو الأعمدة في عبارات DDL معينة. راجع عبارة IDENTIFIER.
يمكن توفير علامات المعلمات من خلال:
- Python باستخدام واجهة برمجة تطبيقات pyspark.sql.SparkSession.sql().
- Scala باستخدام واجهة برمجة تطبيقات org.apache.spark.sql.SparkSession.sql() الخاصة به.
- Java باستخدام واجهة برمجة تطبيقات org.apache.spark.sql.SparkSession.sql() الخاصة به.
علامات المعلمات المسماة
ينطبق على: Databricks Runtime 12.1 وما فوق
علامات المعلمات المسماة هي متغيرات عنصر نائب مكتوبة. يجب أن توفر واجهة برمجة التطبيقات التي تستدعي عبارة SQL أزواجا من قيمة الاسم لربط كل علامة معلمة بقيمة.
بناء الجملة
:parameter_name
المعلمات
-
مرجع إلى علامة معلمة تم توفيرها في شكل معرف غير مؤهل.
ملاحظات
يمكنك الرجوع إلى نفس علامة المعلمة عدة مرات ضمن نفس عبارة SQL. إذا لم يتم ربط أي قيمة بعلامة المعلمة ، يتم رفع خطأ UNBOUND_SQL_PARAMETER . لست مطالبا بالإشارة إلى جميع علامات المعلمات المتوفرة.
يميز السابق الإلزامي :
(النقطتين) مساحة الاسم لعلامات المعلمات المسماة عن مساحة أسماء الأعمدة ومعلمات SQL.
الأمثلة
يحدد المثال التالي اثنين من علامات المعلمات:
- لاحقا: مع
INTERVAL HOUR
القيمة 3. - x: A
DOUBLE
بقيمة 15.0
x
تتم الإشارة إليها عدة مرات، بينما later
تتم الإشارة إليها مرة واحدة.
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
التطوير
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|
// +------+
علامات المعلمات غير المسماة
ينطبق على: Databricks Runtime 13.3 وما فوق
علامات المعلمات غير المسماة هي متغيرات عنصر نائب مكتوبة. يجب أن توفر واجهة برمجة التطبيقات التي تستدعي عبارة SQL صفيفا من الوسيطات لإقران كل علامة معلمة بقيمة بالترتيب الذي تظهر به.
بناء الجملة
?
المعلمات
?
: مرجع إلى علامة معلمة تم توفيرها في شكل علامة استفهام.
ملاحظات
يستهلك كل تكرار لعلامة معلمة غير مسماة قيمة توفرها واجهة برمجة التطبيقات لاستدعاء عبارة SQL بالترتيب. إذا لم يتم ربط أي قيمة بعلامة المعلمة، يتم رفع خطأ UNBOUND_SQL_PARAMETER . لست مطالبا باستهلاك كافة القيم المتوفرة.
الأمثلة
يحدد المثال التالي ثلاث علامات معلمات:
- مع
INTERVAL HOUR
القيمة 3. - اثنان
DOUBLE
بقيمة 15.0 لكل منهما.
نظرا لأن المعلمات غير مسماة، يتم استهلاك كل قيمة مقدمة بواسطة معلمة واحدة على الأكثر.
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
التطوير
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|
// +------+