Databricks widget'ları

Giriş pencere öğeleri, not defterlerinize ve panolarınıza parametre eklemenize olanak tanır. Databricks kullanıcı arabiriminden veya pencere öğesi API'sini kullanarak bir pencere öğesi ekleyebilirsiniz. Pencere öğesi eklemek veya düzenlemek için not defterinde CAN EDIT izinlerine sahip olmanız gerekir.

Databricks Runtime 11.3 LTS veya üzerini çalıştırıyorsanız, Databricks not defterlerinde ipywidgets de kullanabilirsiniz.

Databricks pencere öğeleri şunlar için en iyisidir:

• Farklı parametrelerle yeniden yürütülen bir not defteri veya pano oluşturma.
• Farklı parametrelerle tek bir sorgunun sonuçlarını hızla keşfetme.

Scala, Python veya R'de pencere öğesi API'sinin belgelerini görüntülemek için şu komutu kullanın: dbutils.widgets.help(). Pencere öğeleri yardımcı programı (dbutils.widgets) belgelerine de başvurabilirsiniz.

Databricks pencere öğesi türleri

4 tür pencere öğesi vardır:

• text: Metin kutusuna bir değer girin.
• dropdown: Sağlanan değerler listesinden bir değer seçin.
• combobox: Metin ve açılan menü birleşimi. Sağlanan listeden bir değer seçin veya metin kutusuna bir değer girin.
• multiselect: Sağlanan değerler listesinden bir veya daha fazla değer seçin.

Açılan menüler ve metin kutuları not defteri araç çubuğunun hemen ardından görünür. Pencere öğeleri yalnızca dize değerlerini kabul eder.

Arabirim öğeleri oluşturma

Bu bölümde, kullanıcı arabirimini kullanarak pencere öğelerinin nasıl oluşturulacağı veya SQL büyülerini veya Python, Scala ve R için pencere öğesi API'sini kullanarak program aracılığıyla nasıl oluşturulacağı gösterilmektedir.

Kullanıcı arabirimini kullanarak pencere öğeleri oluşturma

Not defteri kullanıcı arabirimini kullanarak bir pencere öğesi oluşturun. SQL deposuna bağlıysanız, pencere öğeleri oluşturmanın tek yolu budur. Düzenle > Parametre ekle seçin.

Pencere öğesi ayarlarını düzenlemek için dişli simgesine tıklayın.

Pencere öğesi ayarları iletişim kutusunda pencere öğesi adını, isteğe bağlı etiketi, türü, parametre türünü, olası değerleri ve isteğe bağlı varsayılan değeri girebilirsiniz. İletişim kutusunda Parametre Adı, kodunuzda bu öğeye başvurmak için kullandığınız addır. Pencere Öğesi Etiketi , kullanıcı arabirimindeki pencere öğesinin üzerinde görünen isteğe bağlı bir addır.

Bir pencere öğesi oluşturduktan sonra, pencere öğesinin adına gelerek pencere öğesine nasıl referans vereceğinizi açıklayan bir araç ipucu görüntüleyebilirsiniz.

SQL, Python, R ve Scala ile pencere öğeleri oluşturma

Program aracılığıyla işlem kümesine bağlı bir not defterinde pencere öğeleri oluşturun.

Pencere öğesi API'si Scala, Python ve R'de tutarlı olacak şekilde tasarlanmıştır. SQL'deki pencere öğesi API'si biraz farklıdır ancak diğer dillerle eşdeğerdir. Pencere öğelerini Databricks Yardımcı Programları (dbutils) referans arayüzü üzerinden yönetirsiniz.

• Tüm pencere öğesi türleri için ilk bağımsız değişken name'dir. Bu, pencere öğesine erişmek için kullandığınız addır.
• İkinci bağımsız değişken defaultValue, pencere öğesinin varsayılan ayarıdır.
• Tüm pencere öğesi türleri (hariç text) için üçüncü bağımsız değişken, pencere öğesinin alabildiği değerlerin listesidir choices. Bu bağımsız değişken text türündeki pencere öğeleri için kullanılmaz.
• Son bağımsız değişken, pencere öğesi metin kutusu veya açılır menü üzerinde gösterilen etiket için isteğe bağlı bir değer olan label'dır.

Piton

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

Scala programlama dili

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

R

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

SQL

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

Pencere öğesi panelinden pencere öğesiyle etkileşim kurun.

Pencere öğesinin geçerli değerine erişebilir veya tüm pencere öğelerinin eşlemesini alabilirsiniz:

Piton

dbutils.widgets.get("state")

dbutils.widgets.getAll()

Scala programlama dili

dbutils.widgets.get("state")

dbutils.widgets.getAll()

R

dbutils.widgets.get("state")

SQL

SELECT :state

Son olarak, bir pencere öğesini veya not defterindeki tüm pencere öğelerini kaldırabilirsiniz:

Piton

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

Scala programlama dili

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

R

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

Bir pencere öğesini kaldırırsanız, aynı hücrede bir pencere öğesi oluşturamazsınız. Widget'ı başka bir hücrede oluşturmanız gerekir.

Spark SQL ve SQL Ambarı'nda pencere öğesi değerlerini kullanma

Spark SQL ve SQL Ambarı, parametre işaretçilerini kullanarak pencere öğesi değerlerine erişmektedir. Parametre işaretçileri, sağlanan değerleri SQL deyimlerinden açıkça ayırarak kodunuzu SQL ekleme saldırılarına karşı korur.

Widget'ler için parametre belirleyicileri Databricks Runtime 15.2 ve ilerisi sürümlerde kullanılabilir. Databricks Runtime'ın önceki sürümleri Databricks Runtime 15.1 ve altı için eski söz dizimini kullanmalıdır.

Not defterlerini etkileşimli olarak yürütürken Spark SQL'den herhangi bir dilde tanımlanan pencere öğelerine erişebilirsiniz. Aşağıdaki iş akışını göz önünde bulundurun:

1. Geçerli katalogdaki tüm veritabanlarının açılır listesini oluşturun.

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

2. Tablo adını el ile belirtmek için bir metin pencere öğesi oluşturun:

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

3. Veritabanındaki tüm tabloları görmek için bir SQL sorgusu çalıştırın (açılan listeden seçili):

   SHOW TABLES IN IDENTIFIER(:database)
   

   Not

   Dizeleri veritabanları, tablolar, görünümler, işlevler, sütunlar ve alanlar için adlar gibi nesne tanımlayıcıları olarak ayrıştırmak için SQL IDENTIFIER() yan tümcesini kullanmanız gerekir.

4. table widget'ine manuel olarak bir tablo adı girin.

5. Filtre değeri belirtmek için bir metin pencere öğesi oluşturun:

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

6. Sorgunun içeriğini düzenlemeye gerek kalmadan tablonun içeriğini önizleme:

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

Arabirim öğesi ayarlarını yapılandırma

Yeni bir değer seçildiğinde pencere öğelerinin davranışını, pencere öğesi panelinin her zaman not defterinin en üstüne sabitlenip sabitlenmediğini yapılandırabilir ve not defterindeki pencere öğelerinin düzenini değiştirebilirsiniz.

1. Araç Takımı panelinin sağ ucundaki tıklayın.

2. Açılır Pencere Öğesi Paneli Ayarları iletişim kutusunda pencere öğesinin yürütme davranışını seçin.

   

   • Not Defterini Çalıştır: Her yeni değer seçildiğinde not defterinin tamamı yeniden çalıştırılır.
   • Erişilen Komutları Çalıştır: Her yeni değer seçildiğinde, yalnızca söz konusu pencere öğesinin değerlerini alan hücreler yeniden çalıştırılır. Bu, pencere öğesi oluşturduğunuzda varsayılan ayardır. SQL hücreleri bu yapılandırmada yeniden çalıştırılmaz.
   • Hiçbir Şey Yapma: Her yeni değer seçildiğinde, hiçbir işlem yeniden çalıştırılmaz.

3. Pencere öğelerini not defterinin en üstüne sabitlemek veya ilk hücrenin üstüne yerleştirmek için öğesine tıklayın. Ayar, her kullanıcı için ayrı ayrı kaydedilir. Varsayılan davranışa sıfırlamak için thumbtack simgesine yeniden tıklayın.

4. Not defterleri için CAN MANAGE izniniz varsa, öğesine tıklayarak pencere öğesi düzenini yapılandırabilirsiniz. Her pencere öğesinin sırası ve boyutu özelleştirilebilir. Değişikliklerinizi kaydetmek veya kapatmak için tıklayın.

   Pencere öğesi düzeni not defteriyle birlikte kaydedilir. Pencere öğesi düzenini varsayılan yapılandırmadan değiştirirseniz, yeni pencere öğeleri alfabetik olarak eklenmez.

5. Pencere öğesi düzenini varsayılan düzene ve boyuta sıfırlamak için tıklayarak Pencere Öğesi Paneli Ayarları iletişim kutusunu açın ve ardından Düzeni Sıfırla'ya tıklayın. Komut removeAll() pencere öğesi düzenini sıfırlamaz.

Panolardaki Databricks araçları

Giriş pencere öğeleri içeren bir not defterinden pano oluşturduğunuzda, tüm pencere öğeleri en üstte görüntülenir. Sunu modunda, bir pencere öğesinin değerini her güncelleştirdiğinizde, not defterini yeniden çalıştırmak ve panonuzu yeni değerlerle güncelleştirmek için Güncelleştir düğmesine tıklayabilirsiniz.

%run ile Databricks pencere öğelerini kullan

Pencere öğeleri içeren bir not defteri çalıştırırsanız , belirtilen not defteri pencere öğesinin varsayılan değerleriyle çalıştırılır.

Not defteri bir kümeye (SQL ambarı değil) bağlıysa, değerleri pencere öğelerine de geçirebilirsiniz. Örneğin:

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

Bu örnek, belirtilen not defterini çalıştırır ve 10'yi X pencere öğesine, 1'yi Y pencere öğesine geçirir.

Sınırlamalar

Daha fazla bilgi için Databricks not defterlerinin bilinen sınırlamaları'na bakın.