مشاركة عبر

عناصر واجهة مستخدم Databricks

  • مقالة

تسمح لك عناصر واجهة مستخدم الإدخال بإضافة معلمات إلى دفاتر الملاحظات ولوحات المعلومات. يمكنك إضافة عنصر واجهة مستخدم من واجهة مستخدم Databricks أو استخدام واجهة برمجة تطبيقات عنصر واجهة المستخدم. لإضافة عنصر واجهة مستخدم أو تحريره، يجب أن يكون لديك أذونات CAN EDIT على دفتر الملاحظات.

إذا كنت تقوم بتشغيل Databricks Runtime 11.3 LTS أو أعلى، يمكنك أيضا استخدام ipywidgets في دفاتر ملاحظات Databricks.

عناصر واجهة مستخدم Databricks هي الأفضل ل:

  • إنشاء دفتر ملاحظات أو لوحة معلومات يتم إعادة تنفيذها باستخدام معلمات مختلفة.
  • استكشاف نتائج استعلام واحد بسرعة باستخدام معلمات مختلفة.

لعرض وثائق واجهة برمجة تطبيقات عنصر واجهة المستخدم في Scala أو Python أو R، استخدم الأمر التالي: dbutils.widgets.help()

أنواع عناصر واجهة مستخدم Databricks

هناك 4 أنواع من عناصر واجهة المستخدم:

  • text: إدخال قيمة في مربع نص.
  • dropdown: حدد قيمة من قائمة القيم المتوفرة.
  • combobox: تركيبة من النص والمنسدل. حدد قيمة من قائمة متوفرة أو إدخال قيمة في مربع النص.
  • multiselect: حدد قيمة واحدة أو أكثر من قائمة القيم المتوفرة.

تظهر القوائم المنسدلة ومربعات النص الخاصة بعناصر واجهة المستخدم مباشرة بعد شريط أدوات دفتر الملاحظات. تقبل عناصر واجهة المستخدم قيم السلسلة فقط.

عنصر واجهة المستخدم في الرأس

إنشاء عناصر واجهة مستخدم

يوضح لك هذا القسم كيفية إنشاء عناصر واجهة المستخدم باستخدام واجهة المستخدم أو برمجيا باستخدام سحر SQL أو واجهة برمجة تطبيقات واجهة المستخدم ل Python وSc scala وR.

إنشاء عناصر واجهة المستخدم باستخدام واجهة المستخدم

إنشاء عنصر واجهة مستخدم باستخدام واجهة مستخدم دفتر الملاحظات. إذا كنت متصلا بمستودع SQL، فهذه هي الطريقة الوحيدة التي يمكنك من خلالها إنشاء عناصر واجهة مستخدم.

حدد تحرير > إضافة عنصر واجهة مستخدم. في مربع الحوار إضافة عنصر واجهة مستخدم ، أدخل اسم عنصر واجهة المستخدم، والتسمية الاختيارية، والنوع، ونوع المعلمة، والقيم المحتملة، والقيمة الافتراضية الاختيارية. في مربع الحوار، اسم المعلمة هو الاسم الذي تستخدمه للإشارة إلى عنصر واجهة المستخدم في التعليمات البرمجية الخاصة بك. تسمية عنصر واجهة المستخدم هو اسم اختياري يظهر فوق عنصر واجهة المستخدم.

مربع حوار إنشاء عنصر واجهة مستخدم

بعد إنشاء عنصر واجهة مستخدم، يمكنك تمرير الماوس فوق اسم عنصر واجهة المستخدم لعرض تلميح أداة يصف كيفية الرجوع إلى عنصر واجهة المستخدم.

تلميح أداة عنصر واجهة المستخدم

يمكنك استخدام قائمة الكباب لتحرير عنصر واجهة المستخدم أو إزالته:

قائمة كباب عنصر واجهة المستخدم

إنشاء عناصر واجهة مستخدم باستخدام SQL وPython وR وSc scala

إنشاء عناصر واجهة مستخدم برمجيا في دفتر ملاحظات مرفق بمجموعة حساب.

تم تصميم واجهة برمجة تطبيقات عنصر واجهة المستخدم لتكون متسقة في Scala وPython وR. واجهة برمجة تطبيقات عنصر واجهة المستخدم في SQL مختلفة قليلا ولكنها مكافئة للغات الأخرى. يمكنك إدارة عناصر واجهة المستخدم من خلال واجهة مرجع Databricks Utilities (dbutils).

  • الوسيطة الأولى لجميع أنواع عناصر واجهة المستخدم هي name. هذا هو الاسم الذي تستخدمه للوصول إلى عنصر واجهة المستخدم.
  • الوسيطة الثانية هي defaultValue، إعداد عنصر واجهة المستخدم الافتراضي.
  • الوسيطة الثالثة لجميع أنواع عناصر واجهة المستخدم (باستثناء text) هي choices، قائمة بالقيم التي يمكن أن يأخذها عنصر واجهة المستخدم. لا يتم استخدام هذه الوسيطة لعناصر text واجهة مستخدم النوع.
  • الوسيطة الأخيرة هي label، وهي قيمة اختيارية للتسمية المعروضة عبر مربع نص عنصر واجهة المستخدم أو القائمة المنسدلة.

Python

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

Scala

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

R

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

SQL

CREATE WIDGET DROPDOWN state DEFAULT "CA" CHOICES SELECT * FROM (VALUES ("CA"), ("IL"), ("MI"), ("NY"), ("OR"), ("VA"))

التفاعل مع عنصر واجهة المستخدم من لوحة عنصر واجهة المستخدم.

التفاعل مع عنصر واجهة المستخدم

يمكنك الوصول إلى القيمة الحالية لعن طريق واجهة المستخدم أو الحصول على تعيين لجميع عناصر واجهة المستخدم:

Python

dbutils.widgets.get("state")

dbutils.widgets.getAll()

Scala

dbutils.widgets.get("state")

dbutils.widgets.getAll()

R

dbutils.widgets.get("state")

SQL

SELECT :state

وأخيرا، يمكنك إزالة عنصر واجهة مستخدم أو جميع عناصر واجهة المستخدم في دفتر ملاحظات:

Python

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

Scala

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

R

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

إذا قمت بإزالة عنصر واجهة مستخدم، فلا يمكنك إنشاء عنصر واجهة مستخدم في الخلية نفسها. يجب إنشاء عنصر واجهة المستخدم في خلية أخرى.

استخدام قيم عنصر واجهة المستخدم في Spark SQL ومستودع SQL

تصل Spark SQL وSQL Warehouse إلى قيم عنصر واجهة المستخدم باستخدام علامات المعلمات. تحمي علامات المعلمات التعليمات البرمجية الخاصة بك من هجمات حقن SQL عن طريق فصل القيم المقدمة بوضوح عن عبارات SQL.

تتوفر علامات المعلمات لعناصر واجهة المستخدم في Databricks Runtime 15.2 وما فوق. يجب أن تستخدم الإصدارات السابقة من Databricks Runtime بناء الجملة القديم ل DBR 15.1 والإصدارات أدناه.

يمكنك الوصول إلى عناصر واجهة المستخدم المعرفة بأي لغة من Spark SQL أثناء تنفيذ دفاتر الملاحظات بشكل تفاعلي. ضع في اعتبارك سير العمل التالي:

  1. إنشاء عنصر واجهة مستخدم منسدلة لكافة قواعد البيانات في الكتالوج الحالي:

    dbutils.widgets.dropdown("database", "default", [database[0] for database in spark.catalog.listDatabases()])

  2. إنشاء عنصر واجهة مستخدم نصي لتحديد اسم جدول يدويا:

    dbutils.widgets.text("table", "")

  3. قم بتشغيل استعلام SQL لمشاهدة جميع الجداول في قاعدة بيانات (محددة من القائمة المنسدلة):

    SHOW TABLES IN IDENTIFIER(:database)

    إشعار

    يجب استخدام عبارة SQL IDENTIFIER() لتحليل السلاسل كمعرفات عناصر مثل أسماء قواعد البيانات والجداول وطرق العرض والوظائف والأعمدة والحقول.

  4. أدخل اسم جدول يدويا في table عنصر واجهة المستخدم.

  5. إنشاء عنصر واجهة مستخدم نصي لتحديد قيمة عامل تصفية:

    dbutils.widgets.text("filter_value", "")

  6. معاينة محتويات جدول دون الحاجة إلى تحرير محتويات الاستعلام:

    SELECT *
FROM IDENTIFIER(:database || '.' || :table)
WHERE col == :filter_value
LIMIT 100

استخدام قيم عنصر واجهة المستخدم في Databricks Runtime 15.1 وما دونه

يصف هذا القسم كيفية تمرير قيم عناصر واجهة المستخدم Databricks إلى %sql خلايا دفتر الملاحظات في Databricks Runtime 15.1 وما دونه.

  1. إنشاء عناصر واجهة مستخدم لتحديد قيم نصية.

Python

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

Scala

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

R

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

SQL

 CREATE WIDGET TEXT database DEFAULT ""
 CREATE WIDGET TEXT table DEFAULT ""
 CREATE WIDGET TEXT filter_value DEFAULT "100"

  1. تمرير قيم عنصر واجهة المستخدم باستخدام بناء الجملة ${param} .

    SELECT *
FROM ${database}.${table}
WHERE col == ${filter_value}
LIMIT 100

إشعار

للهروب من $ الحرف في سلسلة SQL حرفية، استخدم \$. على سبيل المثال، للتعبير عن السلسلة $1,000، استخدم "\$1,000". $ لا يمكن إلغاء الحرف لمعرفات SQL.

تكوين إعدادات عنصر واجهة المستخدم

يمكنك تكوين سلوك عناصر واجهة المستخدم عند تحديد قيمة جديدة، سواء كانت لوحة عنصر واجهة المستخدم مثبتة دائما في أعلى دفتر الملاحظات، وتغيير تخطيط عناصر واجهة المستخدم في دفتر الملاحظات.

  1. انقر فوق الأيقونة أيقونة الترس الموجودة في الطرف الأيسر من لوحة عنصر واجهة المستخدم.

  2. في مربع الحوار إعدادات لوحة عنصر واجهة المستخدم المنبثق، اختر سلوك تنفيذ عنصر واجهة المستخدم.

    إعدادات عنصر واجهة المستخدم

    • تشغيل دفتر الملاحظات: في كل مرة يتم فيها تحديد قيمة جديدة، تتم إعادة تشغيل دفتر الملاحظات بأكمله.
    • تشغيل الأوامر التي تم الوصول إليها: في كل مرة يتم فيها تحديد قيمة جديدة، يتم إعادة تشغيل الخلايا التي تسترد قيم عنصر واجهة المستخدم المعينة فقط. هذا هو الإعداد الافتراضي عند إنشاء عنصر واجهة مستخدم. لا تتم إعادة تشغيل خلايا SQL في هذا التكوين.
    • لا تفعل شيئا: في كل مرة يتم فيها تحديد قيمة جديدة، لا يتم إعادة تشغيل أي شيء.

  3. لتثبيت عناصر واجهة المستخدم في أعلى دفتر الملاحظات أو لوضع عناصر واجهة المستخدم فوق الخلية الأولى، انقر فوق أيقونة تثبيت. يتم حفظ الإعداد على أساس كل مستخدم. انقر فوق أيقونة thumbtack مرة أخرى لإعادة التعيين إلى السلوك الافتراضي.

  4. إذا كان لديك إذن CAN MANAGE لدفاتر الملاحظات، يمكنك تكوين تخطيط عنصر واجهة المستخدم بالنقر فوق أيقونة Edit. يمكن تخصيص ترتيب وحجم كل عنصر واجهة مستخدم. لحفظ التغييرات أو تجاهلها، انقر فوق قبول الأيقونات وإلغاءها.

    يتم حفظ تخطيط عنصر واجهة المستخدم مع دفتر الملاحظات. إذا قمت بتغيير تخطيط عنصر واجهة المستخدم من التكوين الافتراضي، فلن تتم إضافة عناصر واجهة مستخدم جديدة أبجديا.

  5. لإعادة تعيين تخطيط عنصر واجهة المستخدم إلى ترتيب وحجم افتراضيين، انقر أيقونة الترسلفتح مربع الحوار إعدادات لوحة عنصر واجهة المستخدم ثم انقر فوق إعادة تعيين التخطيط. لا يعيد removeAll() الأمر تعيين تخطيط عنصر واجهة المستخدم.

مثال لدفتر الملاحظات

يوضح دفتر الملاحظات التالي كيفية عمل إعداد تشغيل الأوامر التي تم الوصول إليها. year يتم إنشاء عنصر واجهة المستخدم مع الإعداد 2014 ويتم استخدامه في واجهة برمجة تطبيقات DataFrame والأوامر SQL.

عناصر واجهة مستخدم

عند تغيير إعداد year عنصر واجهة المستخدم إلى 2007، يتم إعادة تشغيل الأمر DataFrame، ولكن لا يتم إعادة تشغيل أمر SQL.

يوضح دفتر الملاحظات هذا استخدام عناصر واجهة المستخدم في دفتر ملاحظات مرفق بمجموعة، وليس مستودع SQL.

دفتر ملاحظات العرض التوضيحي لعناصر واجهة المستخدم

الحصول على دفتر الملاحظات

عناصر واجهة مستخدم Databricks في لوحات المعلومات

عند إنشاء لوحة معلومات من دفتر ملاحظات مع عناصر واجهة مستخدم الإدخال، يتم عرض جميع عناصر واجهة المستخدم في الأعلى. في وضع العرض التقديمي، في كل مرة تقوم فيها بتحديث قيمة عنصر واجهة المستخدم، يمكنك النقر فوق الزر تحديث لإعادة تشغيل دفتر الملاحظات وتحديث لوحة المعلومات بقيم جديدة.

لوحة المعلومات مع عناصر واجهة المستخدم

استخدام عناصر واجهة مستخدم Databricks مع ٪run

إذا قمت بتشغيل دفتر ملاحظات يحتوي على عناصر واجهة مستخدم، يتم تشغيل دفتر الملاحظات المحدد بالقيم الافتراضية لعن الأداة.

إذا كان دفتر الملاحظات مرفقا بمجموعة (وليس مستودع SQL)، يمكنك أيضا تمرير القيم إلى عناصر واجهة المستخدم. على سبيل المثال:

%run /path/to/notebook $X="10" $Y="1"

يقوم هذا المثال بتشغيل دفتر الملاحظات المحدد ويمرر 10 إلى عنصر واجهة المستخدم X وإلى 1 عنصر واجهة المستخدم Y.

القيود

راجع القيود المعروفة دفاتر ملاحظات Databricks لمزيد من المعلومات.