# SQL-Variablen

Denken Sie an Lücken in einem Serienbrief - Sie schreiben den Brief einmal mit Platzhaltern für "Name" und "Abteilung", dann können Sie jedes Mal, wenn Sie ihn verwenden, verschiedene Werte einsetzen. SQL-Variablen ermöglichen es Ihnen, eine Abfrage zu schreiben, die verschiedene Ergebnisse basierend auf den Werten zeigt, die Sie bereitstellen.

## Was SQL-Variablen sind

SQL-Variablen sind Platzhalter in Ihren SQL-Abfragen, die es Ihnen ermöglichen:

* **Flexible Abfragen zu erstellen** - Einmal schreiben, mit verschiedenen Werten verwenden
* **Verschiedene Szenarien zu testen** - Verschiedene Werte ausprobieren, ohne SQL umzuschreiben
* **Dynamische Berichte zu erstellen** - Dieselbe Abfrage zeigt verschiedene Daten basierend auf der Benutzerauswahl
* **Mit Berichtsfiltern zu verbinden** - Variablen werden zu benutzerfreundlichen Filtern in Berichten

**Beispiel aus der Praxis**: Anstatt separate Abfragen für jede Abteilung zu schreiben, schreiben Sie eine Abfrage mit `$abteilung` und testen sie dann mit "Öffentliche Sicherheit", "Gesundheitsdienste" oder jedem anderen Abteilungsnamen.

## Variablen-Syntax

Variablen verwenden eine einfache Dollar-Zeichen-Syntax in Ihren SQL-Abfragen.

```sql
SELECT abteilung, status, budget, erstellungsdatum
FROM projekte 
WHERE abteilung = $abteilungsfilter
  AND status = $projektstatus
  AND budget >= $mindestbudget
  AND erstellungsdatum >= $startdatum
```

{% hint style="info" %}
**Hinweis:** Derzeit können Variablen nur in WHERE-Klauseln verwendet werden.
{% endhint %}

**Regeln für Variablennamen:**

* **Muss mit Buchstabe oder Unterstrich beginnen**: `$abteilung` ✅, `$_filter` ✅
* **Kann Buchstaben, Zahlen, Unterstriche enthalten**: `$region_2024` ✅, `$statusfilter` ✅
* **Kann nicht mit Zahlen beginnen**: `$2024_daten` ❌
* **Kann keine Leerzeichen oder Sonderzeichen enthalten**: `$mein-filter` ❌, `$mein filter` ❌

**Aktuelle Einschränkungen:**

* **Nur WHERE-Klausel**: Variablen können nur in WHERE-Bedingungen verwendet werden
* **Keine Spaltennamen**: Variablen können nicht für SELECT-Spalten wie `SELECT $spaltenname FROM tabelle` verwendet werden
* **Kein GROUP BY/ORDER BY**: Variablen können nicht in `GROUP BY $gruppenfeld` oder `ORDER BY $sortierfeld` verwendet werden

Für vollständige technische Details siehe [DuckDBs Dokumentation zu benannten Parametern](https://duckdb.org/docs/stable/sql/query_syntax/prepared_statements.html#named-parameters-parameter).

{% hint style="info" %}
Verwenden Sie beschreibende Namen wie `$abteilungsfilter` oder `$startdatum` anstatt generische Namen wie `$var1` oder `$x`. Dies macht Ihre Abfragen später leichter verständlich.
{% endhint %}

## Wie Variablen in der Benutzeroberfläche funktionieren

Wenn Sie eine SQL-Abfrage mit Variablen schreiben, erkennt das System sie automatisch und erstellt interaktive Steuerelemente über der Tabellenvorschau oder Diagrammvorschau auf der linken Seite der Benutzeroberfläche.

### Variablen steuern

Jede Variable bekommt ihre eigene kleine Steuerung, in der Ihnen folgende Funktionen zur Verfügung stehen:

{% stepper %}
{% step %}
**Mit verschiedenen Variablentypen testen**

Sie können Ihre Variablen mit verschiedenen Datentypen testen:

* **Text** - Für Namen, Kategorien, Beschreibungen
* **Zahl** - Für Beträge, Anzahlen, IDs
* **Datum** - Für zeitbasierte Filterung (YYYY-MM-DD-Format)

Die Benutzeroberfläche ermöglicht es Ihnen zu testen, wie sich Ihre Abfrage mit verschiedenen Arten von Werten verhält.
{% endstep %}

{% step %}
**Einzelne oder mehrere Werte wählen**

**Einzelwert-Modus:**

* Geben Sie einen Wert ein, der die Variable ersetzt
* Beispiel: `$abteilung` wird zu `"Öffentliche Sicherheit"`

**Mehrwert-Modus:**

* Geben Sie mehrere Werte getrennt durch Semikolons ein
* Beispiel: `$statusliste` wird zu `"Aktiv; Ausstehend; Überprüfung"`
* Verwenden Sie mit `IN`-Klausel: `WHERE status IN ($statusliste)`
  {% endstep %}

{% step %}
**Ihre Testwerte eingeben**

**Für Textwerte:**

* Direkt tippen: `Öffentliche Sicherheit`
* Mehrere Werte: `Aktiv; Ausstehend; Abgeschlossen`
* Semikolons wörtlich einschließen: `Text mit \; Semikolon`

**Für Zahlen:**

* Einzeln: `1000`
* Mehrere: `100; 500; 1000`

**Für Daten:**

* Immer YYYY-MM-DD-Format verwenden: `2024-01-15`
* Nur einzelnes Datum (keine mehreren Datumswerte)
  {% endstep %}

{% step %}
**Ihre Abfrage testen**

Klicken Sie **"Anwenden"** auf der Variablen-Pill, um mit diesen Werten zu testen, dann führen Sie Ihre Abfrage aus, um die Ergebnisse zu sehen.
{% endstep %}
{% endstepper %}

## Häufige Variablenmuster

### Einzelwert-Filterung

```sql
SELECT abteilung, COUNT(*) as mitarbeiteranzahl
FROM mitarbeiter 
WHERE abteilung = $abteilung
GROUP BY abteilung
ORDER BY mitarbeiteranzahl DESC
```

**Variablen-Setup:**

* Name: `abteilung`
* Testen mit: Textwerten wie `Öffentliche Sicherheit`
* Modus: Einzelwert

### Mehrwert-Filterung

```sql
SELECT * 
FROM projekte
WHERE status IN $statusliste
  AND prioritaet IN $prioritaetsliste
ORDER BY erstellungsdatum DESC
```

**Variablen-Setup:**

* Name: `statusliste`
* Testen mit: Mehreren Textwerten wie `Aktiv; Überprüfung; Planung`
* Modus: Mehrere Werte

### Datumsbereichs-Filterung

```sql
SELECT * 
FROM budgetposten
WHERE erstellungsdatum >= $startdatum 
  AND erstellungsdatum <= $enddatum
  AND betrag >= $mindestbetrag
ORDER BY erstellungsdatum
```

**Variablen-Setup:**

* `startdatum`: Testen mit Datumswerten wie `2024-01-01`
* `enddatum`: Testen mit Datumswerten wie `2024-12-31`
* `mindestbetrag`: Testen mit Zahlenwerten wie `1000`

### Umgang mit leeren Variablen

Wenn kein Filter angewendet werden soll, verwenden Sie dieses Muster, um alle Daten zu zeigen:

```sql
SELECT * 
FROM projekte
WHERE (abteilung = $abteilung OR $abteilung IS NULL)
  AND (status IN $statusliste OR array_length($statusliste) = 0)
```

Dies gewährleistet:

* Wenn Sie `$abteilung` auf "Öffentliche Sicherheit" setzen, zeigen nur diese Projekte
* Wenn Sie `$abteilung` leer lassen, zeigen ALLE Abteilungen
* Dieselbe Logik funktioniert für die Statusliste

**Wichtiger Unterschied für Mehrfachauswahl-Variablen:**

* **Einzelwert-Variablen** verwenden `OR $variable IS NULL` wenn leer
* **Mehrfachauswahl-Variablen** verwenden `OR array_length($variable) = 0` wenn keine Optionen ausgewählt sind

Mehrfachauswahl-Filter senden leere Arrays (nicht Null-Werte) wenn keine Auswahl im Filter getroffen wurde (leere Auswahl). Die `array_length()`-Funktion gibt 0 für leere Arrays zurück, wodurch Ihre Abfrage alle Daten anzeigen kann, wenn keine Filteroptionen ausgewählt sind.

{% hint style="success" %}
**Profi-Tipp**: Schließen Sie immer das richtige Muster für leere Filter ein:

* Einzelwert-Variablen: `OR $variable IS NULL`
* Mehrfachauswahl-Variablen: `OR array_length($variable) = 0`

Dies macht Ihre Abfragen funktionsfähig, egal ob Filter gesetzt sind oder nicht, was besonders wichtig ist, wenn Sie Variablen in Berichten verwenden.
{% endhint %}

## Variablen in Auswertungen testen

Variablen sind perfekt zum Testen verschiedener Szenarien beim Erstellen von Auswertungen:

### Entwicklungsworkflow

{% stepper %}
{% step %}
**Schreiben Sie Ihre Basis-Abfrage**

Beginnen Sie mit einer Abfrage, die ohne Variablen funktioniert:

```sql
SELECT abteilung, AVG(budget) as durchschnittsbudget
FROM projekte 
WHERE status = 'Aktiv'
GROUP BY abteilung
```

{% endstep %}

{% step %}
**Fügen Sie Variablen für Flexibilität hinzu**

Ersetzen Sie feste Werte durch Variablen:

```sql
SELECT abteilung, AVG(budget) as durchschnittsbudget
FROM projekte 
WHERE (status IN $statusfilter OR array_length($statusfilter) = 0)
  AND (abteilung = $abteilungsfilter OR $abteilungsfilter IS NULL)
GROUP BY abteilung
```

{% endstep %}

{% step %}
**Verschiedene Szenarien testen**

Verwenden Sie die Variablen-Pills zum Testen:

* Alle aktiven Projekte: `statusfilter` = `Aktiv`
* Aktiv und ausstehend: `statusfilter` = `Aktiv; Ausstehend`
* Spezifische Abteilung: `abteilungsfilter` = `Gesundheitsdienste`
* Alle Abteilungen: `abteilungsfilter` leer lassen
  {% endstep %}

{% step %}
**Verifizieren Sie, dass Ergebnisse Sinn machen**

Überprüfen Sie, dass Ihre Abfrage erwartete Ergebnisse für jeden Testfall zurückgibt, bevor Sie sie in Berichten verwenden.
{% endstep %}
{% endstepper %}

## Von Variablen in Auswertungen zu Berichtsfiltern

Die wahre Macht von Variablen zeigt sich, wenn Sie Auswertungen mit Variablen in Berichten verwenden:

### Die Verbindung

1. **In Auswertungen**: Variablen ermöglichen es Ihnen, verschiedene Abfrageparameter zu testen
2. **In Berichten**: Dieselben Variablen können zu benutzerfreundlichen Filtern werden
3. **Für Endnutzer des Berichts**: Sie sehen Menüs und Datumsauswähler, nicht rohen SQL-Code

### Beispiel-Transformation

**Ihre SQL-Auswertung mit Variablen:**

```sql
SELECT abteilung, COUNT(*) as projektanzahl
FROM projekte
WHERE (status IN $projektstatus OR array_length($projektstatus) = 0)
  AND (erstellungsdatum >= $startdatum OR $startdatum IS NULL)
```

**Wird zu diesem für Berichtsbenutzer:**

* **Projektstatus**-Filter mit Auswahl: "Aktiv", "Ausstehend", "Abgeschlossen"
* **Startdatum**-Filter für die Auswahl des frühesten einzuschließenden Datums

### Warum das wichtig ist

* **Entwickler** arbeiten mit flexiblen SQL-Abfragen mit Variablen
* **Berichts-Ersteller** verbinden Variablen mit benutzerfreundlichen Filter-Benutzeroberflächen
* **Endnutzer** bekommen intuitive Steuerelemente, ohne SQL-Code zu sehen oder zu bearbeiten

Für vollständige Details zur Verbindung von Variablen mit Berichtsfiltern siehe [**Berichtsfilter**](/berichte/filter.md).

## Tipps

### Variablennamen

* **Seien Sie beschreibend**: `$abteilungsfilter` nicht `$a`
* **Seien Sie konsistent**: Wenn Sie das `_filter`-Suffix verwenden, verwenden Sie es überall
* **Passen Sie zu Ihren Daten**: Verwenden Sie Namen, die zu Ihren Spaltennamen passen, wenn möglich

### Abfrage-Design

* **Behandeln Sie Nulls ordnungsgemäß**: Schließen Sie immer `OR $variable IS NULL` für optionale Filter ein
* **Testen Sie gründlich**: Probieren Sie leere Werte, Einzelwerte und mehrere Werte
* **Verwenden Sie angemessene SQL-Klauseln**: `=` für Einzelwerte, `IN` für Listen

### Variablentypen

* **Text**: Für Kategorien, Namen, Beschreibungen
* **Zahl**: Für Beträge, Anzahlen, IDs
* **Datum**: Nur für Datumswerte, immer YYYY-MM-DD-Format

### Test-Ablauf

1. **Beginnen Sie einfach**: Testen Sie zuerst mit Einzelwerten
2. **Fügen Sie Komplexität hinzu**: Probieren Sie mehrere Werte und Kombinationen
3. **Testen Sie Grenzfälle**: Leere Werte, alle Werte, keine Treffer
4. **Verifizieren Sie Logik**: Stellen Sie sicher, dass NULL-Behandlung korrekt funktioniert

{% hint style="warning" %}
**Denken Sie daran**: Variablen sind abhängig von Groß- und Kleinschreibung. `$Abteilung` und `$abteilung` sind verschiedene Variablen. Bleiben Sie bei Kleinschreibung mit Unterstrichen für Konsistenz.
{% endhint %}

## Häufige Problembehandlung

### Variable nicht erkannt

**Problem**: Sie haben `$abteilung` getippt, aber sehen keine Variable wird erkannt

**Lösung**: Überprüfen Sie die Rechtschreibung und stellen Sie sicher, dass der Variablenname den Namensregeln folgt

### Abfrage schlägt mit Variablen fehl

**Problem**: Abfrage funktioniert ohne Variablen, aber schlägt fehl, wenn Sie sie hinzufügen

**Lösung**: Überprüfen Sie Ihre NULL-Behandlung - fügen Sie `OR $variable IS NULL`-Bedingungen hinzu

### Falscher Datentyp

**Problem**: Ihre Datumsvariable zeigt Textwerte oder Zahlen werden als Text angezeigt

**Lösung**: Testen Sie mit dem korrekten Datentyp in der Variablen-Benutzeroberfläche - probieren Sie Datumsformat YYYY-MM-DD für Daten

### Mehrere Werte funktionieren nicht

**Problem**: Mehrere Werte in einer Variable filtern nicht korrekt

**Lösung**: Stellen Sie sicher, dass Sie `IN ($variable)` und nicht `= $variable` für Listen verwenden

## Erweiterte Muster

### Komplexe Filterung

```sql
SELECT * 
FROM projekte
WHERE 
  -- Datumsbereichs-Filterung
  (erstellungsdatum BETWEEN $startdatum AND $enddatum 
   OR ($startdatum IS NULL AND $enddatum IS NULL))
  
  -- Multi-Kriterien-Filterung  
  AND (
    (abteilung IN $abteilungsliste OR array_length($abteilungsliste) = 0)
    AND (status IN $statusliste OR array_length($statusliste) = 0)
    AND (budget >= $mindestbudget OR $mindestbudget IS NULL)
  )
```

{% hint style="info" %}
**Denken Sie daran**: Variablen können nur in WHERE-Klauseln verwendet werden. Komplexe Logik mit CASE-Anweisungen, dynamische Spaltenauswahl oder variable GROUP BY/ORDER BY-Klauseln werden derzeit nicht unterstützt.
{% endhint %}

Bereit, Variablen in Berichten zu verwenden? Erfahren Sie, wie Sie Ihre SQL-Auswertungen mit benutzerfreundlichen Berichtsfiltern in der [**Berichtsfilter-Dokumentation**](/berichte/filter.md) verbinden.


---

# Agent Instructions: 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:

```
GET https://docs.polyteia.com/auswertungen/sql-editor/sql-variablen.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.