> For the complete documentation index, see [llms.txt](https://help.vario-software.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.vario-software.de/vario-cloud-handbuch/auswertungen/freie-vql.md).

# Freie VQL

Freie VQL-Selektionen in VARIO Cloud erstellen, konfigurieren und mit Variablen sowie Aggregationen erweitern.

Im Menüpunkt **Freie VQL** unter **Auswertungen** kannst Du freie VQL-Selektionen erstellen. Dabei kannst Du auf alle Datensätze in VARIO zugreifen, um Selektionen anhand von VQL zu konfigurieren.

{% hint style="warning" %}

## **VQL-Kenntnisse erforderlich**

Für die Erstellung von Selektionen im VQL-Modus sind gute Kenntnisse in der Abfragesprache VQL (VARIO Query Language) erforderlich.

in unserer [Developer Docs](https://developer.vario-software.de/) steht Dir eine ausführliche Dokumentation zu [**VQL**](https://developer.vario-software.de/documentation/fundamentals/vql) zur Verfügung. Dort sind die verschiedenen **VQL-Formulierungen** und ihre **Verwendung** aufgelistet und genau erklärt.
{% endhint %}

{% hint style="info" %}
Ohne eigene VQL-Kenntnisse hilft Dir ein KI-Assistent über den [MCP-Server](https://help.vario-software.de/vario-cloud-handbuch/kuenstliche-intelligenz/mcp-server.md): Du beschreibst, was Du sehen willst, und der Assistent sucht die passenden Felder heraus, schreibt die VQL und testet sie an Deinen Daten. Die fertige Abfrage übernimmst Du hier als Selektion.
{% endhint %}

In unserem **Deep Dive** zu VQL zeigen wir Dir wie Du VQLs nicht nur im Menüpunkt **Freie VQL** sondern in **jedem Bereich** erstellen kannst:

{% embed url="<https://www.youtube.com/watch?index=2&list=PL0EUYY7rOquvH67AHkOjoAGmcsgMt8ihx&v=TTXrpPZdisk>" %}

## VQL-Selektion erstellen

Beim ersten Öffnen des Menüpunkts **Freie VQL** wird keine vordefinierte Selektion angezeigt. Um eine **neue Selektion** zu erstellen, gehe wie folgt vor:

{% stepper %}
{% step %}

#### C-Unit-Einstellungen öffnen

Klicke **links** im **Spaltenkopf** auf das **Zahnrad**-Icon.

<figure><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2FhZPcQKpSnS50sqo3ZKTz%2Fimage.png?alt=media&#x26;token=fb26f82c-9954-4a34-a279-6a9f4d8cb814" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Selektion definieren

Trage im Feld **„Bezeichnung“** eine Bezeichnung für die Selektion ein.

<figure><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2Fe8be5g9YRNF0PjxeAhRu%2Fimage.png?alt=media&#x26;token=a0ae4b8d-b3a9-4a8f-a54c-53e1b5038774" alt="" width="563"><figcaption></figcaption></figure>

Der Modus **VQL** ist bereits vorausgewählt und kann nicht geändert werden. Im Feld **„Anzahl der Datensätze“** kannst Du die **maximale Anzahl** an **Datensätze** eintragen, die selektiert werden sollen.

Nach dem Speichern kannst Du die Selektion über den Toggle **»Standard«** als **Standardselektion** festlegen. Sie wird dann beim **Öffnen des Menüpunkts** automatisch ausgewählt.

Genauere Informationen zu den Konfigurationsmöglichkeiten findest Du auf der Seite [**Selektionen konfigurieren**](https://help.vario-software.de/vario-cloud-handbuch/grundlagen-und-konzepte/konfigurierbare-tabellen-c-units/selektionen-konfigurieren.md).
{% endstep %}

{% step %}

#### VQL verfassen

Im Reiter **»VQL Query«** kannst Du die Selektion frei anhand von VQL konfigurieren. Die **einzelnen Icons** oberhalb des **Editors** helfen Dir dabei, die Selektion effizienter zu konfigurieren. Beispielsweise wird Dir eine Auflistung **möglicher Code-Ausschnitte** und **C-Units** angeboten. Genauere Informationen zu diesen findest Du im nächsten Abschnitt.

<figure><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2FpduCP8hQArVm2RK5Xmpf%2Fimage.png?alt=media&#x26;token=3de2d268-87a4-48d1-a1cd-0063e5ae8560" alt="" width="563"><figcaption></figcaption></figure>

**Autovervollständigung**

Für die **Autovervollständigung** kannst Du sowohl nach den **technischen Namen** der Tabellen und Felder als auch nach deren **Übersetzung** suchen. Wähle einen Vorschlag aus; der Editor fügt den technischen Tabellennamen oder Feldpfad in die VQL-Anweisung ein.

Technische Namen kannst Du auch in der jeweiligen Verwaltung nachschlagen: Zeigt das **Kontextmenü (Rechtsklick)** eines Eingabefelds einen **Feldnamen** an, kopierst Du ihn durch Anklicken. Bei einer Tabellenspalte kannst Du den Pfad im Kontextmenü der **Spaltenüberschrift** kopieren. Den passenden Feldpfad für die ausgewählte C-Unit findest Du anschließend über die Autovervollständigung im VQL-Editor.

<figure><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2F3FupnsdtEEd03U518tvf%2Fimage.png?alt=media&#x26;token=b48e05b2-7efd-48fd-9099-56d6e44b3b4c" alt="VQL Übersetzungen" width="563"><figcaption></figcaption></figure>

{% hint style="info" %}

## Autovervollständigung

Beim Schreiben des VQLs werden Dir automatisch passende **Tabellen- und Feldnamen** angezeigt. Du kannst auch **Strg+Leertaste** klicken, um die Auflistung anzuzeigen. Auf dem Mac verwendest Du dafür **⌘+I**.

* Mit dem **Tastatur-Icon** oberhalb des Editors schaltest Du die automatischen Vorschläge aus. Die Vorschläge erscheinen dann nur noch, wenn Du sie mit **Strg+Leertaste** (Mac: **⌘+I**) aufrufst. Ein erneuter Klick aktiviert die automatischen Vorschläge wieder.
* Bei den Vorschlägen für Felder werden zuerst die Felder der Tabelle selbst angeboten, danach Felder aus verknüpften Tabellen (Unterfelder).
* Die Auswahl an **Tabellen** werden Dir nach der Eingabe von **„FROM“** angezeigt mit der entsprechende Beschreibung in Klammern.
* **Feldnamen** werden nach mindestens einer Angabe einer Tabelle vorgeschlagen. Dabei stehen Dir die entsprechende Feldnamen der Tabelle zur Verfügung.
  * Werden **mehrere Tabellen** angegeben, wird die entsprechende Tabelle hinter dem Feldnamen angezeigt
    {% endhint %}

**Auflistung von Enum-Werte**

Sind für ein Feld systemabhängige Werte vorhanden, z. B. bei **Geschäftsbeziehungen** oder **Art der Geschäftsbeziehung**, erscheint nach der Angabe des Feldes unterhalb des Editors ein entsprechenden Hinweis.

<figure><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2FBtWR0mF7VU2gUHymL0uK%2Fimage.png?alt=media&#x26;token=95aefdab-ac2f-46c4-a5ec-2e34e7f6513f" alt=""><figcaption></figcaption></figure>

Mit einem Klick auf diesen werden die entsprechenden Werte als Enum-Werte unter dem Editor angezeigt. Mit einem Klick auf einen Werte wird dieser direkt eingefügt.

<figure><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2Fr3lP2xh4vEEQlBCuPbhZ%2Fimage.png?alt=media&#x26;token=e468ec61-9150-404c-913f-bd79bce55f69" alt="" width="370"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Variablen konfigurieren

Mit dem **Zauberstab** liest Du die Variablen aus der VQL-Anweisung ein. Wenn VARIO das zugehörige Vergleichsfeld erkennt, ordnet es auch den passenden **Datentyp** oder **Suchdialog** zu. So erhältst Du beispielsweise für ein Datumsfeld einen Datumspicker und für eine passende Datensatzreferenz eine Suchauswahl. Bereits zugeordnete Typen und Suchdialoge bleiben erhalten. Kontrolliere die Zuordnung nach der Analyse; bei komplexen Ausdrücken kann eine manuelle Auswahl nötig sein.

Über **»+«** ergänzt Du Variablen auch manuell. Der **Name** muss zur Variable in der VQL-Anweisung passen. Unter **„Typ“** wählst Du die Art der Eingabe. Ein **„Suchdialog“** lässt den Benutzer stattdessen einen vorhandenen Datensatz auswählen, etwa eine Adresse oder einen Artikel; für die Abfrage wird dessen **ID** übernommen.

**Typ und Suchdialog sind alternative Einstellungen.** Ist ein Suchdialog gewählt, ist „Typ“ gesperrt. Entferne den Suchdialog über das Kreuz, um einen Typ auszuwählen. Ist ein Datentyp gewählt, stelle den Typ zunächst auf **Text**, damit Du einen Suchdialog wählen kannst.

<figure><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2FK9Kf19EfZyINIYKDnZYf%2Fimage.png?alt=media&#x26;token=85b098ee-136c-4ecf-8f8b-cb01a75ab2f8" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Aggregationen hinzufügen

Im Reiter **»Aggregation«** kannst Du ebenfalls [**Aggregationen**](https://help.vario-software.de/vario-cloud-handbuch/grundlagen-und-konzepte/konfigurierbare-tabellen-c-units/selektionen-konfigurieren.md#reiter-aggregationen) anhand von VQL erstellen.

<figure><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2FN7tHl8fCGo7Vp0ssXS7N%2Fimage.png?alt=media&#x26;token=e8dc81a4-a3b4-40ab-9430-7e7ac597143f" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Selektion speichern

Klicke **unten rechts** auf eines der **Disketten**-Icons, um die Selektion zu speichern. Mit dem Button **»Speichern«** wird die Selektion zwischengespeichert. Mit dem Button **»Speichern und anwenden«** wird das Fenster nach dem Speichern direkt geschlossen.

<figure><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2FYTCnBeKoX1ptQRvOJ4RO%2Fimage.png?alt=media&#x26;token=cc06011e-e420-4cad-91bf-43f56a952b12" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

## Tools im VQL-Editor

Im **VQL-Editor** im Reiter **»VQL Query«** innerhalb der Selektionskonfiguration stehen Dir verschiedene Tools zur Verfügung, die Dir dabei helfen Selektion effizienter zu konfigurieren:

<table><thead><tr><th width="138">Tool</th><th>Beschreibung</th></tr></thead><tbody><tr><td><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2FUFJgU3xFWdLOwNqKO9UO%2Fimage.png?alt=media&#x26;token=06f257df-9863-42a5-89ac-55d64d5e685e" alt="Icon formatieren" data-size="line"></td><td><strong>Formatiert</strong> den Code entsprechend der verwendeten Objekte</td></tr><tr><td><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2FFUHionIJSaEuvFRN7mzg%2Fimage.png?alt=media&#x26;token=444ed8d4-69f1-40ca-af0e-69ddb9735abd" alt="Icon rückgängig" data-size="line"> / <img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2FAO8ghE2pbcylkhzfj9yQ%2Fimage.png?alt=media&#x26;token=e7c0d559-e5d4-41ac-9b14-3cf2177bcb20" alt="Icon wiederherstellen" data-size="line"></td><td>Änderung <strong>rückgängig</strong> machen oder <strong>wiederherstellen</strong> (Strg+Z / Strg+Y)</td></tr><tr><td><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2FF4HDXrGiQ5gyTRjg0YT2%2Fimage.png?alt=media&#x26;token=3ba1f33f-03fb-4b35-9d08-9ecac0232ee1" alt="Icon suchen" data-size="line"></td><td>Nach einem Wert im Skript <strong>suchen</strong> (Strg+F)</td></tr><tr><td><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2FSjYvqTaulz70xLbEMvNi%2Fimage.png?alt=media&#x26;token=7b3972fd-2bf5-451e-8955-73275c547c34" alt="Icon suchen und ersetzen" data-size="line"></td><td>Nach einem bestimmten Wert im Skript <strong>suchen</strong> und diesen <strong>ersetzen</strong> (Strg+H)</td></tr><tr><td><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2F0exaU9wqKnM4kyhUjfQY%2Fimage.png?alt=media&#x26;token=8165952d-a50b-465c-9b16-1e59bf6eb11c" alt="Icon Kommentar einfügen" data-size="original"></td><td><strong>Kommentar</strong> ins Skript einfügen (Strg+/)</td></tr><tr><td><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2FPZ5XnbRvdk4k7UAcwzQy%2Fimage.png?alt=media&#x26;token=7178bcfe-3f00-4408-b49b-3298dcffbef6" alt="" data-size="line"> / <img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2FiZnZKy7Hd8KLuoMjzZah%2Fimage.png?alt=media&#x26;token=867b4423-8988-4cc9-851f-9a51aa101ee7" alt="" data-size="line"></td><td>Alle Klammern <strong>ein- oder ausklappen</strong></td></tr><tr><td><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2FlGUOfBUuD39DdjJPmlQu%2Fimage.png?alt=media&#x26;token=65b70383-a31f-4ce3-bdef-26148d7433e2" alt="Icon Code-Snippets" data-size="line"></td><td>Auswahl der meistgenutzten <strong>Code-Ausschnitte</strong>, die beliebig für die Verfassung des Skripts beliebig eingesetzt werden können</td></tr><tr><td><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2F9NwBeIoJumD38znawQcl%2Fimage.png?alt=media&#x26;token=ac6976f6-0b4e-4c47-b67a-e09201c305c9" alt="Icon kopieren" data-size="original"></td><td>Gesamtes Skript <strong>kopieren</strong></td></tr><tr><td><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2FZWbZKbjxViU09Et7Efxo%2Fimage.png?alt=media&#x26;token=9e2c8702-3ee4-4dd7-810f-73d101cdd1dd" alt="Icon minimap" data-size="original"></td><td><strong>Minimap</strong> des Skripts in der oberen rechten Ecke des Skript-Editors ein- und ausblenden</td></tr><tr><td><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2Fy5IjU13NtaQnxw29VPSh%2Fimage.png?alt=media&#x26;token=4df027e3-271e-47d4-80c3-b47b5d6c827a" alt="Icon Zeilenumbruch" data-size="line"></td><td>Bestimme, ob am <strong>Ende der Zeile</strong> im Skript-Editor ein <strong>Zeilenumbruch</strong> erfolgen soll</td></tr><tr><td><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2FoOIAqg4h42H55LfeQR53%2Fimage.png?alt=media&#x26;token=7ba8716e-1515-4c98-8aab-8dfd57f7152a" alt="Icon Design ändern" data-size="original"></td><td><strong>Design</strong> des Skripteditors auswählen</td></tr><tr><td>Tastatur-Icon</td><td>Automatische <strong>Vorschläge</strong> aus- und einschalten. Ausgeschaltet erscheinen Vorschläge nur mit Strg+Leertaste (Mac: ⌘+I)</td></tr><tr><td><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2FiX43o0Gd6LQ5g5w0n1jU%2Fimage.png?alt=media&#x26;token=58f08d2d-d350-49e8-a8aa-a9418ddfeb6c" alt="Icon Vollbildmodus" data-size="original"></td><td>Skript-Editor im <strong>Vollbildmodus</strong> öffnen</td></tr></tbody></table>

## VQL-Selektionen verwenden

Über das Feld **„Selektion“** kannst Du eine der erstellten Selektionen auswählen. Ist eine Selektion als **Standard** festgelegt, wird diese beim Öffnen des Menüpunkts automatisch ausgewählt.

<figure><img src="https://534317722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fa7nDlxyw1xkeHi7FnWgm%2Fuploads%2FXkW7jYh89oKiKXhGkR1P%2Fimage.png?alt=media&#x26;token=6ce01629-59dd-4620-bdeb-2666de16abe7" alt="Selektion auswählen"><figcaption></figcaption></figure>

## Beispiel: Projektnummer zum Beleg anzeigen

Über **Freie VQL** kannst Du Verkaufsbelege mit den ihnen zugeordneten CRM-Projekten verbinden. Das Beispiel liefert **Beleg-ID**, **Belegnummer** und **Projektnummer** für eine eingegebene Belegnummer.

```sql
select id,
       number,
       project$.number
  from document.querySalesDocuments
  join (select document.id,
               crmProject.id
          from crm.document-refs) as docRef
    on (docRef$.document.id = id)
  join (select id,
               number
          from crm.projects) as project
    on (project$.id = docRef$.crmProject.id)
 where number = :documentNumber
   and project$.id notnull
```

1. Erstelle eine **VQL-Selektion** und füge die Anweisung im Reiter **»VQL Query«** ein.
2. Lies über den **Zauberstab** die Variable `documentNumber` ein und kontrolliere den zugeordneten Datentyp.
3. Benenne die Ergebnisspalten eindeutig, zum Beispiel **Beleg-ID**, **Belegnummer** und **Projektnummer**.
4. Speichere die Selektion und gib die gewünschte Belegnummer ein.

Die Bedingung `project$.id notnull` begrenzt das Ergebnis auf passende Projektverknüpfungen. Ist ein Beleg mit mehreren Projekten verknüpft, kann er mehrfach im Ergebnis erscheinen. Ohne passende Verknüpfung wird er mit diesem Filter nicht angezeigt.

Die Verbindung erfolgt über die **Beleg-ID** und die **Projekt-ID**; ausgegeben wird die lesbare Projektnummer. `crm.document-refs` enthält die zugeordneten CRM-Objekte in den Feldern `crmProject`, `crmTask` und `crmDeal`.

Für Einkaufsbelege ersetzt Du die Quelle `document.querySalesDocuments` durch `document.queryPurchaseDocuments`. Die Verbindung über die Beleg-ID und die Projekt-ID bleibt gleich.

## Eine VQL-Auswertung mit eigenem Report drucken

Du kannst mit einer gespeicherten Selektion einen eigenen Report verknüpfen und ihre Ergebnisse damit ausgeben. Richte die Verbindung im Reiter **»Ausgabe«** der Selektion ein. Die vollständigen Schritte findest Du unter **Selektionen konfigurieren →** [**Ausgabe**](https://help.vario-software.de/vario-cloud-handbuch/grundlagen-und-konzepte/konfigurierbare-tabellen-c-units/selektionen-konfigurieren.md#reiter-ausgabe). Die Ausgabe- und Reporteinstellungen beschreibt [Modul CUnit](https://help.vario-software.de/vario-cloud-handbuch/system/ausgabe/modul-cunit.md).


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.vario-software.de/vario-cloud-handbuch/auswertungen/freie-vql.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
