SQL-gefiltertes Referenzfeld (searchReferenceSql)

Das Feld searchReferenceSql ist ein Formularfeldtyp für handgebaute Formulare, mit dem eine Referenz auf ein Datenobjekt ausgewählt wird – wie beim klassischen Referenzfeld, jedoch wird die Auswahlliste über eine frei definierte SQL-Abfrage vorgefiltert.

So lässt sich die Auswahl gezielt auf fachlich relevante Datensätze einschränken – etwa nur Projekte mit Status „offen" – statt eine vollständige, ungefilterte Liste anzubieten.

Wozu dient das Feld?

Das automatische Referenzfeld eines Datenschemas kann nur nach dem Dokumentnamen (document_name) suchen und nicht nach Fachattributen filtern. Genau diese Lücke schließt searchReferenceSql: Über eine eigene SQL-Abfrage wird festgelegt, welche Datensätze überhaupt zur Auswahl stehen und gegen welchen Text gesucht wird.

Das Feld ist für handgebaute Custom-Formulare gedacht, also für Formulare, deren Aufbau direkt als Formular-JSON definiert wird.

Anwendungsfall

Ein typisches Szenario ist die Zeit-Nacherfassung: Ein Dashboard-Button startet einen Prozess mit einem handgebauten Formular, in dem Zeit auf eine Referenz – zum Beispiel ein Projekt – gebucht wird. Mit searchReferenceSql lässt sich die Projektliste vorab auf offene Projekte einschränken, sodass keine bereits abgeschlossenen Projekte auswählbar sind.

Spalten-Vertrag der SQL-Abfrage

Die SQL-Abfrage muss exakt die folgenden vier Spalten zurückgeben. Fehlt eine Spalte oder weicht der Name ab, funktioniert das Feld nicht korrekt.

Spalte	Beschreibung
`id`	Eindeutige Kennung des Datenobjekts. Wird zum Nachladen des vollständigen Objekts (Hydration) verwendet.
`data_schema_id`	Kennung des Datenschemas. Wird für Vorschau und Konsistenz mitgeführt.
`document_name`	Anzeigetext der Auswahloption.
`search_string`	Die Spalte, gegen die gefiltert und gesucht wird. Ihr Inhalt wird im SQL frei bestimmt (z. B. Dokumentname plus Kundenname, kleingeschrieben).

Vier Vertragsspalten sind Pflicht

Die Abfrage muss exakt id, data_schema_id, document_name und search_string liefern. Eine clevere Vorfilterung im WHERE hält die Liste klein und die Suche schnell.

Konfiguration über `props`

Die Konfiguration erfolgt inline im Formular-JSON über die Feld-props:

Eigenschaft	Standard	Beschreibung
`sql`	– (Pflicht)	Basisabfrage mit Fachfilter, liefert den Spalten-Vertrag.
`initialLimit`	`1000`	Anzahl der initial geladenen Zeilen – zugleich die Schwelle zwischen „vollständig" und „teilweise" geladen.
`searchLimit`	`50`	Obergrenze pro serverseitiger Nachladesuche.
`loadOn`	`'render'`	`'render'` = beim Laden des Feldes laden, `'focus'` = erst beim Fokussieren laden (spart Abfragen).
`hydrateFullObject`	`true`	Lädt bei Auswahl das vollständige Datenobjekt – wie beim klassischen Referenzfeld.
`dataSchemaId`	– (optional)	Ist die Angabe gesetzt, erscheint ein „Neu"-Button zum Anlegen eines neuen Datenobjekts dieses Schemas. Ohne Angabe bleibt der „Neu"-Button ausgeblendet.

Platzhalter im SQL

In der SQL-Abfrage werden folgende Platzhalter automatisch aufgelöst und ermöglichen nutzerspezifische Filter:

@currentUserSub – die eindeutige Kennung des angemeldeten Nutzers.
@currentUserEmail – die E-Mail-Adresse des angemeldeten Nutzers.

Vollständiges Beispiel

Das folgende Formularfeld bietet eine Auswahl offener Projekte und blendet einen „Neu"-Button für das Schema projekte ein:

{
  "key": "projekt",
  "type": "searchReferenceSql",
  "props": {
    "label": "Projekt",
    "sql": "SELECT id, 'projekte' AS data_schema_id, document_name, lower(document_name) AS search_string FROM projekte WHERE status = 'offen'",
    "initialLimit": 1000,
    "searchLimit": 50,
    "loadOn": "render",
    "hydrateFullObject": true,
    "dataSchemaId": "projekte"
  }
}

Such- und Ladeverhalten

Das Feld arbeitet zweistufig und bleibt auch bei Zehntausenden Datensätzen schnell:

Vollständig geladen (Trefferzahl kleiner als initialLimit): Tippen filtert die Liste sofort clientseitig. Ein Nachladen ist nicht nötig.
Teilweise geladen (Trefferzahl gleich initialLimit): Tippen filtert ebenfalls zuerst im bereits geladenen Puffer. Zusätzlich erscheint ein Button „Nachladen", der serverseitig mit dem aktuellen Suchbegriff weitersucht (LIKE-Suche bis zur searchLimit-Grenze) und neue Ergebnisse in die Liste mischt.

Wildcards (% und _) im Suchbegriff sind erlaubt.

Bedien-Buttons am Feld

Neu: Legt direkt ein neues Datenobjekt des Schemas an. Nur sichtbar, wenn dataSchemaId gesetzt ist.
Im Data-Lake öffnen: Öffnet die gewählte Referenz in einem neuen Tab.
Auswahl entfernen: Setzt das Feld zurück.

Tipps

Vorfilterung im WHERE: Je enger die Basisabfrage gefasst ist, desto kleiner bleibt die Liste und desto schneller die Suche.
Suchspalte gezielt aufbauen: In search_string können mehrere Werte zusammengeführt werden (z. B. Dokumentname und Kundenname), damit auch danach gesucht werden kann.
loadOn: 'focus' bei vielen Feldern: Wenn ein Formular mehrere solcher Felder enthält, spart das verzögerte Laden beim Fokussieren unnötige Abfragen.