Databricks pencere öğeleri

  • Makale

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 aşağıdaki komutu kullanın: dbutils.widgets.help()

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.

Üst bilgideki pencere öğesi

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

Pencere öğesi oluşturmak için Pencere öğesi ekle'yi 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.

pencere öğesi oluştur iletişim kutusu

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 öğesi araç ipucu

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

pencere öğesi kebap menüsü

İşlem kümesinde Databricks pencere öğelerini kullanma

Bu bölümde, işlem kümesine bağlı bir not defterinde Databricks pencere öğelerinin nasıl kullanılacağı açıklanmaktadır. SQL ambara bağlı bir not defterinde pencere öğelerini kullanmak için bkz . SQL ambarında Databricks pencere öğelerini kullanma.

Databricks pencere öğesi API'si (küme)

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 ise pencere öğesinin varsayılan ayarıdır defaultValue.
  • Üçüncü bağımsız değişken, dışındaki textchoicestüm pencere öğesi türleri içindir ve pencere öğesinin alabildiği değerlerin listesidir. 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.

Databricks pencere öğesi örneği (küme)

Her yöntemin ayrıntılı API belgelerini görmek için kullanın dbutils.widgets.help("<method-name>"). Yardım API'si tüm dillerde aynıdır. Örneğin:

dbutils.widgets.help("dropdown")

Basit bir açılan pencere öğesi oluşturun.

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

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

Pencere öğesiyle etkileşim kurma

Pencere öğesinin geçerli değerine şu çağrıyla erişebilirsiniz:

Python

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

SQL

REMOVE WIDGET state

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

Spark SQL'de pencere öğesi değerlerini kullanma (küme)

Spark SQL, sorgularda kullanılabilecek dize değişmez değerleri olarak pencere öğesi değerlerine erişir.

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 ${database}

  4. Pencere öğesine el ile bir tablo adı table girin.

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

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

Not

Genel olarak, bir not defterindeki farklı diller arasında bağımsız değişkenler geçirmek için pencere öğelerini kullanamazsınız. Python hücresinde bir pencere öğesi arg1 oluşturabilir ve aynı anda bir hücre çalıştırırsanız bunu SQL veya Scala hücresinde kullanabilirsiniz. Ancak, Tümünü Çalıştır'ı kullanırsanız veya not defterini iş olarak çalıştırırsanız bu işe yaramaz.

Geçici çözümler:

Not

SQL dize değişmez değerindeki karakterden $ kaçmak için kullanın\$. Örneğin, dizesini $1,000ifade etmek için kullanın "\$1,000". $ SQL tanımlayıcıları için karakterden kaçılamaz.

SQL ambarı üzerinde Databricks pencere öğelerini kullanma

Bu bölümde, SQL ambara bağlı bir not defterinde Databricks pencere öğelerinin nasıl kullanılacağı açıklanmaktadır. İşlem kümesine bağlı bir not defterinde pencere öğelerini kullanmak için bkz . İşlem kümesinde Databricks pencere öğelerini kullanma.

SQL ambarı üzerindeki pencere öğesi değerlerine başvurmak için , değil $paramsöz dizimini :paramkullanın. Örneğin, fare_amount adlı bir pencere öğesiniz varsa aşağıdakine benzer bir kod kullanın:

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

IDENTIFIER Tablolar, görünümler, şemalar ve sütunlar gibi nesneleri tanımlamak için anahtar sözcüğünü kullanın. Örneğin, table_name adlı pencere öğesi olarak samples.nyctaxi.tripsayarlanırsa:

SELECT * FROM IDENTIFIER(:table_name)

Ayrıntılar için bkz . IDENTIFIER yan tümcesi.

Parametre işaretçisi söz dizimi hakkında ayrıntılar için bkz . Parametre işaretçileri.

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 dişli simgesi 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.

    Pencere öğesi ayarları

    • 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 raptiye simgesi. 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 düzenle simgesipencere öğ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 simgeleri kabul etme ve iptal etme.

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

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

Örnek not defteri

Aşağıdaki not defterinde, Erişilen Komutları Çalıştır ayarının nasıl çalıştığını gösteren bir tanıtım görebilirsiniz. Pencere year öğesi ayarıyla 2014 oluşturulur ve DataFrame API'sinde ve SQL komutlarında kullanılır.

Küçük aletler

Pencere öğesinin year2007ayarını olarak değiştirdiğinizde DataFrame komutu yeniden çalıştırılır, ancak SQL komutu yeniden çalıştırılmaz.

Bu not defteri, sql ambarı değil kümeye bağlı bir not defterinde pencere öğelerinin kullanımını gösterir.

Pencere öğesi tanıtım not defteri

Not defterini alma

Panolardaki Databricks pencere öğeleri

Giriş pencere öğeleri içeren bir not defterinden pano oluşturduğunuzda, tüm pencere öğeleri panonun en üstünde 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.

Pencere öğeleri içeren pano

%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

  • Pencere öğeleri için aşağıdaki sınırlar geçerlidir:

    • Not defterinde en fazla 512 pencere öğesi oluşturulabilir.
    • Pencere öğesi adı 1024 karakterle sınırlıdır.
    • Pencere öğesi etiketi 2048 karakterle sınırlıdır.
    • Metin pencere öğesine en fazla 2048 karakter girilebilir.
    • Çoklu seçim, birleşik giriş kutusu veya açılan pencere öğesi için en fazla 1024 seçenek olabilir.

  • Koddaki pencere öğesini temizledikten veya kaldırdıktan sonra bile Tümünü Çalıştır'a bastıktan sonra pencere öğesi durumunun düzgün temizlenmediği bilinen bir sorun vardır. Böyle bir durumda, pencere öğesinin görsel durumu ile yazdırılan durumu arasında bir tutarsızlık görürsünüz. Hücreleri tek tek yeniden çalıştırmak bu sorunu atlayabilir. Bu sorunu tamamen önlemek için Databricks ipywidgets kullanmanızı önerir.

  • Zaman uyumsuz kod çalışırken pencere öğesi durumu değişeebileceği için pencere öğesi durumuna doğrudan iş parçacıkları, alt işlemler veya Yapılandırılmış Akış (foreachBatch) gibi zaman uyumsuz bağlamlarda erişmemelisiniz. Zaman uyumsuz bağlamda pencere öğesi durumuna erişmeniz gerekiyorsa, bunu bağımsız değişken olarak geçirin. Örneğin, iş parçacıkları kullanan aşağıdaki kodunuz varsa:

    import threading

def thread_func():
  # Unsafe access in a thread
  value = dbutils.widgets.get('my_widget')
  print(value)

thread = threading.Thread(target=thread_func)
thread.start()
thread.join()

    Ardından bunu şu şekilde yazmanız gerekir:

    # Access widget values outside the asynchronous context and pass them to the function
value = dbutils.widgets.get('my_widget')

def thread_func(val):
  # Use the passed value safely inside the thread
  print(val)

thread = threading.Thread(target=thread_func, args=(value,))
thread.start()
thread.join()