Databricks pencere öğeleri

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.

Pencere öğesi açılan menüleri 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. BIR SQL ambara bağlıysanız pencere öğeleri oluşturmanın tek yolu budur.

Ekle pencere öğesini düzenle'yi >seçin. Pencere öğesi ekle 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 girin. İletişim kutusunda Parametre Adı, kodunuzdaki pencere öğesine 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 öğesi adının üzerine gelerek pencere öğesine nasıl başvurabileceğinizi açıklayan bir araç ipucu görüntüleyebilirsiniz.

Pencere öğesini düzenlemek veya kaldırmak için kebap menüsünü kullanabilirsiniz:

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) başvuru arabirimi aracılığıyla yönetirsiniz.

• Tüm pencere öğesi türlerinin ilk bağımsız değişkenidir name. Bu, pencere öğesine erişmek için kullandığınız addır.
• İkinci bağımsız değişken, pencere öğesinin varsayılan ayarıdır defaultValue.
• 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 tür pencere öğeleri için text kullanılmaz.
• Son bağımsız değişken, pencere öğesi metin kutusu veya açılan menü üzerinde gösterilen etiket için isteğe bağlı bir değerdir 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"))

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

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

Python

dbutils.widgets.get("state")

dbutils.widgets.getAll()

Scala

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:

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

Bir pencere öğesini kaldırırsanız, aynı hücrede bir pencere öğesi oluşturamazsınız. Pencere öğesini 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.

Pencere öğeleri için parametre işaretçileri Databricks Runtime 15.2 ve üzeri sürümleriyle kullanılabilir. Databricks Runtime'ın önceki sürümleri, DBR 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çılan pencere öğesi 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. Pencere öğesine el ile bir tablo adı table 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
   

Databricks Runtime 15.1 ve altında pencere öğesi değerlerini kullanma

Bu bölümde Databricks Runtime 15.1 ve altındaki not defteri hücrelerine %sql Databricks pencere öğeleri değerlerini geçirme açıklanmaktadır.

1. Metin değerlerini belirtmek için pencere öğeleri oluşturun.

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. Söz dizimini kullanarak pencere öğesi değerlerini geçirin ${param} .

   SELECT *
   FROM ${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. Pencere öğesi panelinin sağ ucundaki simgeye 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 şey yeniden çalıştırılır.

3. Pencere öğelerini not defterinin en üstüne sabitlemek veya pencere öğelerini ilk hücrenin üstüne yerleştirmek için öğesine tıklayın . Ayar kullanıcı başına 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 öğesine 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, Pencere Öğesi Paneli Ayarları iletişim kutusunu açmak için tıklayın ve ardından Düzeni Sıfırla'ya tıklayın. Komut removeAll() pencere öğesi düzenini sıfırlamaz.

Panolardaki Databricks pencere öğeleri

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 X pencere öğesine ve 1 pencere öğesi Y'ye geçer10.

Sınırlamalar

Daha fazla bilgi için bkz . Bilinen sınırlamalar Databricks not defterleri .