SQL parametreleri

Yerel/SQL düzenleyicisinde SQL sorgularınıza değişkenler ekleyerek SQL şablonları oluşturabilirsiniz. Bu değişkenler, sorgudaki değişkenin değerini değiştirmek için kullanabileceğiniz filtre widget'ları oluşturacaktır. Ayrıca, soru yüklendiğinde bu değerlerin değişkenlere eklenmesi için sorunuzun URL'sine parametreler ekleyebilirsiniz.

Değişkenleri tanımlama

Yerel sorgunuzda {{variable_name}} yazmak, variable_name adlı bir değişken oluşturur.

Alan Filtreleri, özel bir filtre türü, biraz farklı bir sözdizimine sahiptir.

Bu örnek, category adlı bir Metin değişkenini tanımlar:

SELECT
  count(*)
FROM
  products
WHERE
  category = {{category}}

Patrona değişkeni okuyacak ve sorguya, kişilerin cat değişkenine tırnak işaretleriyle eklenen değeri değiştirmek için kullanabileceği bir filtre widget'ı ekleyecektir. Yani birisi filtre widget'ına "Gizmo" yazarsa, Patrona'nın çalıştıracağı sorgu şu olacaktır:

SELECT
  count(*)
FROM
  products
WHERE
  category = 'Gizmo'

Yerel bir MongoDB sorgusu yazıyorsanız, sorgunuz cat değişkeni match yan tümcesinin içinde tanımlanmış olarak buna benzer görünecektir.

[{ "$match": { "category": "{{cat}}" } }]

SQL değişkenlerini ayarlama

Bir SQL değişkenini bir değere ayarlamak için:

• Filtre widget'ına bir değer girin ve soruyu yeniden çalıştırın veya
• URL'ye bir parametre ekleyin ve sayfayı yükleyin.

URL'ye bir değer eklemek için şu sözdizimini izleyin:

?variable_name=value

Örneğin, {{cat}} değişkenini "Gizmo" değerine ayarlamak için URL'niz şöyle görünecektir:

https://patrona.example.com/question/42-eg-question?cat=Gizmo

Birden fazla değişken ayarlamak için parametreleri ampersand (&) ile ayırın:

https://patrona.example.com/question/42-eg-question?cat=Gizmo&maxprice=50

SQL değişken türleri

Bir değişken tanımladığınızda, Değişkenler yan paneli görünecektir. Bir değişken için bir tür ayarlayabilirsiniz, bu da Patrona'nın sunduğu filtre widget'ının türünü değiştirir.

Dört tür değişken vardır:

• Metin: düz bir giriş kutusu.
• Sayı: düz bir giriş kutusu.
• Tarih: basit bir tarih seçici. Bir aralık belirtmek gibi daha ifade edici bir tarih seçici istiyorsanız, Alan Filtresi kullanmanız gerekecektir.
• Alan Filtresi: eşlenen alana bağlı olarak farklı filtre widget'ları.

Son değişken türü, Alan Filtresi, özeldir; bir arama kutusu, bir değerler açılır menüsü veya bir tarih aralığı belirtmenize olanak tanıyan dinamik bir tarih seçici gibi "akıllı" filtre widget'ları oluşturmanıza olanak tanır.

Sorguya birden fazla değişken ekleyebilir ve Patrona soruya birden fazla filtre widget'ı ekleyecektir. Birden fazla filtre widget'ınız olduğunda, bir filtre widget'ına tıklayıp sürükleyerek sırasını değiştirebilirsiniz.

Alan Filtresi değişken türü

Bir değişkeni Alan Filtresi türüne ayarlamak, değişkeni mevcut veritabanındaki herhangi bir tablodaki bir alana eşlemenize olanak tanır. Alan filtreleri, o alan için mantıklı olan "akıllı" bir filtre widget'ı oluşturmanıza olanak tanır.

Alan Filtresi değişkenleri SQL'deki bir WHERE yan tümcesi veya MongoDB'deki bir $match yan tümcesi içinde kullanılmalıdır.

Alan Filtresi uyumlu türler

Alan Filtreleri YALNIZCA aşağıdaki alan türleriyle çalışır:

• Kategori
• Varlık Adı
• Varlık Anahtarı
• Yabancı Anahtar
• Şehir
• Eyalet
• Posta Kodu

Alan ayrıca bir tarih veya zaman damgası olabilir, bu da Tablo Meta Verileri içinde "Semantik tür yok" olarak bırakılabilir.

Değişken türünü "Alan Filtresi" olarak ayarladığınızda, Patrona Eşlenecek alan ve Filtre widget türünü ayarlama seçeneği sunacaktır. Filtre widget türü için mevcut seçenekler, alanın türüne bağlıdır. Örneğin, bir Kategori türü alanına eşleştirirseniz, "Kategori" veya Yok seçeneklerini görürsünüz. Bir Tarih Alanına eşleştirirseniz, Yok, Ay ve yıl, Çeyrek ve yıl, Tek tarih, Tarih aralığı veya Tarih filtresi seçeneklerini görürsünüz.

Bir filtre widget'ını görüntüleme seçeneğini görmüyorsanız, eşlenen alanın yukarıdaki türlerden birine ayarlandığından emin olun ve ardından Patrona'nın alanın değerlerini tarayıp önbelleğe alması için Yönetici Panelinin "Veritabanları" bölümünden veritabanınızı manuel olarak senkronize etmeyi deneyin.

Alan Filtresini yukarıda listelenen uyumlu türlerden biri olmayan bir alana eşlemek istiyorsanız, bir Yöneticinin o sütun için alan türünü değiştirmesi gerekecektir. Bkz. meta veri düzenleme.

Alan Filtresi sözdizimi

Diyelim ki People tablosunu eyalete göre filtreleyen bir Alan Filtresi oluşturmak istiyorsunuz ve kişilerin aynı anda birden fazla eyalet seçebilmesini istiyorsunuz. İşte sorgu:

Alan Filtrelerinin sözdizimi, Metin, Sayı veya Tarih değişkeninden farklıdır.

SELECT
  *
FROM
  PEOPLE
WHERE
  {{state}}

Ardından, yan panelde "Alan Filtresi" değişken türünü seçin ve değişkeninizi hangi alana eşleyeceğinizi seçin (bu durumda State).

Sütun ve operatörün (örneğin =) eksikliğine dikkat edin. Alan Filtrelerini bu şekilde yapılandırmanızın nedeni, Patrona'nın sizin için kod oluşturduğu durumları ele almaktır. Örneğin, birinin filtre widget'ında birden fazla değer seçtiği veya bir tarih aralığı seçtiği durumları ele almak için. Alan Filtreleri ile oluşturulan SQL'i kontrol edemezsiniz, bu nedenle daha fazla kontrol gerekiyorsa, bir (veya daha fazla) Metin, Sayı veya Tarih değişkeni kullanmalısınız.

Bir MongoDB yerel sorgu örneği şöyle görünebilir:

[{ "$match": "{{date_var}}" }]

Daha ayrıntılı bir kılavuz için Alan Filtreleri: SQL soruları için akıllı filtre widget'ları oluşturma bölümüne göz atın.

BigQuery ve Oracle'da alan filtreleri

SQL lehçenizin seçtiğiniz veritabanıyla eşleştiğinden emin olun. Tabloların sorguda nasıl tırnak içine alındığıyla ilgili yaygın sorunlar:

Veritabanı	Lehçe özelliği	Örnek
BigQuery	Şemalar ve tablolar ters tırnak işaretiyle tırnak içine alınmalıdır.	FROM `dataset.table`
Oracle	Şemalar ve tablolar çift tırnak içinde tırnak içine alınmalıdır.	FROM schema.table

Daha fazla yardım için bkz. SQL hata mesajlarını giderme.

Farklı türde filtre widget'ları oluşturma

Bir Alan Filtresi widget'ı oluşturduğunuzda Patrona'nın görüntülediği filtre widget'ı türü, Patrona'daki Bu alanda filtreleme adlı bir alan ayarına bağlıdır. Yöneticiler bu alan seçeneğini şu şekilde ayarlayabilir:

• Düz giriş kutusu
• Arama kutusu
• Tüm değerlerin listesi (açılır menü olarak da bilinir)

Tarih alanları ya basit bir tarih filtresine (Tarih değişkenleri için) ya da dinamik bir tarih seçiciye (bir tarih alanına eşlenen Alan Filtreleri için) sahip olacaktır.

Belirli bir alan için filtre widget'ını değiştirmek istiyorsanız, bir Yöneticiden Tablo Meta Verileri içindeki o alanı güncellemesini ve istenen "Bu alanda filtreleme" seçeneğini ayarlamasını istemeniz gerekecektir.

Düz giriş kutusuyla filtre widget'ı

Basit bir Metin veya Sayı değişkeni oluşturun. Ek olarak, Bu alanda filtreleme değeri "Düz giriş kutusu" olarak ayarlanmış bir alanla Alan Filtresi kullanabilirsiniz.

Not: SQL enjeksiyon saldırılarına karşı korunmak için Patrona, Arama kutusundaki her şeyi bir dizeye dönüştürür. Joker karakterler kullanmak istiyorsanız, öğrenme makalemize göz atın.

Arama kutusuyla filtre widget'ı

• Sorgunuza bir SQL değişkeni ekleyin.
• Değişken türünü Alan Filtresi olarak ayarlayın.
• Eşlenecek alanı, Bu alanda filtreleme seçeneği "Arama kutusu" olarak ayarlanmış "Kategori" türünde bir alana ayarlayın.

Açılır menü ve arama ile filtre widget'ı

Arama ve tüm değerlerin listesi ile bir açılır menü oluşturmak için şunları yapmanız gerekir:

• Sorgunuza bir SQL değişkeni ekleyin.
• Değişken türünü Alan Filtresi olarak ayarlayın.
• Eşlenecek alanı, Bu alanda filtreleme seçeneği "Tüm değerlerin listesi" olarak ayarlanmış "Kategori" türünde bir alana ayarlayın.
• Filtre widget türünü "Kategori" olarak ayarlayın.

Açılır menü oluşturmak istediğiniz alan, Bu alanda filtreleme seçeneği "Tüm değerlerin listesi" olarak ayarlanmış "Kategori" türünde değilse, bir Yöneticinin o alan için ayarları güncellemesi gerekecektir. Örneğin, bir E-posta alanı gibi uyumsuz bir alan türü için bir açılır menü oluşturmak istiyorsanız, bir yöneticinin o alan türünü "Kategori" olarak değiştirmesi, Bu alanda filtreleme seçeneğini Tüm değerlerin listesi olarak ayarlaması ve ardından o alan için değerleri yeniden taraması gerekecektir.

Ancak, o sütunda görüntülenecek çok fazla farklı değer varsa, Patrona bunun yerine basitçe bir arama kutusu görüntüleyecektir. Yani, çok fazla e-posta adresiniz varsa, yine de bir arama kutusu alabilirsiniz. Açılır menü widget'ları, seçilecek küçük bir değer kümesi olduğunda (örneğin, elli ABD eyaleti gibi) daha iyi çalışır.

Alan filtresi sınırlamaları

Bir Alan Filtresi değişkeni ayarlamaya çalışırken sizi zorlayabilecek bazı şeyler.

Alan Filtreleri tablo takma adlarıyla çalışmaz

Birleştirmeler veya CTE'ler için tablo takma adları kullanan sorgularda alan filtrelerinden değer seçemezsiniz.

Bunun nedeni, alan filtrelerinin eşlenen alana dayalı SQL oluşturmasıdır; Patrona SQL'i ayrıştırmaz, bu nedenle bir takma adın neye atıfta bulunduğunu anlayamaz. Sorgunuzun karmaşıklığına bağlı olarak, üç geçici çözüm seçeneğiniz vardır.

1. Tam tablo adlarını kullanın.
2. CTE'leri alt sorgularla değiştirin.
3. Veritabanınızda bir görünüm oluşturun ve sorgunuzun temeli olarak görünümü kullanın.

Alan Filtreleri sorguya dahil edilen alanlara bağlı olmalıdır

Ana sorgunuz, Alan Filtresi değişkeninizin işaret ettiği tüm tabloları bilmelidir, aksi takdirde bir SQL sözdizimi hatası alırsınız. Örneğin, ana sorgunuzun şu şekilde bir alan filtresi içerdiğini varsayalım:

SELECT
  *
FROM
  ORDERS
WHERE
  {{ product_category }}

Diyelim ki {{ product_category }} değişkeni Products tablosunu kullanan başka bir soruya atıfta bulunur. Alan filtresinin çalışması için, ana sorgunuza Products ile bir birleştirme eklemeniz gerekecektir.

SELECT
  *
FROM
  ORDERS
  JOIN PRODUCTS ON ORDERS.product_id = PRODUCTS.id
WHERE
  {{ product_category }}

Açılır listeleri ve arama kutusu değerlerini özelleştirme

Metin ve Alan filtresi değişkenleriyle, bir açılır liste veya arama kutusu içeren bir filtre kullanırken kişilerin hangi değerleri seçebileceğini Patrona'ya söyleyebilirsiniz.

1. Yerel düzenleyicide, çift parantez içinde bir {{variable}} ekleyin.
2. Yan panel açılmazsa, ilgili simgeye tıklayarak Değişkenler yan panelini açabilirsiniz.
3. Ayarlar sekmesinde, Değişken türünü "Metin" veya "Alan Filtresi" olarak ayarlayın.
4. Yan panelde, Kullanıcılar bu değişkeni nasıl filtrelemeli? bölümüne gidin. Açılır liste veya Arama kutusu seçeneklerinden birini seçin.
5. Seçtiğiniz seçeneğin yanındaki Düzenle seçeneğine tıklayın.
6. Patrona, değerlerin nereden gelmesi gerektiğini seçebileceğiniz bir modal açacaktır.

Şunları seçebilirsiniz:

• Bağlı alanlardan. Alan filtresi değişken türünü seçtiyseniz, bağlı alanı kullanma seçeneğiniz de olacaktır.
• Başka bir model veya sorudan. Bu seçeneği seçerseniz, bir model veya soru seçmeniz, ardından Patrona'nın o açılır liste veya arama kutusu için değerleri sağlamak için kullanacağı model veya sorudan bir alan seçmeniz gerekecektir. Örneğin, açılır listenin bir hesabın olabileceği farklı planları listelemesini istiyorsanız, oluşturduğunuz bir "Hesap" modelini seçebilir ve o açılır listeyi çalıştırmak için "Plan" alanını seçebilirsiniz. Açılır liste, ardından Hesaplar modelindeki "Plan" sütununda görünen tüm farklı plan seçeneklerini listeleyecektir.
• Özel liste. Her öğeyi bir satıra girin. İstediğiniz herhangi bir dize değerini girebilirsiniz.

Ayrıca bir pano filtresinin seçilebilir değerlerini değiştirebilirsiniz.

Filtre widget'ında varsayılan bir değer ayarlama

Değişkenler yan panelinde, değişkeniniz için varsayılan bir değer ayarlayabilirsiniz. Bu değer, varsayılan olarak ilgili filtre widget'ına eklenir (filtre widget'ı boş olsa bile). Varsayılanı geçersiz kılmak için filtre widget'ına yeni bir değer eklemeniz gerekecektir.

Sorguda karmaşık varsayılan değerler ayarlama

Ayrıca, isteğe bağlı bir parametrenin son parantezleri içine yorum sözdizimi ekleyerek doğrudan sorgunuzda varsayılan değerler tanımlayabilirsiniz.

WHERE column = [[ {{ your_parameter }} --]] your_default_value

Yorumu your_parametera bir değer geçtiğinizde "etkinleştirilir".

Bu, karmaşık varsayılan değerler tanımlarken kullanışlıdır (örneğin, varsayılan değeriniz CURRENT_DATE gibi bir işlevse). İşte CURRENT_DATE kullanarak bir Tarih filtresinin varsayılan değerini geçerli tarihe ayarlayan bir PostgreSQL örneği:

SELECT
  *
FROM
  orders
WHERE
  DATE(created_at) = [[ {{dateOfCreation}} --]] CURRENT_DATE

Değişkene bir değer geçerseniz, WHERE yan tümcesi, varsayılan CURRENT_DATE işlevini yorumlayan yorum sözdizimini içerecek şekilde çalışır.

Metni yorumlamak için kullanılan hash (--), kullandığınız veritabanına özgü yorum sözdizimi ile değiştirilmelidir.

Filtre widget'ı için bir değer gerektirme

Değişken ayarları yan panelinde, Her zaman bir değer gerektir seçeneğini açabilirsiniz. Bunu açarsanız:

• Varsayılan bir değer girmeniz gerekecektir.
• Varsayılan değer, kodunuzdaki isteğe bağlı sözdizimini (örneğin, isteğe bağlı bir WHERE yan tümcesi) geçersiz kılacaktır. Filtreye bir değer geçilmezse, Patrona sorguyu varsayılan değeri kullanarak çalıştıracaktır. Patrona'nın çalıştıracağı SQL'i önizlemek için düzenleyicideki Göz simgesine tıklayın.

Değişkenleri isteğe bağlı hale getirme

Bir sorguda bir yan tümceyi isteğe bağlı hale getirebilirsiniz. Örneğin, bir SQL değişkeni içeren isteğe bağlı bir WHERE yan tümcesi oluşturabilirsiniz, böylece değişkene (filtrede veya URL aracılığıyla) bir değer sağlanmazsa, sorgu yine de WHERE yan tümcesi yokmuş gibi çalışır.

Yerel sorgunuzda bir değişkeni isteğe bağlı hale getirmek için, {{variable}} içeren tüm yan tümceyi [[ .. ]] parantezleri içine alın. Birisi variable için filtre widget'ına bir değer girerse, Patrona şablondaki yan tümceyi yerleştirir; aksi takdirde Patrona yan tümceyi yokmuş gibi görmezden gelir ve sorguyu çalıştırır.

Bu örnekte, cat için bir değer verilmezse, sorgu sadece products tablosundaki tüm satırları seçecektir. Ancak cat bir değere sahipse, örneğin "Widget", sorgu yalnızca Widget türünde bir kategoriye sahip ürünleri alacaktır:

SELECT
  count(*)
FROM
  products
[[WHERE category = {{cat}}]]

SQL'iniz isteğe bağlı yan tümce olmadan da çalışabilmelidir

Parantez içindeki yan tümceye değer geçilmediğinde SQL'inizin hala geçerli olduğundan emin olmanız gerekir.

Örneğin, parantez içindeki yan tümceye WHERE anahtar kelimesini dahil etmemek, cat için bir değer verilmediğinde bir hataya neden olacaktır:

-- bu bir hataya neden olacaktır:
SELECT
  count(*)
FROM
  products
WHERE
  [[category = {{cat}}]]

Bunun nedeni, cat için bir değer verilmediğinde, Patrona'nın [[ ]] içindeki yan tümce yokmuş gibi SQL'i çalıştırmaya çalışmasıdır:

SELECT
  count(*)
FROM
  products
WHERE

bu geçerli bir SQL sorgusu değildir.

Bunun yerine, tüm WHERE yan tümcesini [[ ]] içine alın:

SELECT
  count(*)
FROM
  products
[[WHERE
  category = {{cat}}]]

cat için bir değer verilmediğinde, Patrona sadece şunu çalıştıracaktır:

SELECT
  count(*)
FROM
  products

bu hala geçerli bir sorgudur.

Birden fazla isteğe bağlı yan tümce kullanırken en az bir WHERE gereklidir

Birden fazla isteğe bağlı yan tümce kullanmak için, en az bir normal WHERE yan tümcesi eklemeli ve ardından her biri AND ile başlayan isteğe bağlı yan tümceler eklemelisiniz:

SELECT
  count(*)
FROM
  products
WHERE
  TRUE
  [[AND id = {{id}}]]
  [[AND {{category}}]]

Son yan tümce bir Alan filtresi kullanır (yan tümcede sütunun eksikliğine dikkat edin). Bir alan filtresi kullanırken, sorgudaki sütunu hariç tutmanız gerekir; değişkeni yan panelde eşlemeniz gerekir.

MongoDB'de isteğe bağlı değişkenler

MongoDB kullanıyorsanız, bir yan tümceyi şu şekilde isteğe bağlı hale getirebilirsiniz:

[
    [[{
        "$match": { "category": "{{cat}}" }
    },]]
    {
        "$count": "Total"
    }
]

Or with multiple optional filters:

[
    [[{ "$match": "{{cat}}" },]]
    [[{ "$match": { "price": { "$gt": "{{minprice}}" } } },]]
    {
        "$count": "Total"
    }
]

Connecting a SQL question to a dashboard filter

In order for a saved SQL/native question to be usable with a dashboard filter, the question must contain at least one variable.

The kind of dashboard filter that can be used with the SQL question depends on the field. For example, if you have a field filter called {{var}} and you map it to a State field, you can map a Location dashboard filter to your SQL question. In this example, you'd create a new dashboard (or go to an existing dashboard), click the Pencil icon to enter Dashboard edit mode, add the SQL question that contains your State Field Filter variable, add a new dashboard filter (or edit an existing Location filter), then click the dropdown on the SQL question card to see the State Field Filter.

If you add a Date variable to the question, then it's only possible to use the dashboard filter option Single Date. So if you are trying to use one of the other Time options on the dashboard, you'll need to change the variable to a Field Filter variable and map it to a date column.

More on Dashboard filters.

Further reading

• Create filter widgets for charts using SQL variables.
• Field Filters: create smart filter widgets for SQL questions.
• Troubleshooting SQL.
• Troubleshooting filters.
• Dashboard filters.