Query Builder

Der Query Builder im OctoMesh Refinery Studio ermöglicht Ihnen, Abfragen gegen Ihre OctoMesh-Runtime-Entitäten zu erstellen, zu speichern und auszuführen. Er bietet eine visuelle Oberfläche zum Erstellen von Abfragen, ohne GraphQL-Code direkt zu schreiben.

Zugriff auf den Query Builder

Navigieren Sie zu Repository > Query Builder, um auf die Oberfläche zur Abfrageverwaltung zuzugreifen.

Die Listenansicht zeigt alle gespeicherten Abfragen mit ihrem Namen, Abfragetyp und CK-Typ. Sie bietet Aktionen zum Bearbeiten oder Löschen.

Toolbar-Aktionen

Button	Beschreibung
NEW QUERY	Eine neue Abfrage erstellen
IMPORT DATA	Daten aus einer Datei importieren
IMPORT QUERIES	Abfragedefinitionen aus einer Datei importieren
Export to Excel	Die Abfrageliste in eine Excel-Datei exportieren
Export to PDF	Die Abfrageliste in eine PDF-Datei exportieren
Refresh Data	Die Abfrageliste vom Server neu laden

Zeilenaktionen

Jede Abfragezeile bietet die folgenden Aktionsschaltflächen:

Aktion	Beschreibung
Run	Die Abfrage ausführen und die Ergebnisse anzeigen
Edit	Die Abfrage im Editor öffnen

Kontextmenü

Ein Rechtsklick auf eine Abfragezeile öffnet ein Kontextmenü mit zusätzlichen Aktionen:

Aktion	Beschreibung
Duplicate	Eine Kopie der Abfrage erstellen
Export Results	Die Abfrage ausführen und die Ergebnisse als ZIP-Datei exportieren
Export Query	Die Abfragedefinition als ZIP-Datei exportieren
Delete	Die Abfrage löschen (mit Bestätigung)

Eine neue Abfrage erstellen

Klicken Sie auf NEW QUERY, um das Konfigurationsformular für Abfragen zu öffnen.

Abfragekonfiguration

Das Abfrageformular besteht aus mehreren Abschnitten:

Grundeinstellungen

Die Grundeinstellungen sind für ein kompaktes Layout in zwei Zeilen angeordnet:

Zeile 1: Query Type und Name

Feld	Beschreibung
Query Type	Wählen Sie den Abfragetyp (Simple, Aggregation oder Grouped Aggregation). Jede Option enthält eine kurze Beschreibung.
Query Name	Ein aussagekräftiger Name für Ihre Abfrage

Zeile 2: CK Type und Navigation Filter Mode

Feld	Beschreibung
CK Type	Der abzufragende Construction-Kit-Typ
Navigation Filter Mode	Steuert, wie Entitäten ohne passende Navigationsassoziationen behandelt werden (siehe unten)

Navigation Filter Mode

Der Navigation Filter Mode bestimmt, wie Entitäten behandelt werden, wenn sie keine passenden Navigationsassoziationen haben:

Modus	Beschreibung
Filter	Entitäten ohne passende Navigationsassoziationen werden aus der Ergebnismenge ausgeschlossen.
Include	Entitäten ohne passende Navigationsassoziationen werden mit Null-Werten beibehalten.

Abfragetypen

Typ	Beschreibung
Simple Query	Gibt eine Liste von Entitäten mit ausgewählten Attributen zurück
Aggregation	Führt aggregierte Berechnungen (COUNT, SUM, AVG, MIN, MAX) über alle passenden Entitäten durch
Grouped Aggregation	Gruppiert Entitäten nach einem Attribut und führt aggregierte Berechnungen pro Gruppe durch

Einen CK-Typ auswählen

Klicken Sie auf die Schaltfläche SELECT neben dem Feld CK Type, um die Typauswahl zu öffnen.

Der Auswahldialog zeigt alle verfügbaren Construction-Kit-Typen, organisiert nach Paket. Verwenden Sie das Suchfeld, um Typen nach Namen zu filtern. Klicken Sie auf einen Typ, um ihn auszuwählen.

Nach der Auswahl zeigt das Feld CK Type den ausgewählten Typ (z. B. System.Identity/User).

Konfiguration einer Simple Query

Für Simple Queries konfigurieren Sie Spalten, Sortierung und Filter.

Spalten

Klicken Sie auf ADD COLUMNS, um auszuwählen, welche Attribute in die Abfrageergebnisse aufgenommen werden.

Der Dialog zur Spaltenauswahl zeigt:

• Available attributes (linkes Panel): Alle Attribute des ausgewählten CK Type mit ihren Datentypen
• Selected columns (rechtes Panel): In die Abfrageergebnisse aufgenommene Attribute

Neben den eigenen Attributen des CK-Typs stehen die Systemfelder rtDisplayName und rtDisplayDescription (berechnet aus den Display-Name-Regeln des Typs) als Spalten zur Verfügung und können auch in Filtern und Sortierungen verwendet werden.

Angezeigte Attributtypen umfassen:

• STRING - Textwerte
• INTEGER - Ganze Zahlen
• INTEGER_64 - Große ganze Zahlen
• BOOLEAN - Wahr/Falsch-Werte
• DATE_TIME - Datums- und Zeitwerte
• DATE_TIME_OFFSET - Datum und Uhrzeit mit Zeitzone
• STRING_ARRAY - Liste von Textwerten
• RECORD_ARRAY - Liste komplexer Records

Verwenden Sie die Pfeilschaltflächen, um:

• Ausgewählte Attribute zur Abfrage hinzuzufügen
• Attribute aus der Abfrage zu entfernen
• Spalten neu anzuordnen (nach oben/unten verschieben)

Sortierung

Fügen Sie Sortierregeln hinzu, um die Reihenfolge der Ergebnisse zu steuern:

1. Klicken Sie auf ADD SORTING
2. Wählen Sie das Attribut, nach dem sortiert werden soll
3. Wählen Sie aufsteigende oder absteigende Reihenfolge

Mehrere Sortierregeln werden der Reihe nach angewendet.

Konfigurierte Abfrage

Sobald Spalten konfiguriert sind:

• Wird die Schaltfläche SAVE aktiviert
• Wird die Schaltfläche EXECUTE aktiviert
• Wird die Spaltenanzahl angezeigt (z. B. „4 Columns Selected")

Filter

Filter grenzen die Abfrageergebnisse anhand von Attributwerten ein.

Filter hinzufügen

Klicken Sie auf ADD FILTER, um eine Filterzeile hinzuzufügen.

Jeder Filter besteht aus:

• Attribute: Das Attribut, nach dem gefiltert wird
• Operator: Der Vergleichsoperator
• Value: Der Wert, mit dem verglichen wird

Filter-Attribute

Das Attribut-Dropdown zeigt alle verfügbaren Attribute mit ihren Datentypen. Die Werteingabe passt sich an den Attributtyp an:

• Boolesche Attribute zeigen einen Umschalter
• String-Attribute zeigen eine Texteingabe
• Zahlen-Attribute zeigen eine numerische Eingabe
• Datums-Attribute zeigen einen Datumswähler

Filter-Operatoren

Operator	Beschreibung
Equals	Exakte Übereinstimmung
Not Equals	Keine Übereinstimmung
Greater Than	Wert ist größer als
Greater Equal	Wert ist größer als oder gleich
Less Than	Wert ist kleiner als
Less Equal	Wert ist kleiner als oder gleich
Like	Mustervergleich (verwenden Sie % als Platzhalter)
In	Wert ist in einer Liste enthalten
Not In	Wert ist nicht in einer Liste enthalten
Any Equals	Ein beliebiges Array-Element stimmt überein
Any Like	Ein beliebiges Array-Element stimmt mit dem Muster überein
Match RegEx	Übereinstimmung per regulärem Ausdruck

Mehrere Filter

Sie können mehrere Filter hinzufügen. Alle Filter werden mit UND-Logik verknüpft (alle Bedingungen müssen zutreffen).

Aggregation Queries

Aggregation Queries berechnen zusammenfassende Statistiken, anstatt einzelne Entitäten zurückzugeben.

Bei Aggregation Queries werden die Abschnitte COLUMNS und SORTING durch einen Abschnitt AGGREGATION ersetzt.

Aggregationen konfigurieren

Klicken Sie auf ADD AGGREGATION, um den Aggregationsdialog zu öffnen.

Konfigurieren Sie jede Aggregation:

Feld	Beschreibung
Function	Die Aggregationsfunktion (COUNT, MIN, MAX, AVG, SUM)
Attribute	Das zu aggregierende Attribut (bei COUNT nicht erforderlich)
Name	Anzeigename für das Aggregationsergebnis

Aggregationsfunktionen

Funktion	Beschreibung
COUNT	Anzahl der passenden Entitäten
MIN	Minimalwert
MAX	Maximalwert
AVG	Durchschnittswert (Mittelwert)
SUM	Gesamtsumme der Werte

Grouped Aggregation Queries

Grouped Aggregation Queries kombinieren Gruppierung mit Aggregation. Ergebnisse werden nach einem Attribut gruppiert, und für jede Gruppe werden Aggregationen berechnet.

Die Konfiguration umfasst:

• Group By: Das Attribut, nach dem die Ergebnisse gruppiert werden
• Aggregations: Eine oder mehrere Aggregationsfunktionen

Beispiel: Benutzer nach Abteilung gruppieren und die Benutzer pro Abteilung zählen.

Abfragen ausführen

Klicken Sie auf EXECUTE, um die Abfrage auszuführen und Ergebnisse zu sehen. Die Ergebnisse werden unterhalb der Abfragekonfiguration in Tabellenform angezeigt.

Abfragen speichern

Klicken Sie auf SAVE, um die Abfragekonfiguration zu speichern. Gespeicherte Abfragen erscheinen in der Query-Builder-Liste und können:

• zur Datenexploration wiederverwendet werden
• in MeshBoard-Widgets referenziert werden
• über den Tenant hinweg geteilt werden

---

Stream Data Queries

Zusätzlich zu Abfragen auf Runtime-Entitäten unterstützt der Query Builder das Abfragen von Zeitreihendaten, die in CrateDB gespeichert sind. Stream Data Queries ermöglichen es Ihnen, historische Messwerte wie Sensormesswerte, Maschinenkennzahlen oder Energieerzeugungswerte abzurufen, zu aggregieren und herunterzurechnen (Downsampling).

Zu den Details der zugrunde liegenden GraphQL-API siehe den Technikleitfaden Stream Data Access.

Stream-Data-Abfragetypen

Beim Erstellen einer neuen Abfrage stehen im Selektor Query Type die folgenden Stream-Data-Abfragetypen zur Verfügung:

Typ	Beschreibung
Stream Data Query	Rohe Zeitreihen-Datenpunkte mit Spaltenauswahl abrufen
Stream Data Aggregation	Aggregierte Werte (AVG, MIN, MAX, COUNT, SUM) über Zeitreihendaten berechnen
Stream Data Grouped Aggregation	Zeitreihendaten gruppiert nach einer oder mehreren Spalten aggregieren
Stream Data Downsampling	Die Datendichte reduzieren, indem Zeitbereiche in Buckets aufgeteilt werden, mit Aggregation pro Bucket

Einen CK-Typ für Stream Data auswählen

Wenn ein Stream-Data-Abfragetyp ausgewählt ist, zeigt der CK-Type-Selektor nur Typen an, für die Stream Data aktiviert ist (IsStreamType). Wählen Sie den Typ, dessen Zeitreihendaten Sie abfragen möchten (z. B. Industry.Energy/EnergyMeter).

Konfiguration einer Stream Data Simple Query

Für Stream-Data-Simple-Queries ähnelt die Konfiguration den Runtime-Simple-Queries:

• Columns: Wählen Sie, welche Datenstrom-Attribute in die Ergebnisse aufgenommen werden (z. B. voltage, power). Nur als Datenstrom-Attribute markierte Attribute stehen zur Verfügung.
• Time Range: Verwenden Sie die Datumswähler From und To, um die Abfrage auf ein bestimmtes Zeitfenster einzuschränken.
• Limit: Legen Sie die maximale Anzahl zurückzugebender Datenpunkte fest.
• Sorting: Fügen Sie Sortierregeln hinzu, um die Reihenfolge der Ergebnisse zu steuern (z. B. absteigend nach timestamp sortieren, um die neuesten zuerst zu erhalten).
• Filters: Fügen Sie Feldfilter hinzu, um Ergebnisse anhand von Attributwerten einzugrenzen, mit denselben Operatoren wie bei Runtime-Abfragen.

Konfiguration einer Stream Data Aggregation

Für Stream-Data-Aggregation-Queries:

• Aggregation Columns: Wählen Sie Attribute und weisen Sie jedem eine Aggregationsfunktion zu:
  • AVG — Durchschnittswert
  • MIN — Minimalwert
  • MAX — Maximalwert
  • COUNT — Anzahl der Datenpunkte
  • SUM — Summe der Werte
• Time Range: Optionale From-/To-Einschränkung.
• Limit: Maximale Anzahl zurückzugebender Zeilen.
• Filters: Optionale Filter auf Feldebene, die vor der Aggregation angewendet werden.

Konfiguration einer Stream Data Grouped Aggregation

Für Stream-Data-Grouped-Aggregation-Queries:

• Group By: Wählen Sie ein oder mehrere Attribute, nach denen die Ergebnisse gruppiert werden (z. B. Gruppierung nach rtId, um Aggregationen pro Entität zu erhalten).
• Aggregation Columns: Wie bei Aggregation-Queries — wählen Sie Attribute mit Aggregationsfunktionen.
• Time Range, Limit und Filters: Wie oben.

Konfiguration von Stream Data Downsampling

Downsampling teilt einen Zeitbereich in gleich große Buckets und berechnet eine Aggregation pro Bucket. Dies ist ideal für Diagramm- und Dashboard-Visualisierungen.

• Aggregation Columns: Wählen Sie Attribute mit Aggregationsfunktionen (AVG, MIN, MAX).
• From und To: Erforderlich — definieren den zu downsamplenden Zeitbereich.
• Limit: Erforderlich — die Anzahl der zu erzeugenden Zeit-Buckets. Die Bucket-Größe wird als (to - from) / limit berechnet. Ein 24-Stunden-Bereich mit Limit 24 erzeugt beispielsweise stündliche Buckets.
• Filters: Optionale Filter auf Feldebene.

Stream-Data-Ergebnisse ausführen und anzeigen

Klicken Sie auf EXECUTE, um die Stream-Data-Abfrage auszuführen. Die Ergebnisse werden in Tabellenform angezeigt mit:

• Timestamp: Der Zeitpunkt jedes Datenpunkts (bzw. der Bucket-Beginn beim Downsampling)
• Entity: Die Runtime-Entität (rtId / rtWellKnownName), zu der die Daten gehören
• Data columns: Die angeforderten Attributwerte oder aggregierten Ergebnisse

Die Ergebnisse unterstützen Paginierung für große Datenmengen.

Stream Data Queries speichern

Klicken Sie auf SAVE, um die Stream-Data-Abfrage zu speichern. Gespeicherte Stream Data Queries können:

• aus der Query-Builder-Liste erneut ausgeführt werden
• als Datenquellen in MeshBoard-Widgets (KPI, Gauge, Chart, Table) verwendet werden
• von externen Werkzeugen wie Power BI oder Grafana referenziert werden

---

Bewährte Vorgehensweisen

1. Abfragen aussagekräftig benennen: Verwenden Sie klare Namen, die angeben, was die Abfrage zurückgibt
2. Filter effektiv einsetzen: Grenzen Sie Ergebnisse ein, um die Performance zu verbessern
3. Nur benötigte Spalten auswählen: Nehmen Sie nur die Attribute auf, die Sie benötigen, um die Datenübertragung zu reduzieren
4. Vor dem Speichern testen: Führen Sie die Abfrage aus, um die Ergebnisse vor dem Speichern zu überprüfen
5. Aggregationen für Zusammenfassungen verwenden: Verwenden Sie Aggregation-Queries, anstatt alle Daten abzurufen und clientseitig zu berechnen
6. Performance berücksichtigen: Komplexe Abfragen auf großen Datenmengen können länger dauern
7. Downsampling für Diagramme verwenden: Verwenden Sie beim Visualisieren von Zeitreihendaten auf Dashboards Downsampling, um die Datenpunkte auf eine handhabbare Zahl zu reduzieren, die zur Auflösung Ihres Diagramms passt
8. Zeitbereiche setzen: Setzen Sie bei Stream-Data-Abfragen immer einen Zeitbereich, um zu vermeiden, dass die gesamte Historie abgefragt wird

Anwendungsfälle

Datenexploration

• Entitäten eines bestimmten Typs durchsuchen
• Nach Entitäten suchen, die Kriterien erfüllen
• Attribute und Beziehungen von Entitäten anzeigen

Zeitreihenanalyse

• Historische Sensormesswerte für eine bestimmte Maschine anzeigen
• Spannungstrends über mehrere Energiezähler hinweg vergleichen
• Anomalien in Messdaten erkennen

Berichtswesen

• Entitäten nach Status zählen
• Durchschnitte und Summen berechnen
• Daten gruppieren und zusammenfassen
• Periodische Zusammenfassungen von Zeitreihenkennzahlen erstellen

Dashboard-Datenquellen

• Abfragen für MeshBoard-Widgets erstellen
• Wiederverwendbare Datenextraktionen aufbauen
• Gefilterte Ansichten für spezifische Anwendungsfälle einrichten
• Downsampling-Abfragen für Zeitreihen-Diagramm-Widgets verwenden

Power-BI-Integration

• Gespeicherte Abfragen als Datenquellen für Power-BI-Berichte und -Dashboards verwenden
• Aggregation-Queries für vorberechnete Zusammenfassungen in Power BI nutzen

Grafana-Integration

• Gespeicherte Abfragen mit Grafana-Dashboards für die Echtzeitüberwachung verbinden
• Aggregation-Queries für Zeitreihen- und Metrik-Visualisierungen verwenden