Adlandırılmış parametre işaretçilerini kullanma

Adlandırılmış parametre işaretçileri, çalışma zamanında SQL sorgularına değişken değerleri eklemenize olanak tanır. Belirli değerleri sabit kodlamak yerine, sorgu çalıştırıldığında kullanıcıların doldurduğu yazılan yer tutucuları tanımlarsınız. Bu, sorgu yeniden kullanılmasını iyileştirir, SQL eklemesini önler ve esnek, etkileşimli sorgular oluşturmayı kolaylaştırır.

Adlandırılmış parametre işaretçileri aşağıdaki Databricks yüzeylerinde çalışır:

• SQL düzenleyicisi (yeni ve eski)
• Dizüstü bilgisayarlar
• AI/BI pano veri kümesi düzenleyicisi
• Genie Spaces

Adlandırılmış parametre işaretçisi ekleme

Bir parametre eklemek için iki nokta ve ardından :parameter_name gibi bir parametre adı yazın. Bir sorguya adlandırılmış parametre işaretçisi eklediğinizde, parametre türünü ve değerini ayarlayabileceğiniz bir pencere öğesi görüntülenir. Parametre pencere öğeleriyle çalışma konusuna bakın.

Bu örnek, sabit kodlanmış bir sorguyu adlandırılmış parametre kullanacak şekilde dönüştürür.

Sorgu başlatılıyor:

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

1. 5 maddesinden WHERE silin.
2. Yerine :fare_parameter yazın. Son satır okunmalıdır fare_amount < :fare_parameter.
3. Parametre pencere öğesinin yanındaki dişli simgesine tıklayın.
4. Tür değerini Ondalık olarak ayarlayın.
5. Parametre pencere öğesine bir değer girin ve Değişiklikleri uygula'ya tıklayın.
6. Kaydet'e tıklayın.

Parametre türleri

Parametre ayarları panelinde parametre türünü ayarlayın. türü Databricks'in çalışma zamanında değeri nasıl yorumlayıp işlediğini belirler.

Tür	Açıklama
String	Serbest biçimli metin. Ters eğik çizgi, tek ve çift tırnak işaretleri otomatik olarak kaçıştır. Databricks değerin etrafına tırnak işaretleri ekler.
tamsayı	Tamsayı değeri.
Ondalık	Kesirli değerleri destekleyen sayısal değer.
Tarih	Tarih değeri. Bir takvim seçici kullanır ve varsayılan olarak geçerli tarihi kullanır.
Zaman damgası	Tarih ve saat değeri. Bir takvim seçici kullanır ve varsayılan olarak geçerli tarih ve saati kullanır.

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

Aşağıdaki örneklerde adlandırılmış parametre işaretçileri için yaygın desenler gösterilmektedir.

Tarih ekleme

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

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

IDENTIFIER Bir sütun adını parametre olarak geçirmek için işlevini kullanın. 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

Çalışma zamanında katalog, şema ve tablo belirtmek için IDENTIFIER işlevini birden çok parametreyle kullanın.

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

Bkz. IDENTIFIER madde.

Birden çok parametreyi birleştirme

Parametreleri tek bir biçimlendirilmiş dizede birleştirmek için kullanın format_string . 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

from_json Anahtar olarak parametre kullanarak JSON dizesinden bir değer ayıklamak için işlevini kullanın. a'ü :param için değer olarak değiştirmek, 1'yi döndürür.

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

Aralık oluşturma

Zaman tabanlı hesaplamalar için bir parametre değerini CAST bir INTERVAL türüne dönüştürmek için kullanın. Bkz. Aralık türü.

SELECT CAST(:param AS INTERVAL MINUTE)

.min ve .max kullanarak tarih aralığı ekleyin.

Tarih ve Zaman Damgası parametreleri bir aralık widget'ını destekler. Aralığın başlangıcına ve sonuna erişmek için .min ve .max kullanın.

SELECT * FROM samples.nyctaxi.trips
WHERE tpep_pickup_datetime
BETWEEN :date_range.min AND :date_range.max

Parametre türünü Date veya Timestamp , pencere öğesi türünü de Aralık olarak ayarlayın.

İki parametre kullanarak tarih aralığı ekleme

SELECT * FROM samples.nyctaxi.trips
WHERE tpep_pickup_datetime
BETWEEN CAST(:date_range_min AS TIMESTAMP) AND CAST(:date_range_max AS TIMESTAMP)

Toplama detay seviyesini parametrelendirme

Kullanıcı tarafından seçilen ayrıntı düzeyinde sonuçları toplamak için kullanın DATE_TRUNC . Parametre değeri olarak DAY, MONTH veya YEAR geçirin.

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

Dize olarak birden çok değer geçirme

Tek bir dize parametresi olarak geçirilen değerlerin virgülle ayrılmış bir listesine göre filtrelemek için , ARRAY_CONTAINSve SPLIT kullanınTRANSFORM. SPLIT virgülle ayrılmış dizeyi bir diziye ayrıştırıyor. TRANSFORM her öğeden boşlukları kırpıyor. ARRAY_CONTAINS tablo değerinin sonuçta elde edilen dizide görünüp görünmediğini denetler.

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

Not

Bu örnek, dize değerleri için çalışır. Diğer veri türlerini kullanmak için, öğeleri istenen türe dönüştürmek amacıyla TRANSFORM ile CAST işlemini sarmalayın.

Söz dizimi geçiş kaynağı

Sorguları bıyık söz diziminden adlandırılmış parametre işaretçilerine dönüştürürken bu tabloyu kullanın. Eski söz dizimi hakkında daha fazla bilgi için Mustache parametresi söz dizimi bölümüne bakın.

Kullanım örneği	Mustache sözdizimi	Adlandırılmış parametre söz dizimi
Tarihe göre filtrele	WHERE date_field < '{{date_param}}'	WHERE date_field < :date_param
Sayıya göre filtrele	WHERE price < {{max_price}}	WHERE price < :max_price
Dizeleri karşılaştırma	WHERE region = '{{region_param}}'	WHERE region = :region_param
Tablo belirtme	SELECT * FROM {{table_name}}	SELECT * FROM IDENTIFIER(:table) — tam üç düzeyli ad alanını kullanın
Katalog, şema ve tablo belirtme	SELECT * FROM {{catalog}}.{{schema}}.{{table}}	SELECT * FROM IDENTIFIER(:catalog \|\| '.' \|\| :schema \|\| '.' \|\| :table)
Birden çok parametreden dize biçimlendirme	"({{area_code}}) {{phone_number}}"	format_string("(%d) %d", :area_code, :phone_number)
Aralık oluşturma	SELECT INTERVAL {{p}} MINUTE	SELECT CAST(format_string("INTERVAL '%s' MINUTE", :param) AS INTERVAL MINUTE)