> ## Documentation Index
> Fetch the complete documentation index at: https://docs.varios-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MSSQL

> Der MSSQL-Konnektor ermöglicht die Verbindung zu Microsoft SQL Server-Datenbanken und die Ausführung von SQL-Abfragen. Mit diesem Konnektor können Sie Daten aus Ihren SQL Server-Datenbanken abrufen und analysieren.

## Optionen

<ParamField body="host" type="string" required>
  Der Hostname oder die IP-Adresse des MSSQL-Servers.
</ParamField>

<ParamField body="port" type="string" required>
  Der Port des MSSQL-Servers.
</ParamField>

<ParamField body="username" type="string" required>
  Der Benutzername für die Anmeldung.
</ParamField>

<ParamField body="password" type="string" required>
  Das Passwort für die Anmeldung.
</ParamField>

<ParamField body="database" type="string" required>
  Der Name der Datenbank.
</ParamField>

<ParamField body="query" type="string" required>
  Das SQL-Statement, das ausgeführt werden soll. Werte aus den Argumenten
  werden über die Platzhalter `?1` bis `?10` eingesetzt. Setzen Sie Platzhalter
  nicht in Anführungszeichen.
</ParamField>

## Platzhalter im SQL-Statement

Die Platzhalter `?1` bis `?10` verweisen auf die Argumente `argument1` bis `argument10`. Maßgeblich ist dabei die Nummer, nicht die Reihenfolge im Statement. Ein Platzhalter darf mehrfach vorkommen.

Die Werte werden als Parameter an die Datenbank übergeben und dort ausschließlich als Werte behandelt, nicht als Teil des Statements. Das verhindert SQL-Injection und macht ein eigenes Maskieren oder Quoten unnötig.

Daraus ergeben sich drei Regeln:

* Platzhalter stehen immer ohne Anführungszeichen im Statement: `WHERE kunde = ?1` ist korrekt, `WHERE kunde = '?1'` nicht.
* Platzhalter stehen nur für Werte. Datenbank-, Tabellen- und Spaltennamen müssen fest im Statement hinterlegt sein.
* Zusätzliche Zeichen wie Wildcards werden an den Platzhalter angehängt, statt in ihn hineingeschrieben zu werden.

<Warning>
  Ein Platzhalter in Anführungszeichen wird zu festem Text und nicht zum
  übergebenen Wert. Die beiden Fehlerbilder unterscheiden sich: `LIKE '%?1%'`
  sucht nach dem festen Text `?1` und liefert ein leeres Ergebnis, ohne dass ein
  Fehler entsteht. `datum >= '?2'` erzeugt dagegen einen Konvertierungsfehler in
  SQL Server, den der Konnektor als fehlgeschlagene Abfrage meldet.
</Warning>

### Suche mit LIKE

Die Prozentzeichen gehören als eigenständiger Text in das Statement und werden mit dem Platzhalter verbunden:

```sql theme={null}
WHERE kunde LIKE '%' + ?1 + '%'
```

Gleichwertig ist `WHERE kunde LIKE CONCAT('%', ?1, '%')`. Nicht verwendbar ist `WHERE kunde LIKE '%?1%'`.

### Datums- und Zahlenwerte

Argumente werden immer als Text übergeben. Verwenden Sie für Datumswerte das Format `yyyy-mm-dd`; SQL Server wandelt es beim Vergleich automatisch in einen Datumswert um:

```sql theme={null}
WHERE datum >= ?2 AND datum < ?3
```

Fragen Sie einen Zeitraum mit `>=` für den Beginn und `<` für das Ende ab. Bei Spalten mit Uhrzeit fehlen sonst die Einträge des letzten Tages. Soll die Umwandlung ausdrücklich im Statement stehen, verwenden Sie `CAST(?2 AS date)`.

### Nicht gefüllte Argumente

Nicht gefüllte Argumente werden als leerer Text übergeben. Bei einer LIKE-Suche entsteht daraus `LIKE '%%'`, das alle Datensätze zurückgibt. Beschreiben Sie deshalb bei jedem Argument, welcher Wert und welches Format erwartet werden. `argument1` ist ein Pflichtfeld: Ohne Wert führt der Konnektor die Abfrage nicht aus.

## Argumente

<ParamField body="argument1" type="string" required>
  Wert für den ersten Parameter im SQL-Statement.
</ParamField>

<ParamField body="argument2" type="string">
  Wert für den zweiten Parameter im SQL-Statement.
</ParamField>

<ParamField body="argument3" type="string">
  Wert für den dritten Parameter im SQL-Statement.
</ParamField>

<ParamField body="argument4" type="string">
  Wert für den vierten Parameter im SQL-Statement.
</ParamField>

<ParamField body="argument5" type="string">
  Wert für den fünften Parameter im SQL-Statement.
</ParamField>

<ParamField body="argument6" type="string">
  Wert für den sechsten Parameter im SQL-Statement.
</ParamField>

<ParamField body="argument7" type="string">
  Wert für den siebten Parameter im SQL-Statement.
</ParamField>

<ParamField body="argument8" type="string">
  Wert für den achten Parameter im SQL-Statement.
</ParamField>

<ParamField body="argument9" type="string">
  Wert für den neunten Parameter im SQL-Statement.
</ParamField>

<ParamField body="argument10" type="string">
  Wert für den zehnten Parameter im SQL-Statement.
</ParamField>

## Beispiel

Die folgende Abfrage sucht Verträge eines Kunden, deren Laufzeit in einem bestimmten Zeitraum endet. Der Kundenname wird als Teilbegriff gesucht, der Zeitraum über zwei Datumswerte eingegrenzt.

Option `query`:

```sql theme={null}
SELECT vertragsnummer, kunde, produkt, status, laufzeit_ende
FROM crm.dbo.vertraege
WHERE kunde LIKE '%' + ?1 + '%'
  AND laufzeit_ende >= ?2
  AND laufzeit_ende <  ?3
ORDER BY laufzeit_ende ASC;
```

Beschreibung der Argumente:

```
argument1: Name oder Namensbestandteil des Kunden / Beispiel: `Muster GmbH`
argument2: Beginn des Zeitraums. Format: `yyyy-mm-dd` / Beispiel: `2025-01-01`
argument3: Ende des Zeitraums, nicht enthalten. Format: `yyyy-mm-dd` / Beispiel: `2025-07-01`
```

Mit den Werten `Muster`, `2025-01-01` und `2025-07-01` führt die Datenbank die Abfrage so aus, als stünde dort `kunde LIKE '%Muster%'` und `laufzeit_ende >= '2025-01-01' AND laufzeit_ende < '2025-07-01'`.

## Fehlerbehebung

<AccordionGroup>
  <Accordion title="Die Abfrage liefert keine Daten, obwohl sie direkt auf der Datenbank funktioniert">
    Prüfen Sie, ob die Platzhalter in Anführungszeichen stehen. `'%?1%'` wird
    als fester Text ausgeführt und liefert deshalb ein leeres Ergebnis statt
    eines Fehlers. Schreiben Sie stattdessen `'%' + ?1 + '%'`.
  </Accordion>

  <Accordion title="Die Abfrage liefert alle Datensätze">
    Ein nicht gefülltes Argument wird als leerer Text übergeben. In einer
    LIKE-Bedingung entsteht daraus `'%%'`, das auf alle Datensätze passt.
    Beschreiben Sie das erwartete Format im Argument oder grenzen Sie die
    Abfrage im Statement zusätzlich ein.
  </Accordion>

  <Accordion title="Ein Datumsfilter greift nicht wie erwartet">
    Übergeben Sie Datumswerte im Format `yyyy-mm-dd`. Bei Spalten mit Uhrzeit
    grenzen Sie den Zeitraum mit `>=` und `<` ein, damit die Einträge des
    letzten Tages enthalten sind.
  </Accordion>

  <Accordion title="Die Antwort meldet, dass die Abfrage nicht ausgeführt werden konnte">
    Kann das Statement nicht ausgeführt werden, meldet der Konnektor dies als
    fehlgeschlagene Abfrage und gibt die Meldung der Datenbank weiter; sie wird
    zusätzlich im Systemprotokoll erfasst. Eine solche Meldung bedeutet nicht,
    dass keine passenden Daten vorhanden sind. Prüfen Sie das Statement direkt
    auf der Datenbank und ersetzen Sie die Platzhalter dort testweise durch
    feste Werte.
  </Accordion>
</AccordionGroup>