Sorgu parametreleriyle çalışma

Bu makalede Azure Databricks SQL düzenleyicisinde sorgu parametreleriyle çalışma açıklanmaktadır.

Sorgu parametreleri, çalışma zamanına değişken değerleri ekleyerek sorgularınızı daha dinamik ve esnek hale getirmenizi sağlar. Sorgularınıza belirli değerleri sabit kodlamak yerine, verileri filtrelemek veya kullanıcı girişine göre çıktıyı değiştirmek için parametreler tanımlayabilirsiniz. Bu yaklaşım sorgunun yeniden kullanılmasını iyileştirir, SQL eklemesini engelleyerek güvenliği artırır ve farklı veri senaryolarının daha verimli işlenmesini sağlar.

Adlandırılmış parametre işaretçisi söz dizimi

Adlandırılmış parametre işaretçileri, yazılan yer tutucu değişkenleridir. Azure Databricks kullanıcı arabiriminin aşağıdaki bölümlerine sorgu yazmak için bu söz dizimini kullanın:

• SQL düzenleyicisi

• Notebooks

• AI/BI pano veri kümesi düzenleyicisi

• AI/BI Genie alanları (Genel Önizleme)

SQL sorgularınıza parametre eklemek için iki nokta üst üste ve ardından gibi :parameter_namebir parametre adı yazın. Sorguya adlandırılmış parametre işaretçisi eklediğinizde, kullanıcı arabiriminde bir pencere öğesi görüntülenir. Parametre türünü ve adını düzenlemek için pencere öğesini kullanabilirsiniz.

Sorguya adlandırılmış parametre işaretçisi ekleme

Bu örnek, aşağıdaki sorguya bir parametre işaretçisi ekler:

SELECT
  trip_distance,
  fare_amount
FROM
  samples.nyctaxi.trips
WHERE
  fare_amount < 5

Bu sorgu yalnızca beş doların altındaki ücret tutarlarını içeren bir veri kümesi döndürür. Sabit kodlanmış değer (5) yerine parametre kullanmak üzere sorguyu düzenlemek için aşağıdaki adımları kullanın.

1. Sorgudan 5 sayısını silin.
2. İki nokta üst üste (:) ve ardından dizesini fare_parameteryazın. Güncelleştirilmiş sorgunuzun son satırı şunu içermelidir: fare_amount < :fare_parameter.
3. Parametre pencere öğesinin yanındaki dişli simgesine tıklayın. İletişim kutusunda aşağıdaki alanlar gösterilir:
   • Anahtar Sözcük: Sorgudaki parametreyi temsil eden anahtar sözcük. Bu alanı düzenleyemezsiniz. Anahtar sözcüğü değiştirmek için, SQL sorgusundaki işaretçiyi düzenleyin.
   • Başlık: Pencere öğesinin üzerinde görünen başlık. Varsayılan olarak, başlık anahtar sözcükle aynıdır.
   • Tür: Desteklenen türler Metin, Sayı, Açılan Liste, Tarih, Tarih ve Saat ve Tarih ve Saat 'tir (Saniye ile). Varsayılan değer Metin'dir.
4. İletişim kutusunda Tür'leri Sayı olarak değiştirin.
5. Parametre pencere öğesine bir sayı girin ve Değişiklikleri uygula'ya tıklayın.
6. Sorguyu kaydetmek için Kaydet’e tıklayın.

Adlandırılmış parametre söz dizimi örnekleri

Aşağıdaki örneklerde parametreler için bazı yaygın kullanım örnekleri gösterilmiştir.

Tarih ekleme

Aşağıdaki örnek, sorgu sonuçlarını belirli bir tarihten sonraki kayıtlara sınırlayan bir Date parametresini içerir.

SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  sum(o_totalprice) AS `Total Price`
FROM
  samples.tpch.orders
WHERE
  o_orderdate > :date_param
GROUP BY
  1,
  2

Sayı ekleme

Aşağıdaki örnek, sonuçları alanın sağlanan parametre değerinden o_total_price büyük olduğu kayıtlara sınırlayan bir Number parametresini içerir.

SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  o_totalprice AS Price
FROM
  samples.tpch.orders
WHERE
  o_totalprice > :num_param

Alan adı ekleme

Aşağıdaki örnekte, field_param çalışma zamanında sorgu için eşik değeri sağlamak üzere işleviyle birlikte IDENTIFIER kullanılır. Parametre değeri, sorguda kullanılan tablodan bir sütun adı olmalıdır.

SELECT
  *
FROM
  samples.tpch.orders
WHERE
  IDENTIFIER(:field_param) < 10000

Veritabanı nesneleri ekleme

Aşağıdaki örnek üç parametre oluşturur: catalog, schemave table.

SELECT
  *
FROM
  IDENTIFIER(:catalog || '.' || :schema || '.' || :table)

Bkz. IDENTIFIER yan tümcesi.

Birden çok parametreyi birleştirme

Parametreleri diğer SQL işlevlerine ekleyebilirsiniz. Bu örnek, görüntüleyicinin bir çalışan unvanı ve bir numara kimliği seçmesine olanak tanır. Sorgu, iki dizeyi format_string birleştirmek ve eşleşen satırları filtrelemek için işlevini kullanır. Bkz. format_string işlevi.

SELECT
  o_orderkey,
  o_clerk
FROM
  samples.tpch.orders
WHERE
  o_clerk LIKE format_string('%s%s', :title, :emp_number)

JSON dizeleriyle çalışma

JSON dizesinden öznitelik ayıklamak için parametreleri kullanabilirsiniz. Aşağıdaki örnek, JSON dizesini from_json yapı değerine dönüştürmek için işlevini kullanır. () parametresininparam değeri olarak dizeyi a değiştirerek 1 özniteliğini döndürür.

SELECT
  from_json('{"a": 1}', 'map<string, int>') [:param]

Aralık oluşturma

Türü INTERVAL bir zaman aralığını temsil eder ve zamana dayalı aritmetik ve işlemler gerçekleştirmenizi sağlar. Aşağıdaki örnek, bir işlevin içindeki format_string parametresini içerir ve ardından aralık türü olarak türlenir. Sonuçta elde edilen INTERVAL değer, sorguda zamana dayalı hesaplamalar veya filtreleme için kullanılabilir.

Tüm ayrıntılar ve söz dizimi için bkz . INTERVAL türü .

SELECT CAST(format_string("INTERVAL '%s' MINUTE", :param) AS INTERVAL MINUTE)

Tarih aralığı ekleme

Aşağıdaki örnekte belirli bir zaman dilimindeki kayıtları seçmek için parametreli tarih aralığının nasıl ekleneceği gösterilmektedir.

SELECT * FROM samples.nyctaxi.trips
WHERE tpep_pickup_datetime
BETWEEN :start_date AND :end_date

Toplamaları güne, aya veya yıla göre parametreleştirme

Aşağıdaki örnek, taksi yolculuğu verilerini parametreli ayrıntı düzeyinde toplar. DATE_TRUNC işlevi, değeri , MONTHveya YEARgibi DAYparametre değerine göre :date_granularity kesertpep_pickup_datetime. Kesilen tarih olarak date_rollup diğer ad kullanılır ve yan tümcesinde GROUP BY kullanılır.

SELECT DATE_TRUNC(:date_granularity, tpep_pickup_datetime) AS
  date_rollup,
  COUNT(*) AS total_trips
FROM samples.nyctaxi.trips
GROUP BY date_rollup

Tek bir sorguda birden çok değer kullanma

Aşağıdaki örnek, bir değer listesini filtrelemek için işlevini kullanır ARRAY_CONTAINS . TRANSFORMve SPLIT işlevleri, birden çok virgülle ayrılmış değerin dize parametresi olarak geçirilmesini sağlar.

Değer :list_parameter , virgülle ayrılmış değerlerin listesini alır. İşlev bu SPLIT listeyi ayrıştırarak virgülle ayrılmış değerleri bir diziye böler. işlevi, TRANSFORM herhangi bir boşluk kaldırarak dizideki her öğeyi dönüştürür. İşlev, ARRAY_CONTAINS tablosundaki değerin dropoff_zip trips olarak list_parametergeçirilen değerler dizisinde bulunup bulunmadığını denetler.

SELECT * FROM samples.nyctaxi.trips WHERE
  array_contains(
    TRANSFORM(SPLIT(:list_parameter, ','), s -> TRIM(s)),
    dropoff_zip
  )

Not

Bu örnek, dize değerleri için çalışır. Tamsayı listesi gibi diğer veri türlerinin sorgusunu değiştirmek için işlemi bir CAST işlemle kaydırarak TRANSFORM dize değerlerini istenen veri türüne dönüştürün.

Söz dizimi değişiklikleri

Aşağıdaki tabloda parametreler için yaygın kullanım örnekleri, özgün Databricks SQL bıyık söz dizimi ve adlandırılmış parametre işaretçisi söz dizimi kullanılarak eşdeğer söz dizimi gösterilmektedir.

Parametre kullanım örneği	Bıyık parametresi söz dizimi	Adlandırılmış parametre işaretçisi söz dizimi
Yalnızca belirtilen tarihten önce veri yükleme	WHERE date_field < '{{date_param}}' Tarih parametresinin ve küme ayraçlarının çevresine tırnak işaretleri eklemeniz gerekir.	WHERE date_field < :date_param
Yalnızca belirtilen sayısal değerden küçük verileri yükleme	WHERE price < {{max_price}}	WHERE price < :max_price
İki dizeyi karşılaştırma	WHERE region = {{region_param}}	WHERE region = :region_param
Sorguda kullanılan tabloyu belirtme	SELECT * FROM {{table_name}}	SELECT * FROM IDENTIFIER(:table) Bir kullanıcı bu parametreyi girdiğinde, tabloyu tanımlamak için tam üç düzeyli ad alanını kullanmalıdır.
Sorguda kullanılan kataloğu, şemayı ve tabloyu bağımsız olarak belirtin	SELECT * FROM {{catalog}}.{{schema}}.{{table}}	SELECT * FROM IDENTIFIER(:catalog \|\| '.' \|\| :schema \|\| '.' \|\| :table)
Parametreleri daha uzun, biçimlendirilmiş bir dizede şablon olarak kullanma	"({{area_code}}) {{phone_number}}" Parametre değerleri otomatik olarak dize olarak birleştirilir.	format_string("(%d)%d, :area_code, :p hone_number) Tam bir örnek için bkz . Birden çok parametreyi birleştirme.
Aralık oluşturma	SELECT INTERVAL {{p}} MINUTE	SELECT CAST(format_string("INTERVAL '%s' MINUTE", :param) AS INTERVAL MINUTE)

Bıyık parametresi söz dizimi

Önemli

Aşağıdaki bölümler, yalnızca SQL düzenleyicisinde kullanabileceğiniz sorgu söz dizimi için geçerlidir. Başka bir deyişle, bu söz dizimini kullanarak bir sorguyu kopyalayıp not defteri veya AI/BI pano veri kümesi düzenleyicisi gibi başka bir Azure Databricks arabirimine yapıştırırsanız, sorgunun hatasız çalışmadan önce adlandırılmış parametre işaretçilerini kullanacak şekilde el ile ayarlanması gerekir.

SQL düzenleyicisinde, çift küme ayraçları arasındaki tüm dizeler {{ }} sorgu parametresi olarak değerlendirilir. Parametre değerini ayarladığınız sonuçlar bölmesinin üzerinde bir pencere öğesi görüntülenir. Azure Databricks genellikle adlandırılmış parametre işaretçilerinin kullanılmasını önerir ancak bazı işlevler yalnızca bıyık parametresi söz dizimi kullanılarak desteklenir.

Aşağıdaki işlevler için bıyık parametresi söz dizimini kullanın:

• Eski pano filtreleri
• Birden çok değer açılan parametresi
• Tarih aralıkları
• Sorgu tabanlı açılan parametreler

Bıyık parametresi ekleme

1. Cmd + I yazın. Parametre metin giriş işaretine eklenir ve Parametre Ekle iletişim kutusu görüntülenir.
   • Anahtar Sözcük: Sorgudaki parametreyi temsil eden anahtar sözcük.
   • Başlık: Pencere öğesinin üzerinde görünen başlık. Varsayılan olarak, başlık anahtar sözcükle aynıdır.
   • Tür: Desteklenen türler Metin, Sayı, Tarih, Tarih ve Saat, Tarih ve Saat (Saniye ile), Açılan Liste ve Sorgu Tabanlı Açılan Liste'dir. Varsayılan değer Metin'dir.
2. Anahtar sözcüğünü girin, isteğe bağlı olarak başlığı geçersiz kılın ve parametre türünü seçin.
3. Parametre Ekle'ye tıklayın.
4. Parametre pencere öğesinde parametre değerini ayarlayın.
5. Değişiklikleri Uygula'ya tıklayın.
6. Kaydet'e tıklayın.

Alternatif olarak, çift küme ayracı {{ }} yazın ve ayarları düzenlemek için parametre pencere öğesinin yanındaki dişli simgesine tıklayın.

Sorguyu farklı bir parametre değeriyle yeniden çalıştırmak için, pencere öğesine değeri girin ve Değişiklikleri Uygula'ya tıklayın.

Sorgu parametresini düzenleme

Bir parametreyi düzenlemek için parametre pencere öğesinin yanındaki dişli simgesine tıklayın. Sorguya sahip olmayan kullanıcıların parametreyi değiştirmesini önlemek için Yalnızca Sonuçları Göster'e tıklayın. <Keyword> Parametre iletişim kutusu görüntülenir.

Sorgu parametresini kaldırma

Sorgu parametresini kaldırmak için parametreyi sorgunuzdan silin. Parametre pencere öğesi kaybolur ve statik değerleri kullanarak sorgunuzu yeniden yazabilirsiniz.

Parametrelerin sırasını değiştirme

Parametrelerin gösterilme sırasını değiştirmek için, her parametreyi tıklayıp istediğiniz konuma sürükleyebilirsiniz.

Sorgu parametresi türleri

• Metin
• Numara
• Açılan Liste
• Sorgu Tabanlı Açılan Liste
• Tarih ve Saat

Metin

Giriş olarak bir dize alır. Ters eğik çizgi, tek ve çift tırnak işaretlerinden kaçınılır ve Azure Databricks bu parametreye tırnak işaretleri ekler. Örneğin, gibi mr's Li"s bir dize şunun kullanımına 'mr\'s Li\"s' bir örnek olarak dönüştürülür:

SELECT * FROM users WHERE name={{ text_param }}

Sayı

Girişi olarak bir sayı alır. Bunu kullanma örneği

SELECT * FROM users WHERE age={{ number_param }}

Açılan Liste

Sorgu çalıştırırken olası parametre değerlerinin kapsamını kısıtlamak için Açılan Liste parametre türünü kullanın. Örneğin: SELECT * FROM users WHERE name='{{ dropdown_param }}'. Parametre ayarları panelinden seçildiğinde, her değeri yeni bir satırla ayırarak izin verilen değerleri girdiğiniz bir metin kutusu görüntülenir. Açılan listeler metin parametreleridir. Açılan Listenizde tarih veya tarih ve saatleri kullanmak için, bunları veri kaynağınızın gerektirdiği biçimde girin. Dizelerden kaçılmaz. Tek değerli veya çok değerli açılan liste arasında seçim yapabilirsiniz.

• Tek değer: Parametrenin etrafındaki tek tırnak işaretleri gereklidir.
• Çoklu değer: Birden çok değere izin ver seçeneğini değiştirin. Tırnak açılan listesinde, parametrelerin girilmiş (tırnak işareti olmadan) bırakılıp bırakılmayacağını veya parametrelerin tek veya çift tırnak işaretleri ile kaydırılıp kaydırılmayacağını seçin. Tırnak işaretleri seçerseniz parametrenin çevresine tırnak işareti eklemeniz gerekmez.

Sorgunuzda anahtar sözcüğü kullanmak IN için yan tümcenizi WHERE değiştirin.

SELECT ...
FROM   ...
WHERE field IN ( {{ Multi Select Parameter }} )

Çok seçimli parametre pencere öğesi, veritabanına birden çok değer geçirmenizi sağlar. Tırnak parametresi için Çift Tırnak İşareti seçeneğini belirlerseniz sorgunuz aşağıdaki biçimi yansıtır:WHERE IN ("value1", "value2", "value3")

Sorgu Tabanlı Açılan Liste

Sorgunun sonucunu girişi olarak alır. Açılan Liste parametresiyle aynı davranışa sahiptir. Databricks SQL açılan listesi sorgusunu başka bir sorguda giriş olarak kullanmak için kaydetmeniz gerekir.

1. Ayarlar panelindeki Tür altında Sorgu Tabanlı Açılan liste'ye tıklayın.
2. Sorgu alanına tıklayın ve bir sorgu seçin. Hedef sorgunuz çok sayıda kayıt döndürürse performans düşer.

Hedef sorgunuz birden fazla sütun döndürürse Databricks SQL ilk sütunu kullanır. Hedef sorgunuz ve sütunları döndürürsename, Databricks SQL parametre seçim pencere öğesini sütunuyla name doldurur, ancak sorguyu ilişkili valueile yürütür.value

Örneğin, aşağıdaki sorgunun tablodaki verileri döndürdüğü varsayın.

SELECT user_uuid AS 'value', username AS 'name'
FROM users

değer	Adı
1001	John Smith
1002	Jane Doe
1003	Ahmet Tablolar

Azure Databricks sorguyu çalıştırdığında veritabanına geçirilen değer 1001, 1002 veya 1003 olabilir.

Tarih ve Saat

Azure Databricks'in tarih ve zaman damgası değerlerini parametreleştirmek için zaman aralıklarının parametreleştirilmesini basitleştirme seçenekleri de dahil olmak üzere çeşitli seçenekleri vardır. Farklı duyarlık seçeneklerinden birini belirleyin:

Seçenek	Duyarlık	Tür
Date	gün	DATE
Tarih ve Saat	dakika	TIMESTAMP
Tarih ve Saat (saniye ile)	saniye	TIMESTAMP

Aralık parametresi seçeneğini belirtirken ve .end sonekleri tarafından .start belirlenen iki parametre oluşturursunuz. Tüm seçenekler parametreleri sorgunuza dize değişmez değerleri olarak geçirir; Azure Databricks, tarih ve saat değerlerini tek tırnak içine (') sarmalamanızı gerektirir. Örneğin:

-- Date parameter
SELECT *
FROM usage_logs
WHERE date = '{{ date_param }}'

-- Date and Time Range parameter
SELECT *
FROM usage_logs
WHERE modified_time > '{{ date_range.start }}' and modified_time < '{{ date_range.end }}'

Tarih parametreleri, takvim toplama arabirimini kullanır ve varsayılan olarak geçerli tarih ve saati kullanır.

Not

Tarih Aralığı parametresi yalnızca türdeki sütunlar DATE için doğru sonuçları döndürür. Sütunlar için TIMESTAMP Tarih ve Saat Aralığı seçeneklerinden birini kullanın.

Dinamik tarih ve tarih aralığı değerleri

Sorgunuza bir tarih veya tarih aralığı parametresi eklediğinizde, seçim pencere öğesi mavi şimşek simgesini gösterir. , , , last weekthis weekyesterdaylast month, veya last yeargibi todaydinamik değerleri görüntülemek için buna tıklayın. Bu değerler dinamik olarak güncelleştirilir.

Önemli

Dinamik tarihler ve tarih aralıkları zamanlanmış sorgularla uyumlu değildir.

Panolarda sorgu parametrelerini kullanma

İsteğe bağlı olarak, sorgular parametreleri veya statik değerleri kullanabilir. Bir panoya parametreli sorguyu temel alan bir görselleştirme eklendiğinde, görselleştirme aşağıdakilerden birini kullanacak şekilde yapılandırılabilir:

• Pencere öğesi parametresi

  Pencere öğesi parametreleri panodaki tek bir görselleştirmeye özeldir, görselleştirme panelinde görünür ve belirtilen parametre değerleri yalnızca görselleştirmenin temel alınan sorgusu için geçerlidir.

• Pano parametresi

  Pano parametreleri birden çok görselleştirmeye uygulanabilir. Bir panoya parametreli sorguyu temel alan bir görselleştirme eklediğinizde, parametre varsayılan olarak pano parametresi olarak eklenir. Pano parametreleri bir panodaki bir veya daha fazla görselleştirme için yapılandırılır ve panonun en üstünde görünür. Pano parametresi için belirtilen parametre değerleri, söz konusu pano parametresini yeniden kullanan görselleştirmeler için geçerlidir. Bir panonun birden çok parametresi olabilir ve bunların her biri bazı görselleştirmeler için geçerli olabilir ve diğerleri için geçerli değildir.

• Statik değer

  Statik değerler, değişikliklere yanıt veren bir parametre yerine kullanılır. Statik değerler, parametre yerine bir değeri sabit kodla oluşturmanıza olanak sağlar. Parametresini daha önce göründüğü panodan veya pencere öğesinden "kaybolur" yapar.

Parametreli sorgu içeren bir görselleştirme eklediğinizde, uygun kalem simgesine tıklayarak görselleştirme sorgusunda parametrenin başlığını ve kaynağını seçebilirsiniz. Anahtar sözcüğü ve varsayılan değeri de seçebilirsiniz. Bkz. Parametre özellikleri.

Panoya görselleştirme ekledikten sonra, bir pano pencere öğesinin sağ üst kısmındaki kebap menüsüne ve ardından Pencere öğesi ayarlarını değiştir'e tıklayarak parametre eşleme arabirimine erişin.

Parametre özellikleri

• Başlık: Panonuzda değer seçicinin yanında görünen görünen ad. Varsayılan olarak Anahtar Sözcük parametresini kullanır. Düzenlemek için kalem simgesine tıklayın. Değer seçici gizlendiğinden, statik pano parametreleri için başlıklar görüntülenmez. Değer Kaynağınız olarak Statik değer'i seçerseniz, Başlık alanı gri görünür.

• Anahtar Sözcük: Temel sorgudaki bu parametre için dize değişmez değeri. Panonuz beklenen sonuçları döndürmezse bu hata ayıklama için kullanışlıdır.

• Varsayılan Değer: Başka bir değer belirtilmezse kullanılan değerdir. Bunu sorgu ekranından değiştirmek için sorguyu istediğiniz parametre değeriyle çalıştırın ve Kaydet düğmesine tıklayın.

• Değer Kaynağı: Parametre değerinin kaynağı. Kaynak seçmek için kalem simgesine tıklayın.

  • Yeni pano parametresi: Yeni bir pano düzeyi parametresi oluşturun. Bu, panonuzda tek bir yerde bir parametre değeri ayarlamanıza ve bunu birden çok görselleştirmeye eşlemenize olanak tanır.
  • Mevcut pano parametresi: Parametreyi mevcut bir pano parametresiyle eşleyin. Önceden var olan pano parametresini belirtmeniz gerekir.
  • Pencere öğesi parametresi: Pano pencere öğesi içinde bir değer seçici görüntüler. Bu, pencere öğeleri arasında paylaşılmayan tek seferlik parametreler için kullanışlıdır.
  • Statik değer: Diğer pencere öğelerinde kullanılan değerlerden bağımsız olarak pencere öğesi için statik bir değer seçin. Statik olarak eşlenmiş parametre değerleri, panonun herhangi bir yerinde bir değer seçici görüntülemez ve bu daha kompakttır. Bu, belirli parametrelerin sık değişmesi beklenmediği durumlarda panodaki kullanıcı arabirimini karmaşık hale getirmek zorunda kalmadan sorgu parametrelerinin esnekliğinden yararlanmanızı sağlar.

  

Sık Sorulan Sorular (SSS)

• Aynı parametreyi tek bir sorguda birden çok kez yeniden kullanabilir miyim?
• Tek bir sorguda birden çok parametre kullanabilir miyim?

Aynı parametreyi tek bir sorguda birden çok kez yeniden kullanabilir miyim?

Evet. Küme ayraçlarında aynı tanımlayıcıyı kullanın. Bu örnekte parametresi iki {{org_id}} kez kullanılır.

SELECT {{org_id}}, count(0)
FROM queries
WHERE org_id = {{org_id}}

Tek bir sorguda birden çok parametre kullanabilir miyim?

Evet. Her parametre için benzersiz bir ad kullanın. Bu örnekte iki parametre kullanılır: {{org_id}} ve {{start_date}}.

SELECT count(0)
FROM queries
WHERE org_id = {{org_id}} AND created_at > '{{start_date}}'