Feldprojektion

Projektion - Kurzfassung

Zweck: Gibt den Wert eines Felds einer Entität aus dem Kontext der Abfrage zurück.

images/download/attachments/155419139/image-2023-10-24_13-40-32-version-1-modificationdate-1698147644021-api-v2.png

Eine Feldprojektion gibt den Wert eines Felds einer Entität zurück, sofern der Zugriff auf das ausgewählte Feld technisch darstellbar ist.

Die Feldprojektion ist die wichtigste Projektion, um Werte für Ausgabespalten, Einschränkungen sowie für die Gruppierung und Sortierung von Suchergebnissen aus der Datenbank zu beziehen.

  • Im Unterschied zur Collection Projektion liefert die Feldprojektion in der Regel Einzelwerte. Sofern ein Feld ausgewählt wird, das die n-Seite in einer (1:n)-Relation betrifft, generiert der Zugriff per Feldprojektion (mindestens intern) eine Zeile für jeden Wert der n-Seite.

  • Abhängig vom Datentyp des Felds, der in der Typdefinition für die betreffende Entität festgelegt ist, kann es sich bei einem Feldwert um einen simplen Wert oder ein mehr oder weniger komplexes Datenobjekt handeln.


WICHTIG◄ Um bequem auf die Felder von Attributen einer Entität zuzugreifen, bietet sich im Allgemeinen die Verwendung eine der folgenden spezialisierten Projektionen an:

Beide Projektionen bieten einen Parameter Feld an, über den optional auf ein bestimmtes Feld im Wert des Attributs zugegriffen werden kann.


HINWEIS◄ Wenn die Feldprojektion eine Ausgabespalte (in einer CSV- oder Tupel-Suche) definiert, unterliegt der Feldwert ggf. einer gewissen "Aufbereitung"
Beispiele:

  • Ein Dynamischer Aufzählungswert wird in der Datenbank im Allgemeinen als Long-Wert (ordinal) persistiert, während in einer CSV-Ausgabespalte sein interner "Name" (name) erscheint und in einer Tupel-Suche ein DynamicEnumValue-Objekt (mit dem XML-Attribut name).

  • Wenn eine Feldprojektion in einer Suche für Benutzer oder Firmen das Feld address "liest", liefert die Ausgabe in einer CSV-Suche das String-Abbild der Adresse-Entität (z. B. 21052:de.lobster.scm.base.address.Address@1c6bbbc7), also wenig "benutzerfreundliche" Information abgesehen von der vorangestellten ID (hier: 21052). Dagegen liefert eine Tupel-Suche die "Adresse"-Entität komplett als komplexen Wert, sodass aus dem Suchergebnis im Nachgang sämtliche Details "gewonnen" werden können.

Konfiguration

Parameter

Typ

Beschreibung

Name

String

Der optionale Parameter Name kann verwendet werden, um der Projektion einen (Alias-)Namen zuzuweisen.

  • Wenn kein Name angegeben ist, wird als Spaltenname (sofern relevant) der "Pfad" zum gelesenen Feld zugewiesen. Der Pfad beginnt ggf. mit einem innerhalb der Suche definierten JOIN-Alias auf den ein oder mehrere interne Feldnamen folgen. Als Trennzeichen dient der Punkt (.).
    Beispiele: address.name1 ("Name" aus der Adresse einer Benutzer-Entität), owner.address.countryCode ("Land" in der Adresse eines über einen Datenobjekt Join mit dem Alias owner einbezogenen Firmenkontos).

Feld

String
(Auswahlfeld)

images/download/attachments/155419139/image-2023-10-24_17-17-21-version-1-modificationdate-1698160653149-api-v2.png

Rein technisch handelt es sich beim Parameter Feld um einen String, der im Kontext der Suche als Pfad zu einem Feld einer im Kontext der Abfrage enthaltenen Entitätstypen interpretierbar sein muss, sonst tritt beim Ausführen der Suche ein Fehler auf.

In der Benutzeroberfläche erscheint für das Feld ein Auswahlfeld/Combobox-Element mit Suchfunktion, das per Dropdown alle möglichen im Kontext verfügbaren Pfade zu Feldern zur Auswahl anbietet. Soweit verfügbar werden neben den für den Pfad ausschlaggebenden internen Namen auch Lokalisierungstexte verwendet.

HINWEISE

  • Angebotene Pfade sind nicht in jedem Fall geeignet, um z. B. eine Feldprojektion für eine unmittelbare Ausgabespalte zu definieren (z. B. Feld attributes im Kontext eines Entitätstyps, der Attribute besitzen kann).

  • Ein Stern (*) nach dem lokalisierten Feldnamen (im Screenshot: Benuztername*) weist daraufhin, dass für das Feld datenbankseitig ein Index geführt wird. Indizierte Felder sollten mit Blick auf die Performanz einer Suche bevorzugt herangezogen werden, um Einschränkungen (für Such- oder Join-Kriterien) zu formulieren.

  • Abhängig vom Kontext erscheinen ggf. Auswahloptionen mit dem Alias-Namen _parentQuery, der sich - z. B. im Kontext einer Sub-Suche generisch auf die übergeordnete Suche bezieht und den Zugriff auf deren Felder ermöglicht.

  • Wie im Bild zu sehen akzeptiert das Auswahlfeld/Combobox-Element per Klick auf das [+]-Symbol ggf. die Eingabe von Textwerten für Pfade, die nicht im Dropdown enthalten sind. Fast immer führt dies allerdings zu Fehlern, wenn die Suche ausgeführt wird.


Beispiele

Einfaches Beispiel: Feld Einschränkung für einer Suche

Die Bedingung einer Suche für einen beliebigen Entitätstyp soll diejenigen Instanzen für die Entität herausfiltern, die im Feld "Änderungsdatum" (lastModified) denselben Zeitstempel aufweisen wie im "Erstelldatum" (created)

Die Suche listet also sämtliche Entitäten des gewählten Typs auf, die bisher genau einmal gespeichert wurden - beim "Erstellen" (s. Allgemein (Ereignisse) und deren Datenstand sich seitdem nicht mehr geändert hat.

Konfiguration:

Der Screenshot zeigt die Konfiguration für die Bedingung in einer Suche:

  • Da zwei Felder der gesuchten Entität miteinander verglichen werden sollen, verwendet die Feld Einschränkung zwei Instanzen der Feldprojektion:

    • Als Prüfwert (links) wird eine Feldprojektion für das Feld "Änderungsdatum" (lastModified) herangezogen.

    • Als Vergleichswert (rechts) wird eine Feldprojektion für das Feld "Erstelldatum" (created) herangezogen.

Der Name ist hier unerheblich, da er im Suchergebnis nicht erscheinen wird.

HINWEIS◄ Wie im Screenshot zu sehen, erscheint der Feldname in beiden Fällen mit einem Stern (*). Es handelt sich also um indizierte Felder.

images/download/attachments/155419139/image-2023-10-25_11-19-3-version-1-modificationdate-1698225542767-api-v2.png

WICHTIG◄ Beim Konfigurieren der Feld Einschränkung ist zu beachten, dass das Kontextmenü für den Prüfwert (links) ausschließlich Projektionen zur Auswahl anbietet. Dagegen können für den Vergleichswert wahlweise Projektionen oder Wertauflöser (für konstante Werte) eingesetzt werden. Die Projektionen erscheinen im Kontextmenü für den Vergleichswert (rechts) in einer eigenen Kategorie "Suche".

Einfaches Beispiel: "Ausgabespalten" für Felder in einer Tupel- oder CSV-Suche

Im Kontext einer Tupel- oder CSV-Suche müssen alle "Ausgabespalten" ausdrücklich durch Projektionen definiert sein.

Im Ergebnis einer Suche für Benutzer sollen der "Benutzername" (username) und die zugeordnete(n) Rolle(n) erscheinen.

Konfiguration:

Im Kontext einer CSV-Suche für den Entitätstyp "Benutzer" (s. Benutzer) definieren wir zwei Ausgabenspalten:

  • Die erste Spalte verweist per Feldprojektion auf das Feld "Benutzername" (username), das einen Textwert (String) enthält, und weist als Name USER zu.

  • Die zweite Spalte verweist per Feldprojektion auf das Feld "Rollen", das die dem Benutzerkonto zugeordneten Rollen als Liste von Long-Werten enthält, und weist als Name ROLE zu.

ANMERKUNG◄ Wie das folgende Laufzeitbeispiel zeigt, wäre die Beschriftung "ROLES" irreführend.

images/download/attachments/155419139/image-2023-10-25_12-32-42-version-1-modificationdate-1698229962496-api-v2.png

Laufzeitbeispiel:

Wie das Abfrageergebnis (rechts) zeigt, erscheinen mehrere Zeilen für denselben USER, wenn diesem mehr als eine Rolle zur Auswahl steht.

Die Feldprojektion auf das "mehrwertige" roles-Feld führt hier also zur Multiplikation der Benutzerdaten (hier: USER) je Rolle. Die ROLE-Spalte gibt immer nur genau eine ID einer Rolle aus.

USER,ROLE
ABC,1001
ABC,501
DEF,1201
DEF,501
DEF,1351
DEF,1001
GHI,1352
GHI,1
XYZ,1352

ANMERKUNG◄ Um mehrere Rollen innerhalb derselben USER-Zeile auszugeben, könnte man eine Collection Projektion verwenden.

Komplexeres Beispiel: "Rollennamen" anstelle der ID per JOIN beschaffen

Ausgehend vom vorherigen Beispiel soll die Rolle nicht mehr anhand der ID sondern über den Rollennamen (roleName) identifiziert werden.

Da im Benutzerkonto nur die Long-Referenz enthalten ist, müssen wir jede referenzierte Rolle-Entität in den Kontext der CSV-Suche ausdrücklich hinzuziehen, um auf den Rollennamen zugreifen zu können.

Dies können wir z. B. über einen Datenobjekt Join bewerkstelligen.

Konfiguration:

Der CSV-Suche aus der vorherigen Beispiel fügen wir einen Datenobjekt Join hinzu, der wie rechts abgebildet parametriert wird:

  • Das Datenobjekt für den Join ist der Entitätstyp "Rolle" (Role).

  • Als Join Alias wählen wir willkürlich das Kürzel r (für Role).

  • Als Join Typ wählen wir "Inner", da wir davon ausgehen können, dass zu jeder Rollen-ID eine "Rolle" gefunden wird.

  • Die Join Bedingung verwendet eine Feld Einschränkung, um die Beziehung zwischen dem gesuchten "Benutzer"-Entitätstyp und dem per Join hinzugezogenen Entitätstyp "Rolle" (r) zu beschreiben:

    • Als Prüfwert (links) ziehen wir über eine Feldprojektion das Feld "Rollen" (roles) im Benutzerkonto heran.

    • Als Vergleichswert (rechts) ziehen wir über eine weitere Feldprojektion das Feld "ID" (id) innerhalb der Rolle (r) heran. Der Pfad "r.id" wird automatisch im Dropdown bereitgestellt und erscheint dabei sogar teilweise lokalisiert als "r.ID".

HINWEIS◄ Da sich die Join Bedingung auf ein "mehrwertiges" Feld der Entität bezieht, wird die Bedingung gegen alle im Feld "Rollen" aufgeführten Einzelwerte geprüft. Der Join ordnet jedem roles-Eintrag die referenzierte Rolle (r) zu.

images/download/attachments/155419139/image-2023-10-25_15-8-50-version-1-modificationdate-1698239330831-api-v2.png


Sobald der Datenobjekt Join konfiguriert ist, erweitert sich das Angebot für Pfade im Kontext unserer Projektionen:

  • Die Feldprojektion USER behalten wir unverändert bei.

  • In der Feldprojektion ROLE stellen wir jetzt das Feld um, vom Feld "Rollen" (roles) um auf den neuerdings verfügbaren Pfad r.roleName, der im Dropdown als "r.Rollenname" (teil-lokalisiert) angeboten wird.

images/download/attachments/155419139/image-2023-10-25_15-28-26-version-1-modificationdate-1698240507393-api-v2.png

Laufzeitbeispiel:

USER,ROLE
ABC,Querificus
ABC,Super user limited
DEF,Super user limited
DEF,Querificus
DEF,Upload
DEF,Administrator
GHI,Tester
GHI,Super User
XYZ,Tester

Die bestehenden Projektionen verwenden wir jetzt noch als Grundlage für eine Sortierung der Ergebnisliste

Eine Feldprojektion für eine Projektion kann dazu über das Kontextmenü (s. Menü-Symbol links oben innerhalb der Feldprojektion) in die Zwischenablage kopiert und im Kontext der Sortierung wiederum über das Kontextmenü als per images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/add.svg -Symbol hinzugefügte Projektion eingefügt werden.

Wie im Screenshot zu sehen, soll unsere Sortierung zunächst nach dem Rollennamen und danach nach dem Benutzernamen erfolgen.

HINWEIS◄ Ein Bezug zu einer bereits definierten "Ausgabespalte" über den Spalten-Alias (hier: ROLE, USER) kann ausgehend von der Sortierung (und auch Gruppierung) nicht hergestellt werden. Dieselbe Projektion muss bei Bedarf (wie in unserem Beispiel) also mehrfach angelegt werden. Der verwendete Name ist dabei unerheblich, wurde hier aber beim Kopieren "mitgenommen".

images/download/attachments/155419139/image-2023-10-25_15-46-17-version-1-modificationdate-1698241578144-api-v2.png

Laufzeitbeispiel:

USER,ROLE
DEF,Administrator
ABC,Querificus
DEF,Querificus
GHI,Super User
ABC,Super user limited
DEF,Super user limited
GHI,Tester
XYZ,Tester
DEF,Upload