Compass Parametreleri

Compass kayıtları, dinamik değerler alabilmek için {{parametre_adi}} sözdizimiyle parametre tanımlamayı destekler. Aynı sorguyu farklı tarih aralıkları, makine kimlikleri veya hat seçimleri için yeniden yazmak yerine tek kayıt + dashboard üzerinden değer geçirme modeli kullanılır.

Bu sayfa parametrelerin nasıl yazıldığını, veri kaynağına göre nasıl yorumlandığını, Display Info / Parameter Settings panelinde nasıl yapılandırıldığını ve Cartography / dashboard tarafından nasıl beslendiğini açıklar.

flowchart LR
    A["Compass Sorgu<br/>&#123;&#123;hat_id&#125;&#125;"] --> B["Kayıt Paneli<br/>Parameter Type + Default"]
    B --> C["Cartography Widget<br/>Filter / Tag / GlobalVar"]
    C --> D["Horizon / Atlas<br/>Dashboard Filtresi"]
    D -- "Çalıştırma anında değer" --> A

1. Sözdizimi — `{{parametre_adi}}`

Kural	Açıklama
Açma / kapama	Çift süslü parantez: `{{` ... `}}`
İzin verilen karakterler	Harf (`A-Z`, `a-z`), rakam (`0-9`) ve alt çizgi (`_`). Türkçe karakter, boşluk veya tire kullanılamaz
Büyük / küçük harf	Duyarlıdır — `{{Hat_Id}}` ile `{{hat_id}}` farklı parametrelerdir
Tırnak kullanımı	Tırnak içine alınmaz — backend kendi dialektinin güvenli yer-tutucusunu üretir
Tekrar kullanım	Aynı parametre, sorgunun farklı yerlerinde defalarca yazılabilir; backend bunları akıllıca işler
Maksimum uzunluk	Pratik bir sınır yoktur ama isimleri kısa ve anlamlı tutun (`start_date`, `hat_id`)

Tırnaksız yazın — aksi halde sessizce 0 satır döner

Compass placeholder'ları kesinlikle tırnaksız yazılır:

✅ Doğru	❌ Yanlış
`WHERE hat_id = {{hat_id}}`	`WHERE hat_id = '{{hat_id}}'`
`WHERE plant = {{plant_code}}`	`WHERE plant = "{{plant_code}}"`

Tek tırnak içinde yazılırsa sorgu, dialekte göre WHERE hat_id = '$1' (PostgreSQL) veya WHERE hat_id = '?' (MySQL) gibi literal string'e dönüşür ve 0 satır döner. Hata mesajı verilmez — sessiz hatadır.

2. Veri Kaynağına Göre Davranış

Pirivision backend her dialekt için farklı yer-tutucu üretir. Yazdığınız sözdizimi {{name}} ile aynı kalır; çevirme işlemini Pirivision yapar.

2.1. PostgreSQL — `$1, $2, ...`

{{hat_id}} → $1. Aynı parametre tekrar geçtiğinde aynı $N indeksi yeniden kullanılır:

SELECT *
FROM   sensor_zaman_serisi s
JOIN   makineler m ON m.hat_id = {{hat_id}}   -- $1
WHERE  s.hat_id = {{hat_id}}                          -- yine $1, yeni argüman değil
ORDER  BY ts DESC;

Avantaj	Açıklama
SQL Injection güvenli	`pq` driver değeri prepared statement olarak escape eder
Tip dönüşümü	String parametreyi tarih/sayıya çevirmek için cast kullanın: `{{start_date}}::timestamp`, `{{plant_id}}::int`

2.2. MySQL — Pozisyonel `?`

{{name}} → ?. MySQL driver pozisyonel olduğu için her geçiş ayrı ? üretir; aynı parametre iki yerde kullanılırsa argüman listesine iki kez eklenir:

SELECT *
FROM   demo_vardiya_uretim
WHERE  hat     = {{hat_id}}      -- ?  (args[0])
   OR  vardiya = {{hat_id}};     -- ?  (args[1])

Davranış doğru çalışır; sadece performans açısından aynı parametreyi defalarca yazmak yerine WHERE hat IN ({{hat_id}}) OR vardiya IN ({{hat_id}}) gibi yapılar gerekiyorsa CTE/değişken değerlendirin.

2.3. MSSQL (T-SQL) — Adlandırılmış `@name`

{{hat_id}} → @hat_id. T-SQL adlandırılmış parametre kullandığı için indeks değil isim eşleşir:

SELECT *
FROM   demo_fabrika.vardiya_uretim WITH (NOLOCK)
WHERE  hat      = {{hat_id}}      -- @hat_id
  AND  tarih   >= {{start_date}}  -- @start_date

Otomatik tip algılama (yalnızca MSSQL)

Backend, MSSQL parametre değerinin tam sayıya çevrilebildiğini (strconv.Atoi) tespit ederse sql.Named(name, intValue) olarak gönderir; aksi halde string olarak gönderir. Bu yüzden WHERE id = {{plant_id}} çalışırken WHERE name = {{plant_id}} da çalışır — açık CAST({{plant_id}} AS INT) yazmanız gerekmez ama yazmak da zarar vermez.

2.4. REST API — String Yerine Koyma

REST endpoint kayıtlarında parametre literal string substitution yapılır (prepared statement değildir). {{param}} doğrudan değerle değiştirilir.

Alan	Parametre Desteği	Örnek
Endpoint Path	✅	`/api/recete` (path sabit; parametreler query string'te)
Query Parameters	✅ (Value alanında)	Key: `makine`, Value: `{{makine_id}}`
Headers	✅ (Header Value alanında)	Header Key: `X-Hat-ID`, Value: `{{hat_id}}`
Body (POST)	✅ (JSON gövdesi içinde)	`{"hat": "{{hat_id}}"}` (REST için body'de tırnak gerekir; SQL'in aksine)

REST için body'de tırnak gereklidir

SQL kuralının tersine, REST API body'sinde JSON string değer yazıyorsanız {{param}} tırnak içinde yer almalıdır:

{ "filter": { "plant_id": "{{plant_id}}" } }

Çünkü SQL'de backend prepared statement kuruyor; REST'te ise düz string yer-değişimi yapılıyor ve sonuçta JSON sözdizimi geçerli kalmalı.

2.5. MQTT — Parametre Desteklenmez

MQTT topic seçiminde {{...}} kullanılmaz. Topic path'i sabit yazılır (fabrika/hat1/sicaklik); dinamik filtreleme Cartography widget seviyesinde tag mekanizmasıyla yapılır.

→ Detay: MQTT Topic Seçimi

2.6. Excel — Parametre Desteklenmez

Excel sheet seçiminde de parametre kullanılmaz; sheet adı statik seçilir.

3. Sorgu İçinde Parametre Ekleme — Adım Adım

3.1. Parametreli Sorguyu Yazın

{{hat_id}} gibi çift süslü parantez kullanarak sorgunuzu doğrudan parametreli yazın:

SELECT ts, sicaklik, basinc, makine_id
FROM   sensor_zaman_serisi
WHERE  ts >= NOW() - INTERVAL '24 hours'
  AND  hat_id = {{hat_id}}
ORDER  BY ts;

Editör otomatik olarak {{hat_id}} token'ını Parameters panelinde listeler.

3.2. Test İçin Geçici Değer Girin

Editörün altındaki Parameters bölümüne hat_id = HAT-1 yazıp Preview butonuna basın. Bu değer yalnızca test içindir; gerçek varsayılan kayıt panelinde belirlenir.

3.3. Kaydet → Parameter Settings

Next ile Set Parameters type and Default Values ekranına geçtiğinizde, sorguda kullandığınız her benzersiz parametre otomatik kart olarak listelenir. Aşağıdaki tipler arasından seçim yapın:

4. Parameter Settings Paneli — Tip Seçenekleri

Her parametre kartı, Set Parameter butonuna basıldığında genişler ve dört tip sunar:

Tip	İç Değer	Dashboard Görünümü	Tipik Kullanım
Textbox	`textbox`	Serbest metin alanı	Kod, ID, etiket (`HAT-1`)
Datepicker	`datepicker`	Tarih/saat seçici + hızlı seçim	Zaman aralığı (`start_date`, `end_date`)
Dropdown — Sorgudan	`dropdown enter items into query`	Başka bir Compass kaydı sonuçlarından beslenen liste	Hat / makine listesi (DB'den)
Dropdown — Manuel	`dropdown enter items manually`	Virgülle ayrılmış sabit liste	Vardiya kodları (`A,B,C`)

4.1. Textbox

En basit tip. Dashboard'da kullanıcı serbestçe yazar.

Alan	Açıklama	Örnek
Default Value	İlk yüklemede gelecek değer	`HAT-1`

4.2. Datepicker

Tarih/saat değerleri için. Default Value alanında iki seçenek vardır:

A) Takvimden bir an seçin — Choose from calendar seçeneği takvim açar; kesin tarih kaydedilir.

B) Göreli sabit (relative) — sorgu çalıştırıldığı anda otomatik hesaplanır:

Seçenek	Anlam
`Now`	Şimdi
`5 Minute Ago` / `15 Minute Ago` / `30 Minute Ago`	Belirtilen kadar önce
`1 Hour Ago` / `6 Hour Ago` / `12 Hour Ago`	Saat bazlı geçmiş
`Yesterday`	Dün (00:00)
`1 Week Ago` / `1 Month Ago` / `3 Month Ago` / `6 Month Ago`	Hafta/ay bazlı
`1 Year Ago` / `2 Year Ago`	Yıl bazlı

Tipik tarih aralığı kalıbı

Trend chart için iki parametre tanımlayın: - start_date → varsayılan: 1 Week Ago - end_date → varsayılan: Now

Sorgu:

WHERE ts >= {{start_date}}::timestamp
  AND ts <= {{end_date}}::timestamp

Liste seçenekleri başka bir Compass sorgusunun sonucundan gelir. Bu, "tüm hatların listesi" gibi dinamik kümeleri için idealdir.

Alan	Açıklama
Select a Query	Compass'ta önceden kayıtlı listeleyici sorguyu seçin
Default Value	İlk yüklemede seçili gelecek değer (sorgudaki kolon değerlerinden biri)

Beslenen sorgu örneği (hatlar_listesi):

SELECT hat_id AS value, ad AS label
FROM   hatlar
ORDER  BY ad;

Beslenen sorgunun çıktı şekli

Beslenen sorgunun ilk kolonu gerçek değer (parametreye basılan), ikinci kolonu label (kullanıcıya gösterilen) olarak alınır. İki kolon farklı tip olabilir.

Liste seçenekleri virgülle ayrılmış sabit metin olarak girilir.

Alan	Açıklama	Örnek
Items	Virgülle ayrılmış değerler	`A,B,C` veya `Hat-1,Hat-2,Hat-3`
Default Value	İlk yüklemede seçili gelecek değer (listedekilerden biri)	`A`

5. Global Değişkenler vs Yerel Parametreler

Parameter Settings'te bir parametrenin iki yaşam döngüsü olabilir:

Tip	Görünüm	Yaşam Döngüsü
Yerel parametre	Açık arka plan, gri kenarlık, Set Parameter butonu	Yalnızca bu Compass kaydında geçerli
Global Variable	Koyu arka plan, mavi kenarlık, kilit ikonu 🔒, View Settings butonu	Birden fazla Compass kaydında ortak; merkezi yerden yönetilir

Global olarak işaretlenmiş bir parametre, kayıt panelinde salt-okunur olarak görünür ("Managed by Global Variable Settings" etiketi). Tip ve varsayılan değer, Settings → Global Variables ekranından düzenlenir.

Ne zaman global yapılır?

Aynı plant_id birçok sorguda kullanılıyorsa global yapın → tek yerden değiştirin
Sadece bu sorguya özel bir filtre (device_serial) ise yerel bırakın

6. Cartography ve Dashboard Tarafından Beslenme

Compass kaydı bir Cartography widget'ında kullanıldığında, parametre değerleri şu sırayla aranır (öncelikli → düşük):

Dashboard çalışma anı filtresi — kullanıcının dropdown / datepicker üzerinden o an seçtiği değer
Widget üzerinde tag bağlamı — Cartography widget'ının tag filtresi
Compass kaydının Default Value'ı — kayıt panelinde belirlenmiş varsayılan
Boş — yukarıdakilerin hiçbiri yoksa parametre boş string ("") olarak gönderilir

Boş parametre çağrısı

Hiçbir kaynak değer üretmezse parametre boş string olarak gider: - PostgreSQL: WHERE hat_id = '' → büyük olasılıkla 0 satır - Sayısal kolon karşılaştırmasında: WHERE id = '' → tip uyuşmazlığı hatası verebilir

Bu yüzden mutlaka Default Value tanımlayın veya sorguda COALESCE / ISNULL ile null koruması yapın.

7. Kapsamlı Örnekler

7.1. PostgreSQL — Parametreli Zaman Serisi

SELECT
    ts,
    sicaklik,
    basinc,
    makine_id
FROM   sensor_zaman_serisi
WHERE  ts      >= {{start_date}}::timestamp
  AND  ts      <= {{end_date}}::timestamp
  AND  hat_id   = {{hat_id}}
ORDER  BY ts;

Parametre	Tip	Varsayılan
`start_date`	Datepicker	`1 Week Ago`
`end_date`	Datepicker	`Now`
`hat_id`	Dropdown (sorgudan: `hatlar_listesi`)	`HAT-1`

7.2. MSSQL — Vardiya Bazlı Filtre

SELECT
    vardiya,
    SUM(gerceklesen) AS toplam_uretim,
    SUM(hedef)       AS toplam_hedef
FROM   demo_fabrika.vardiya_uretim WITH (NOLOCK)
WHERE  tarih      >= {{start_date}}
  AND  tarih      <= {{end_date}}
  AND  vardiya     = {{vardiya}}
GROUP  BY vardiya;

Parametre	Tip	Varsayılan
`start_date`	Datepicker	`1 Day Ago`
`end_date`	Datepicker	`Now`
`vardiya`	Dropdown (manuel: `A,B,C`)	`A`

7.3. MySQL — Dinamik LIMIT

SELECT *
FROM   demo_vardiya_uretim
ORDER  BY tarih DESC
LIMIT {{row_count}};

Parametre	Tip	Varsayılan
`row_count`	Textbox	`100`

MySQL'de LIMIT parametresi

MySQL LIMIT ifadesi prepared statement parametresi olarak desteklenir. PostgreSQL'de de aynısı çalışır.

7.4. REST API — Query Parametreli Endpoint

Endpoint Path:     /api/sicaklik/trend
HTTP Method:       GET
Query Parameters:
  Key: hat         Value: {{hat_id}}
  Key: hours       Value: 24

Parametre	Tip	Varsayılan
`hat_id`	Dropdown (sorgudan: `hatlar_listesi`)	`HAT-1`

8. Sık Karşılaşılan Hatalar ve Çözümleri

Belirti	Olası Neden	Çözüm
Sorgu 0 satır dönüyor	`'{{param}}'` tek tırnak içinde	Tırnağı kaldırın: `= {{param}}`
`column "..." does not exist`	Parametre yerinde yazım hatası	Kolon adını editör otomatik tamamlama ile doğrulayın
`invalid input syntax for type integer: ""`	Default Value boş, runtime'da değer gelmedi	Parameter Settings'te Default Value tanımlayın
`Operand type clash` (MSSQL)	Parametre stringken kolon int	Sorguda explicit cast: `CAST({{id}} AS INT)`
Parameters panelinde parametre görünmüyor	`{{ ... }}` arasında boşluk var (`{{ hat_id }}`)	Boşlukları kaldırın: `{{hat_id}}`
Aynı isimde parametre iki kart	Büyük/küçük harf farkı	Tüm geçişleri tek isme normalleştirin (`hat_id`)
Datepicker'da `Now` seçili ama sorgu eski tarih dönüyor	Cache (varsayılan 300 s) geçmemiş	Beklemek veya cache süresini düşürmek
Dropdown (sorgudan) boş geliyor	Beslenen sorgu satır döndürmüyor veya silindi	Beslenen sorguyu önce manuel test edin
REST API body'sinde `{{param}}` parse hatası	JSON içinde tırnaksız yazılmış	`"alan": "{{param}}"` (JSON için tırnak şart)

9. İyi Pratikler

Pratik	Neden
Parametre adlarını `snake_case` ile yazın (`hat_id`, `start_date`)	Tüm dialektlerde güvenli
Parameters panelinde test değeri girip Preview ile doğrulama yapın	Sözdizimi ve veri varlığını ayrı ayrı doğrulamış olursunuz
Datepicker varsayılanını `Now` ve `1 Week Ago` gibi göreli ayarlayın	Dashboard her açıldığında "anlamlı" bir aralık gelir
Birden fazla sorguda kullanılan parametreyi Global Variable yapın	Tek değişiklikle tüm bağlı sorgular güncellenir
PostgreSQL'de tarih parametrelerini `::timestamp` ile cast edin	Driver string olarak gönderir; karşılaştırma için cast gerekir
Global Variable adlarına `g_` öneki gibi konvansiyon koymayın	İç değer aynıdır; kilit ikonu zaten görünür ayrım sağlar
Aşırı parametre tanımlamayın	Dashboard kullanıcısı için 4-5 parametreden sonra UX bozulur — sabitleri sorgu içinde tutun

10. Hızlı Referans

Sözdizimi:           {{parametre_adi}}
İzin verilen:        A-Z, a-z, 0-9, _
Tırnak:              YOK (SQL); VAR (REST JSON body)
PostgreSQL → $1, $2, ... (aynı isim aynı indeks)
MySQL      → ?  (her geçiş ayrı ?)
MSSQL      → @name (otomatik int dönüşümü)
REST       → düz string substitution
MQTT/Excel → desteklenmez

Sonraki Adım

Parametreleri tanımladıktan sonra Compass kaydı Cartography'de chart / KPI widget'ına dönüştürülür ve dashboard tarafından çalıştırılır.

→ Cartography → PostgreSQL Sorgusu Oluşturma → MSSQL Sorgusu Oluşturma → MySQL Sorgusu Oluşturma → REST Endpoint Tanımlama