> For the complete documentation index, see [llms.txt](https://docs.enlyze.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enlyze.com/integrations/grafana/advanced-api/02-api-queries.md).

# 02 ENLYZE API abfragen

In diesem Tutorial lernst du, Produktionsdaten mit dynamischen Zeitbereichen abzufragen, OEE-Kennzahlen zu extrahieren und Daten aus mehreren Queries zu verknüpfen:

<figure><img src="/files/TTSqOLU6W35M9cyBNX9d" alt=""><figcaption></figcaption></figure>

## Was du lernst

* Grafanas Zeitbereich in API-Abfragen verwenden
* Aufträge mit OEE-Kennzahlen abfragen
* Verschachtelte JSON-Werte mit JSONata extrahieren
* Daten mehrerer Maschinen zusammenführen
* Aufträge mit Produktdaten verknüpfen (Join)

## Voraussetzungen

* [Einführung in die ENLYZE API](/integrations/grafana/advanced-api/01-introduction.md) abgeschlossen
* Verständnis von GET-Anfragen und Root Selector `$.data`

***

## Dynamische Zeitbereiche

In der [Einführung](/integrations/grafana/advanced-api/01-introduction.md) hast du feste Endpunkte abgefragt. Für Produktionsdaten brauchst du einen dynamischen Zeitbereich, der sich mit Grafanas Zeitauswahl aktualisiert.

| Variable             | Beschreibung            |
| -------------------- | ----------------------- |
| `${__from:date:iso}` | Startzeit im ISO-Format |
| `${__to:date:iso}`   | Endzeit im ISO-Format   |

Diese Variablen werden automatisch durch den aktuellen Zeitbereich des Dashboards ersetzt.

***

## Aufträge abfragen

Der `production-runs`-Endpunkt liefert Produktionsaufträge inklusive OEE-Kennzahlen.

### Query konfigurieren

1. Erstelle ein neues Panel mit der Visualisierung **Table**
2. Wähle die Data Source **ENLYZE API**
3. Konfiguriere die Query:

| Einstellung | Wert              |
| ----------- | ----------------- |
| Type        | JSON              |
| Parser      | Backend           |
| Source      | URL               |
| Format      | Table             |
| Method      | GET               |
| URL         | `production-runs` |

4. Klappe **Headers, Request params** auf und füge unter **URL Query Params** hinzu:

| Key       | Value                                  |
| --------- | -------------------------------------- |
| `machine` | `141e0927-62b3-4e76-8398-ad82d20f397f` |
| `start`   | `${__from:date:iso}`                   |
| `end`     | `${__to:date:iso}`                     |

5. Setze den **Root selector** auf `$.data`

{% hint style="info" %}
Konfiguriere Query-Parameter immer über die Grafana-Oberfläche unter **Headers, Request params** statt sie direkt in die URL zu schreiben. Das ist übersichtlicher und vermeidet Encoding-Probleme.
{% endhint %}

<figure><img src="/files/bewwrFySjN7c9mbDVnEM" alt=""><figcaption></figcaption></figure>

Die Tabelle zeigt die rohe API-Antwort. OEE-Kennzahlen wie `productivity`, `availability` und `performance` sind verschachtelte Objekte. Im nächsten Schritt extrahierst du diese Werte.

***

## Verschachtelte Werte mit JSONata extrahieren

JSONata erlaubt es, verschachtelte Werte direkt im Root Selector zu extrahieren und umzustrukturieren. Ersetze `$.data` durch:

```
$.data.{
  "production_order": production_order,
  "start": start,
  "end": end,
  "productivity": productivity.score,
  "availability": availability.score,
  "performance": performance.score,
  "quality": quality.score,
  "yield": quantity_yield.value
}
```

<figure><img src="/files/5d7zZE3Z9sTQhaDGhVKt" alt=""><figcaption></figcaption></figure>

Jede Zeile enthält jetzt die extrahierten OEE-Scores und die produzierte Menge (Yield).

### JSONata-Grundlagen

| Ausdruck            | Beschreibung               |
| ------------------- | -------------------------- |
| `$.data`            | Zugriff auf das data-Array |
| `field.subfield`    | Verschachtelte Eigenschaft |
| `{ "name": value }` | Neues Objekt erstellen     |

***

## Spalten konfigurieren (Columns)

Statt JSONata kannst du auch die **Columns**-Funktion der Infinity-Query verwenden. Klappe **Parsing options & Result fields** auf und füge unter **Columns** hinzu:

| Selector               | Title        | Type      |
| ---------------------- | ------------ | --------- |
| `production_order`     | Order        | String    |
| `start`                | Start        | Timestamp |
| `end`                  | End          | Timestamp |
| `productivity.score`   | OEE          | Number    |
| `availability.score`   | Availability | Number    |
| `performance.score`    | Performance  | Number    |
| `quality.score`        | Quality      | Number    |
| `quantity_yield.value` | Yield        | Number    |

### OEE-Werte farblich hervorheben

Für die OEE-Spalten bieten sich farbige Zellen an. Füge einen **Field override** für Felder mit Regex `/OEE|Availability|Performance|Quality/` hinzu:

* **Unit**: Percent (0.0-1.0)
* **Min**: 0, **Max**: 1
* **Cell type**: Color background
* **Value mappings**: Farbabstufungen von Rot (< 60 %) über Orange und Gelb bis Grün (> 95 %) sowie `null` → "NO DATA" in Grau

<figure><img src="/files/NXehx3uKXvDLCavg7KSg" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Bei Maschinen ohne Qualitätsdaten zeigt die Quality-Spalte "NO DATA" an. Der OEE (Productivity) wird in diesem Fall aus Availability und Performance berechnet. Mehr dazu in der [OEE-Dokumentation](/konzepte/oee-verstehen/das-konzept-oee.md).
{% endhint %}

***

## OEE als Stat-Panel

Den OEE des letzten Auftrags kannst du auch als Stat-Panel darstellen:

1. Erstelle ein neues Panel mit **Stat**-Visualisierung
2. Konfiguriere die gleiche `production-runs`-Query mit den Query Params wie oben
3. Setze den Root Selector auf `$.data[0].productivity.score`
4. Unit auf **Percent (0.0-1.0)**, Color mode auf **Background**
5. Thresholds: Rot (Basis), Gelb (0.6), Grün (0.8)

<figure><img src="/files/ge0GQJ1OOoxIiI590RAQ" alt=""><figcaption></figcaption></figure>

Erstelle nach dem gleichen Muster weitere Panels für Availability (`$.data[0].availability.score`), Performance (`$.data[0].performance.score`) und Quality (`$.data[0].quality.score`). Für Quality konfiguriere ein Value Mapping für `null` → "NO DATA", da nicht alle Maschinen Qualitätsdaten liefern.

***

## Aufträge mehrerer Maschinen zusammenführen

Um Aufträge mehrerer Maschinen in einer Tabelle anzuzeigen, konfiguriere zwei Queries mit jeweils einer eigenen Computed Column für den Maschinennamen.

**Query A (Kiefel):**

| Einstellung  | Wert                                                                                   |
| ------------ | -------------------------------------------------------------------------------------- |
| URL          | `production-runs`                                                                      |
| Query Params | `machine` = `141e0927-...`, `start` = `${__from:date:iso}`, `end` = `${__to:date:iso}` |

Unter **Computed columns**: Selector `"Kiefel"`, Title `Machine`

**Query B (Macchi):**

| Einstellung  | Wert                                                                                   |
| ------------ | -------------------------------------------------------------------------------------- |
| URL          | `production-runs`                                                                      |
| Query Params | `machine` = `cc0d2dcb-...`, `start` = `${__from:date:iso}`, `end` = `${__to:date:iso}` |

Unter **Computed columns**: Selector `"Macchi"`, Title `Machine`

Füge eine **Merge**-Transformation hinzu, um beide Queries in einer Tabelle zu vereinen.

<figure><img src="/files/9sTrmRm73Y6U4adkImnu" alt=""><figcaption></figcaption></figure>

***

## Mit Produktdaten verknüpfen

Aufträge enthalten nur eine Produkt-UUID. Um den Produktnamen anzuzeigen, verknüpfe die Daten mit dem `products`-Endpunkt.

### Zwei Queries erstellen

**Query A (Aufträge):**

| Einstellung  | Wert                                                                                   |
| ------------ | -------------------------------------------------------------------------------------- |
| URL          | `production-runs`                                                                      |
| Query Params | `machine` = `141e0927-...`, `start` = `${__from:date:iso}`, `end` = `${__to:date:iso}` |

Columns: `production_order` → Order, `product` → product\_uuid, `start` → Start, `productivity.score` → OEE

**Query B (Produkte):**

| Einstellung   | Wert       |
| ------------- | ---------- |
| URL           | `products` |
| Root selector | `$.data`   |

Columns: `uuid` → product\_uuid, `external_id` → Product ID, `name` → Product Name

**Wichtig:** Das Join-Feld muss in beiden Queries denselben Spaltennamen haben (`product_uuid`).

### Join-Transformation

1. Wechsle zum Tab **Transform**
2. Füge **Join by field** hinzu: Mode **INNER**, Field **product\_uuid**
3. Optional: **Organize fields** hinzufügen, um `product_uuid` auszublenden

<figure><img src="/files/tX9GelAm41LzFZsz41KX" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/h98tJBUn9PVIoBVVRFAb" alt=""><figcaption></figcaption></figure>

***

## Stillstände

Maschinenstillstände lassen sich über den `downtimes`-Endpunkt abfragen:

| Einstellung   | Wert                                                                             |
| ------------- | -------------------------------------------------------------------------------- |
| URL           | `downtimes`                                                                      |
| Query Params  | `machine` = `{uuid}`, `start` = `${__from:date:iso}`, `end` = `${__to:date:iso}` |
| Root selector | `$.data`                                                                         |

Die API liefert neben Start- und Endzeitpunkt auch den Stillstandsgrund und dessen Kategorie. Nutze **Columns**, um die relevanten Felder zu extrahieren:

| Selector          | Title       | Type      |
| ----------------- | ----------- | --------- |
| `uuid`            | Downtime ID | String    |
| `start`           | Start       | Timestamp |
| `end`             | End         | Timestamp |
| `reason.name`     | Reason      | String    |
| `reason.category` | Category    | String    |

***

## Tipps

* **Immer mit Table testen**: Rohdaten sind in Tabellen leichter zu lesen. Erst nach funktionierender Query zu anderen Visualisierungen wechseln.
* **Query Params nutzen**: Konfiguriere Parameter über die Grafana-Oberfläche statt sie direkt in die URL zu schreiben.
* **Root Selector schrittweise aufbauen**: Mit `$.data` beginnen, Datenstruktur überprüfen, dann JSONata ergänzen.
* **Leere Daten**: Zeitbereich erweitern oder prüfen, ob die Maschine im gewählten Zeitraum lief.

***

## Nächste Schritte

* [**Mit Variablen arbeiten**](/integrations/grafana/advanced-api/03-variables.md) — Dropdowns für Standort- und Maschinenauswahl erstellen


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.enlyze.com/integrations/grafana/advanced-api/02-api-queries.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.