علامات المعلمات

علامات المعلمات هي متغيرات عنصر نائب مكتوبة مسماة أو غير مسماة تستخدم لتوفير القيم من واجهة برمجة التطبيقات التي تستدعي عبارة 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

المعلمات

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

المقالات ذات الصلة

• pyspark.sql.SparkSession.sql()
• org.apache.spark.sql.SparkSession.sql()
• تنفيذ فوري
• تعيين متغير