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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

واجهة برمجة تطبيقات عنصر واجهة مستخدم Databricks (نظام المجموعة)

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

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

مثال على عنصر واجهة مستخدم Databricks (نظام المجموعة)

للاطلاع على وثائق واجهة برمجة التطبيقات التفصيلية لكل أسلوب، استخدم dbutils.widgets.help("<method-name>"). واجهة برمجة تطبيقات التعليمات متطابقة في جميع اللغات. على سبيل المثال:

dbutils.widgets.help("dropdown")

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

Python

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

SQL

SELECT "${state}"

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

Python

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

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

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

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

يمكنك الوصول إلى عناصر واجهة المستخدم المعرفة بأي لغة من 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 ${database}
   

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

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

   SELECT *
   FROM ${database}.${table}
   LIMIT 100
   

إشعار

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

الحلول:

• بالنسبة لدفاتر الملاحظات التي لا تخلط اللغات، يمكنك إنشاء دفتر ملاحظات لكل لغة وتمرير الوسيطات عند تشغيل دفتر الملاحظات.
  • يمكنك الوصول إلى عنصر واجهة المستخدم باستخدام spark.sql() مكالمة. على سبيل المثال، في Python: spark.sql("select getArgument('arg1')").take(1)[0][0].

إشعار

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

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

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

للإشارة إلى قيم عنصر واجهة المستخدم على مستودع SQL، استخدم بناء الجملة :param، وليس $param. على سبيل المثال، إذا كان لديك عنصر واجهة مستخدم يسمى fare_amount، فاستخدم تعليمة برمجية مشابهة لما يلي:

SELECT * FROM samples.nyctaxi.trips WHERE fare_amount < :fare_amount

IDENTIFIER استخدم الكلمة الأساسية لتعريف كائنات مثل الجداول وطرق العرض والمخططات والأعمدة. على سبيل المثال، إذا تم تعيين عنصر واجهة المستخدم المسمى table_name إلى samples.nyctaxi.trips:

SELECT * FROM IDENTIFIER(:table_name)

للحصول على التفاصيل، راجع عبارة IDENTIFIER.

للحصول على تفاصيل حول بناء جملة علامة المعلمة، راجع علامات المعلمات.

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

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

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

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

   

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

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

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

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

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.

القيود

• تنطبق الحدود التالية على عناصر واجهة المستخدم:
  • يمكن إنشاء 512 عنصر واجهة مستخدم كحد أقصى في دفتر ملاحظات.
  • يقتصر اسم عنصر واجهة المستخدم على 1024 حرفا.
  • تقتصر تسمية عنصر واجهة المستخدم على 2048 حرفا.
  • يمكن إدخال 2048 حرفا كحد أقصى إلى عنصر واجهة مستخدم نصي.
  • يمكن أن يكون هناك 1024 اختيارا كحد أقصى لمربع متعدد التحديد أو مربع تحرير وسرد أو عنصر واجهة مستخدم منسدلة.
• هناك مشكلة معروفة حيث قد لا تكون حالة عنصر واجهة المستخدم واضحة بشكل صحيح بعد الضغط على تشغيل الكل، حتى بعد مسح أو إزالة عنصر واجهة المستخدم في التعليمات البرمجية. إذا حدث ذلك، فسترى تعارضا بين الحالة المرئية لعنصر واجهة المستخدم وحالته المطبوعة. قد تتجاوز إعادة تشغيل الخلايا بشكل فردي هذه المشكلة. لتجنب هذه المشكلة بالكامل، توصي Databricks باستخدام ipywidgets.