Analitik tarifleri ve sorgu kurucu

Bu sayfa analytics modülünün sorgu yolunu açıklar. src/cluster_erp/modules/analytics/registry.py doğrulanmış kataloğu tutar, src/cluster_erp/modules/analytics/query_builder.py doğruluk kapılarıyla güvenli toplu sorgular kurar ve src/cluster_erp/modules/analytics/recipe_engine.py ile recipe_schemas.py bildirime dayalı hazırlık tariflerini çalıştırır. Kataloğun diğer modüllerce nasıl doldurulduğu analitik olgular sayfasındadır.

Kısaca¶

• Kullanıcı yalnızca anlamsal anahtarlarla sorar: bir olgu, ölçüler, boyutlar, süzgeçler, sıra ve bir sayfa (src/cluster_erp/modules/analytics/schemas.py:1-11, src/cluster_erp/modules/analytics/schemas.py:47-61).
• Tablo ve sütun adları yalnızca modül bildirimlerinden gelir; değerler bağlı parametrelerdir. SQL'e dize birleştirme yoktur (src/cluster_erp/modules/analytics/query_builder.py:5-10).
• Dört kapı yanlış olacak bir sayıyı reddeder: toplanamaz toplamlar, sabitlenmemiş bir eksende yarı toplanabilir toplamlar, karışık para birimleri ve tanecik verilmemiş tarihler (src/cluster_erp/modules/analytics/query_builder.py:11-23).
• Tarif, kapalı bir sözlükten adımların saklanan bir listesidir; motor her adım için giren ve çıkan satırları kaydeder (src/cluster_erp/modules/analytics/recipe_engine.py:1-21, src/cluster_erp/modules/analytics/recipe_schemas.py:1-33).

Nasıl çalışır¶

Tarif ve sorgu hattı¶

flowchart TD
 A["AnalysisSpec ile POST /analysis/run"] --> C["AnalyticsService.catalogue: collect ve visible_to"]
 P["RecipeDefinition ile POST /analysis/prepare"] --> C
 C --> F["FactCatalogue.get olgu"]
 F --> S{"summaries.plan uyuyor mu"}
 S -->|evet| QS["query_builder._build_from_summary"]
 S -->|hayır| QB["query_builder.build"]
 QB --> G["kapılar: toplanabilirlik, para birimi, tanecik"]
 QS --> G
 G --> X["çalıştır, MAX_ROWS ile sınırla"]
 X --> R["kaynak summary veya live olan AnalysisResult"]
 F --> RE["RecipeEngine.run"]
 RE --> ST["adımları uygula, giren ve çıkan satırları say"]
 ST --> EX["beklentileri denetle"]
 EX --> RR["gözlemlerle RecipeRunResult"]

Düz anlatımla:

1. İki giriş noktası da önce çağıranın kataloğunu kurar: registry.collect her modüle sorar, visible_to yalnızca çağıranın read_permission iznine sahip olduğu olgu kümelerini tutar (src/cluster_erp/modules/analytics/service.py:55-62, src/cluster_erp/modules/analytics/registry.py:100-109).
2. Bir çalıştırmada summaries.plan, önceden toplanmış hücrelerin yanıt verip veremeyeceğine karar verir; aksi halde sorgu olgu tablosunda çalışır (src/cluster_erp/modules/analytics/service.py:139-148). Bkz. raporlar, özetler ve çapraz.
3. query_builder.build, tüm bildirilmiş sütunlarla tek bir ilişki kurar; gruplanan boyutları, ölçüleri, süzgeçleri, canlı süzgeci, sırayı ve kesilmeyi algılamak için en fazla MAX_ROWS 10000 artı bir satırlık bir sayfayı ekler (src/cluster_erp/modules/analytics/query_builder.py:71-96, src/cluster_erp/modules/analytics/query_builder.py:375-470).
4. Sonuç summary veya live kaynağından geldiğini ve canlı yolun neden seçildiğini belirtir (src/cluster_erp/modules/analytics/service.py:157-168).
5. Tarifte motor anlamsal adlarıyla anahtarlanmış tüm bildirilmiş sütunlardan başlar, canlı süzgeci uygular, etkin her adımı çalıştırır ve öncesi ile sonrasındaki satır sayısını ölçer (src/cluster_erp/modules/analytics/recipe_engine.py:195-262).

Doğruluk kapıları¶

Yalnızca eq bir değeri sabitler; in sabitlemez, çünkü seçilen iki para biriminin toplamı yine karışık bir toplamdır (src/cluster_erp/modules/analytics/query_builder.py:62-68). İki kural daha geçerlidir: SQL içinde round() yoktur ve parasal medyanlar her rakam gerçekleşmiş bir tutar olsun diye percentile_disc kullanır (src/cluster_erp/modules/analytics/query_builder.py:24-31).

Tarifler¶

Tarifin (RecipeDefinition) bir girdisi, adımları, beklentileri ve 100000 satıra kadar bir sınırı vardır (src/cluster_erp/modules/analytics/recipe_schemas.py:255-283).

Her adımın kararlı bir id, bir gösterim seq, bir note ve bir disabled bayrağı vardır; devre dışı adım kaldırılmak yerine atlanır (src/cluster_erp/modules/analytics/recipe_schemas.py:47-60, src/cluster_erp/modules/analytics/recipe_engine.py:221). Adım kimlikleri benzersiz olmalıdır (src/cluster_erp/modules/analytics/recipe_schemas.py:274-281). Bir adım anlamsal anahtarları adlandırır; olgu kümesinin hiç bildirmediği bir anahtar reddedilir (src/cluster_erp/modules/analytics/recipe_engine.py:69-93).

Neden böyle kurulmuş¶

• Sorgu kurucu belge dizesi tek bir sözü adlandırır: asla yanlış bir sayı üretmemek (src/cluster_erp/modules/analytics/query_builder.py:1-4).
• Tarif şeması op alanını kapalı bir sözlük olarak tutar; çünkü bu hiçbir enjeksiyon yüzeyi bırakmaz ve sonraki adım önerilerinin alanını küçük tutar (src/cluster_erp/modules/analytics/recipe_schemas.py:12-17).
• Birleştirmeler uygulanmamıştır; çünkü satır çoğalması kapısı olmayan bir birleştirme her ölçüyü çoğaltır (src/cluster_erp/modules/analytics/recipe_engine.py:17-21, src/cluster_erp/modules/analytics/recipe_schemas.py:186-190).

Kurallar ve sınırlar¶

• Tarif tam olarak bir girdi kabul eder; birleştirme kapısı var olana kadar birden fazlası reddedilir (src/cluster_erp/modules/analytics/recipe_schemas.py:262-272).
• Sıra anahtarı seçilen boyutlardan veya ölçülerden biri olmalıdır (src/cluster_erp/modules/analytics/query_builder.py:454-463).
• Kayıt defteri, ek savunma olarak katı bir tanımlayıcı kalıbına uymayan fiziksel adları reddeder (src/cluster_erp/modules/analytics/registry.py:41-48).

Diğer parçalarla etkileşim¶

Sınırlar ve açık noktalar¶

• RecipeInput.as_of, anlık görüntü anı olarak tarifle saklanır; recipe_engine.py içinde as_of okuması bulunamadı (src/cluster_erp/modules/analytics/recipe_schemas.py:244-253).
• Sonuç, üretilen SQL metnini sql içinde taşır (src/cluster_erp/modules/analytics/service.py:164, src/cluster_erp/modules/analytics/query_builder.py:543-552).

Tanıtılan terimler¶

İlgili sayfalar¶

• Analytics modülü
• Analitik olgular
• İstatistik ve çıkarım
• Para ve ondalık

92f8051 numaralı commit ile 2026-11-13 tarihinde doğrulandı.