Veri Arka Ucu

IronFlock, TimescaleDB tarafından desteklenen her proje için özel bir veritabanı sağlar. Uygulamanız veri şemasını tanımlar; IronFlock tabloları oluşturur ve uygulamaya bir cihaz eklenir eklenmez veri toplamaya başlar.

Nasıl Çalışır

1. Veri şemanızı .ironflock/data-template.yml içinde tanımlayın.
2. Edge kodunuzdan veri yayımlamak için IronFlock SDK’sını kullanın.
3. IronFlock, uygulamanın kurulu olduğu her projedeki veritabanı tablolarını otomatik olarak ayarlar.
4. Veriler cihazlardan mesajlaşma sistemi aracılığıyla proje veritabanına akar.

Her proje kendi fiziksel veritabanını alır — projeler arasında veri paylaşımı yoktur.

Kullanıcı, projelerinde uygulamanız tarafından toplanan veriler üzerinde tam kontrole sahiptir. Geliştirici olarak bu verilere erişiminiz yoktur.

Veri Şemasını Tanımlama

.ironflock/ dizininde bir data-template.yml dosyası oluşturun:

data:
  tables:
    - tablename: sensordata
      columns:
        - id: tsp
          name: Timestamp
          description: Timestamp of measurement
          path: args[0].timestamp
          dataType: timestamp
        - id: temperature
          name: Temperature
          description: Temperature reading in Celsius
          path: args[0].temperature
          dataType: numeric
        - id: humidity
          name: Humidity
          description: Relative humidity percentage
          path: args[0].humidity
          dataType: numeric
        - id: device_id
          name: Device ID
          description: Source device identifier
          path: args[0].device_id
          dataType: string

Sütun Seçenekleri

Tablo Seçenekleri

columns dışında bir tablo, nasıl tanımlandığını ve verisinin nasıl yaşlandığını denetleyen birkaç isteğe bağlı anahtar kabul eder:

data:
  tables:
    - tablename: sensordata
      description: Üretim sahasından ortam ölçümleri
      chunkTimeInterval: 1 hour
      dropAfter: 30 days
      columns:
        # ...

chunkTimeInterval, zaman serisi verisinin diskte nasıl bölümleneceğini belirler. Bir bölümün, tek seferde sorguladığınız veri miktarına yaklaşık olarak denk gelmesini sağlayacak bir değer seçin: saniyede bir toplanan yüksek frekanslı veriler küçük parçalardan (dakikalar–saatler), yavaş değişen veriler ise büyük parçalardan (haftalar) fayda görür. Bu yalnızca uygulamanın varsayılanıdır — proje sahibi daha sonra kendi data backend’inde bunu değiştirebilir.

dropAfter, tabloyu kayan bir pencereye dönüştürür. Belirtilen aralıktan eski bölümler bütün olarak silinir; bu, satırları tek tek silmekten çok daha ucuzdur. Temizleme işi dropAfter / 4 aralığıyla çalışır, dolayısıyla bir kayıt bölümü kaldırılana kadar süresini aralığın dörtte biri kadar aşabilir. Verileri süresiz saklamak için dropAfter’ı belirtmeyin.

Her ikisi de PostgreSQL aralık ifadeleri alır — 30 minutes, 1 hour, 7 days, 6 months.

Sürekli Aşağı Örnekleme

Panolar, veritabanından veriyi toplulaştırmasını isteyebilir — saatlik ortalamalar, günlük toplamlar, makine başına sayımlar. Bunları ham kayıtlardan hesaplamak bir gün için sorunsuzdur, bir yıl için pahalıdır. Bir tabloya downsample ekleyin; platform o tablonun sürekli güncellenen, önceden toplulaştırılmış bir kopyasını tutar ve uzun pencereli sorguları bunun yerine o kopyadan yanıtlar:

data:
  tables:
    - tablename: sensordata
      dropAfter: 30 days
      downsample:
        bucket: 1 minute
        keepFor: 2 years
        paths:
          - payload.temperature
      columns:
        # ...

bucket, bir grafiğin sunulabileceği en ince çözünürlüktür — bundan çok daha ince aralıklar isteyen bir grafik onun yerine ham tabloyu okur. Bir günü tam bölen, 1 second ile 1 day arasındaki sabit genişlikli aralıkları kabul eder (1 minute, 5 minutes, 1 hour). Varsayılan 1 minute pratikte her panoya uygundur; daha kaba bir aralık daha az depolama ve daha az yazma yükü demektir.

keepFor, uzun geçmişleri en baştan mümkün kılan şeydir. Ham kayıtlar dropAfter ile silinir, ancak aşağı örneklenmiş kopyanın kendi saklama süresi vardır: ham veriyi 30 gün, aşağı örneklenmiş veriyi 2 yıl saklayın; bir pano depolamanın küçük bir bölümüyle yine de iki yıllık saatlik ortalamaları grafikleyebilir. Bunu dropAfter’dan daha uzun ayarlayın — platform tersini hatalı yapılandırma sayarak reddeder.

paths, aşağı örneklemeyi JSON sütunlarının içindeki değerlere de genişletir. Sayısal sütunlar otomatik olarak dahil edilir; JSON alanlarının ise açıkça adlandırılması gerekir, çünkü bir JSON sütununun sabit bir anahtar kümesi yoktur. Bildirilmemiş alanlar panolarda yine de çalışır — yalnızca ham tablodan hesaplanırlar.

Geri kalan her şey otomatiktir. Her sayısal sütunun istatistikleri (ortalama, toplam, minimum, maksimum, ilk, son ve kayıt sayısı), tablonun varlık anahtarına (maintainLatestFlagFor ya da yayımlayan cihaz) göre gruplanarak sürdürülür. Panoların ne bir yapılandırmaya ne de bundan haberdar olmaya ihtiyacı vardır: widget her zamanki gibi sorgular ve platform her sorguda önceden toplulaştırılmış kopyanın yanıt verip veremeyeceğine karar verir — veremediğinde, örneğin bir filtre kopyanın gruplamadığı bir sütuna atıfta bulunduğunda, şeffaf biçimde ham tabloya geri düşer.

Şema değişiklikleri kopyayı yeniden oluşturur. Aşağı örneklenmiş bir tabloya sütun eklemek, sütun kaldırmak veya bir sütunun tipini değiştirmek — ya da downsample bloğunun kendisini düzenlemek — önceden toplulaştırılmış kopyayı ham tablodan yeniden oluşturur. dropAfter’dan eski olan hiçbir şey yeniden kurulamaz ve kaybolur. Bu bloğu mümkün olduğunca tabloyla birlikte kurun ve uzun ömürlü tablolardaki sonraki şema değişikliklerini bilinçli bir karar olarak ele alın.

Edge Kodundan Veri Yayımlama

Uygulamanızdan veri göndermek için IronFlock SDK’sını kullanın:

from ironflock import IronFlock
 
flock = IronFlock()
 
flock.publish_to_table("sensordata", {
    "timestamp": "2025-01-15T10:30:00Z",
    "temperature": 23.5,
    "humidity": 62.1,
    "device_id": "sensor-001"
})

import { IronFlock } from "ironflock";
 
const flock = new IronFlock();
 
flock.publishToTable("sensordata", {
    timestamp: "2025-01-15T10:30:00Z",
    temperature: 23.5,
    humidity: 62.1,
    device_id: "sensor-001"
});

Yüksek frekanslı veriler için, satır başına bir gidiş-dönüş yerine publish_rows_to_table / publishRowsToTable (gönder-unut) ya da append_rows_to_table / appendRowsToTable (ekleme sonucunu döndürür) kullanarak tek bir mesajda birden çok satır gönderin. Her yığın atomik olarak eklenir — ya hep ya hiç. Ayrıntılar için bkz. SDK referansı.

Dönüşüm Tabloları

Ham verilerinizi otomatik olarak toplayan veya işleyen SQL dönüşümleri tanımlayabilirsiniz:

data:
  tables:
    - tablename: sensordata
      columns:
        # ... ham veri sütunları ...
 
  transforms:
    - tablename: hourly_averages
      materialize: true
      schedule: "0 * * * *"
      sql: >
        SELECT
          time_bucket('1 hour', tsp) AS hour,
          avg(temperature) AS avg_temp,
          avg(humidity) AS avg_humidity
        FROM sensordata
        GROUP BY hour
      columns:
        - id: hour
          name: Hour
          dataType: timestamp
        - id: avg_temp
          name: Average Temperature
          dataType: numeric
        - id: avg_humidity
          name: Average Humidity
          dataType: numeric

Dönüşüm tabloları, tıpkı normal tablolar gibi panolarda ve SDK aracılığıyla erişilebilir.

Bir Varlığın En Son Durumunu Takip Etme

Gerçek dünya varlıklarının mevcut durumunu temsil eden tablolar için — makineler, varlıklar, üretim emirleri — IronFlock en son durum takibi adı verilen bir deseni destekler.

Bir şey değiştiğinde satırın üzerine yazmak yerine, her zaman yeni bir satır eklersiniz. Benzersiz bir varlığı hangi sütunların tanımladığını siz bildirirsiniz; IronFlock da tablo her okunduğunda varlık başına en son satırı türetir. Bu, her değişikliğin tam geçmişini sağlarken yalnızca mevcut durumu sorgulamayı da kolaylaştırır.

maintainLatestFlagFor ile bir tabloda etkinleştirin:

- tablename: machineform
  maintainLatestFlagFor: ['machinename']
  columns:
    - id: tsp
      dataType: timestamp
    - id: machinename
      dataType: string
    - id: machinetype
      dataType: string
    - id: active
      dataType: boolean
    - id: description
      dataType: string

maintainLatestFlagFor, birlikte benzersiz bir varlığı tanımlayan sütunların listesini alır. Satırın kendisine hiçbir şey yazılmaz: IronFlock tabloyu bu varlık anahtarına ve zaman damgasına göre indeksler ve sorgu anında varlık başına en yeni satırı seçer. Bu nedenle geç ya da sırasız gelen bir satır, geride asla eskimiş bir işaret bırakamaz.

Yalnızca mevcut makine durumlarını sorgulamak için:

SELECT DISTINCT ON (machinename) *
FROM machineform
ORDER BY machinename, tsp DESC

Belirli bir makinenin tam geçmişini görüntülemek için:

SELECT * FROM machineform WHERE machinename = 'Assembly-Line-01' ORDER BY tsp

Bu sorguyu elle yazmanız nadiren gerekir. Bu tabloya bağlanan panodaki widget’ların filtre ayarlarında bir latest anahtarı bulunur; böylece kullanıcılar herhangi bir ek çalışma olmadan her zaman güncel değerleri görür. SDK’dan aynı modu, filterAnd içine {"latest": true} ekleyerek isteyebilirsiniz — bkz. getHistory.

latest_flag’ten yükseltme: IronFlock’un önceki sürümleri latest_flag adında fiziksel bir boolean sütunu saklıyordu. Bu sütun artık mevcut değil — mevcut durum bunun yerine SQL’de türetiliyor; bu da satırlar sırasız geldiğinde bile sonucun doğru kalmasını sağlıyor. latest_flag = true ile filtreleyen mevcut panolar ve SDK çağrıları çalışmaya devam eder: IronFlock bunları tanır ve en son durum modunu uygular. Yeni kodlar latest anahtarını veya {"latest": true} filtre girdisini kullanmalıdır.

Kayıtları Yumuşak Silme

IronFlock’un yalnızca ekleme modeli, kayıtların fiziksel olarak hiçbir zaman silinmediği anlamına gelir. Bunun yerine, bir kaydı kaldırılmış olarak işaretlemek için deleted boolean sütununu kullanın. Bu, tam denetim izini korurken silinen kayıtları dashboard’lardan gizler.

Herhangi bir varlık tablosuna deleted sütunu ekleyin:

- id: deleted
  name: Deleted
  dataType: boolean

Bir kullanıcı bir kaydı sildiğinde (örneğin panodaki bir form aracılığıyla), uygulamanız o varlık için deleted: true ile yeni bir satır yayımlar. maintainLatestFlagFor ile birleştiğinde, bu yeni satır en son durum olur.

Yalnızca aktif (silinmemiş) mevcut kayıtları sorgulamak için:

SELECT * FROM (
  SELECT DISTINCT ON (machinename) *
  FROM machineform
  ORDER BY machinename, tsp DESC
) latest
WHERE deleted IS NULL OR deleted = false

deleted denetimi, makine başına en son satır seçildikten sonra çalışır. Bu sıra önemlidir: silinen satırları önce ayıklamak, önceki silinmemiş satırın mevcut durum olarak yeniden ortaya çıkmasına yol açar.

Pano widget’ları ve SDK aynı sırayı otomatik olarak uygular — latest anahtarını (veya {"latest": true}) bir deleted filtresiyle birleştirdiğinizde tam olarak bu davranışı elde edersiniz. Silinen kayıtlar form gönderilir gönderilmez dashboard’dan kaybolur, ancak geçmiş ve denetim amacıyla veritabanında kalır.

Verileri Diğer Uygulamalarla Paylaşma

Data backend’iniz yalnızca sizin uygulamanıza aittir: projede kurulu başka hiçbir uygulama tablolarınızı göremez. data-template.yml içindeki iki isteğe bağlı anahtar bunu değiştirir.

Başka bir uygulamanın verilerini okumak için, okumak istediğiniz uygulamaları üst düzey bir consumes: bölümünde listeleyin — data: bölümünün içinde değil, yanında:

consumes:
  - app: machine-monitor
    reason: "Monitörün makine durumu ve sayaç akışlarından OEE hesaplar"
 
data:
  tables:
    - tablename: oee_results
      columns:
        # ... her zamanki gibi uygulamanızın kendi tabloları

app, veriyi sağlayan uygulamanın teknik adıdır; projedeki tüm uygulamalar için "*" (tırnak işaretleri zorunludur) kullanılır. reason, onay penceresinde kullanıcıya gösterilir — bildirimin kendisi, kullanıcı onaylamadıkça hiçbir erişim vermez.

Belirli tabloları paylaşım dışında tutmak için bunları private: true ile işaretleyin. Tanımladığınız her şey varsayılan olarak paylaşılabilirdir; özel bir tablo veya dönüşüm, diğer uygulamaların gördüğü katalogda hiç görünmez.

data:
  tables:
    - tablename: measurements        # paylaşılır (varsayılan)
      columns: [ ... ]
    - tablename: calibration_state   # dahili — diğer uygulamalara asla görünmez
      private: true
      columns: [ ... ]

Erişim salt okunurdur, kullanıcı tarafından proje bazında verilir ve istendiği zaman geri alınabilir. Modelin tamamı ve sağlayıcı uygulamanın geçmiş ile canlı akışlarını okuyan SDK çağrıları için bkz. Diğer Uygulamaların Verilerini Kullanma.