Attributprojektion

Projektion - Kurzfassung

Zweck: Liefert die Werte von allen Instanzen eines bestimmten Attributtyps für einen gegebenen oder explizit definierten Attributbesitzer (ohne expliziten Join).

images/download/attachments/162408869/image-2023-12-6_15-35-27-version-1-modificationdate-1701873327298-api-v2.png

Eine Attributprojektion durchsucht die Attribute des durch den Kontext oder einen explizit definierten Attributbesitzerpfad definierten Attributbesitzers nach Attributen eines per Parameter Attribut ausgewählten Attributtyps.

Abhängig von der optionalen Auswahl für das auszuwertende Feld erscheint im Rückgabewert der Attributprojektion entweder der komplette Attributwert oder der Wert im ausgewählten Feld.

Die Attributprojektion liefert die Attributwerte aller Instanzen des ausgewählten Attributtyps, sodass - im Unterschied zur Typisiertes-Attribut-Projektion - grundsätzlich von einem mehrwertigen Rückgabewert auszugehen ist.

Die Einsatzmöglichkeiten der Attributprojektion im Kontext unterschiedlicher Attributtypen verdeutlicht die folgende Fallunterscheidung:

Kardinalität
des Attribut-/Subtyps ↓

Attributtyp ist
nicht-typisiert

Attributtyp ist typisiert

konkreter
Subtyp

alle
Subtypen

"singulär" (≤1)

Standardzugriff:
Singuläres-Attribut-Projektion

(Attributprojektion anwendbar aber kein Mehrwert)


Standardzugriff:
Typisiertes-Attribut-Projektion

(Attributprojektion mangels Auswahl für den (Sub-)Typ nicht einsetzbar)

Attributprojektion wertet Instanzen für alle singulären und pluralen Subtypen aus und liefert als Rückgabewert eine "flache" Liste (abhängig von der Auswahl für Feld)

"plural" (≥1:)

Attributprojektion ist der Standardzugriff

  • Ein nicht-typisiertes Singuläres Attribut ist als Attribut auswählbar. Technisch bietet die Attributprojektion diese Möglichkeit. Die Singuläres-Attribut-Projektion liefert allerdings dasselbe Ergebnis.

  • Für ein nicht-typisiertes Plurales Attribut, z. B. die "Kommunikationsinformation" (AddressCommunicationInfo) für den Entitätstyp "Adresse" (Address), stellt eine Attributprojektion den Standardzugriff dar.

  • Bezieht sich die Attribut-Auswahl auf einen Attributtyp aus der Gruppe der Typisierten Attribute (z. B. "Textattribut" oder "Firmen- und Adressattribut"), liefert die Attributprojektion die Attributwerte aller singulären und pluralen Subtypen als "flache Liste".

    • Die Werte von Typisierten Attributen mit pluralem Subtyp erscheinen im Rückgabewert also nicht "gruppiert" bzw. "gebündelt" je Attributbesitzer und Subtyp, sondern als individuelle Werte (mit demselben Subtyp aber unterschiedlichem index-Wert.

HINWEIS◄ Die Attributprojektion impliziert auf Datenbankebene einen optionalen LEFT OUTER JOIN auf die Datenbanktabelle für die Implementierung des Parameter Attribut ausgewählten Attributtyps. Sofern eine Suche mehrere Instanzen der Attributprojektion für diesen Attributtyp verwendet, wird derselbe JOIN mehrfach genutzt und nicht etwa redundant ausgeführt. Falls allerdings eine Attributprojektion und eine sinngemäß gleichwertige Singuläres-Attribut-Projektion auf dasselbe Singuläre Attribut zugreifen, ergibt dies zwei redundante JOINs.

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 Name für das ausgewählte Feld verwendet.

Attributbesitzerpfad

Entität
(Projektion)

Ein Attributbesitzerpfad muss nur explizit durch die Konfiguration einer Projektion definiert werden, wenn die Entität im Kontext der Suche nicht der Besitzer der Attribute ist, die ausgewertet werden sollen.

Dies ist z. B. in den folgenden Fällen relevant:

  • Der Attributbesitzer ist eine per Datenobjekt Join in die Suche einbezogene Entität.

  • Der Attributbesitzer ist eine Position einer Entität im Kontext der Suche.

  • Beim Attributbesitzer handelt es sich um eine in die Daten der Entität im Kontext der Suche eingebettete Entität, z. B. die "Adresse" (address) eines Kontos (s. Benutzer, Firmen/Mandanten).

Attribut

Klasse
(Attributtyp)

Im Auswahlfeld/Combobox-Element für den Parameter Attribut muss eine Auswahl aus den per Dropdown angebotenen Optionen für den Attributtyp erfolgen. Hier stehen nur die Attributtypen zur Auswahl, die der Entitätstyp des anwendbaren Attributbesitzers per Implementierung unterstützt.

HINWEIS◄ Stehen für das Attribut keine Optionen zur Auswahl oder werden Optionen vermisst, dann wurde eventuell versäumt den Attributbesitzerpfad passend zu setzen (z. B. die "Adresse" eines Kontos, für das keine Attribute implementiert sind).

Feld

Feld
(des Attributwerts)

Das Auswahlfeld/Combobox-Element für das Feld erlaubt eine optionale Einfachauswahl für eines der Felder des per Attribut ausgewählten Attributtyps.

  • Ohne Auswahl für das Feld liefert die Attributprojektion den kompletten Attributwert (value).

Für Instanzen pluraler Attribute kann ein Zugriff auf das Indexfeld (index oder orderIndex) im Attributwert sinnvoll sein.

  • Ein Zugriff auf die Felder der übergeordneten Attribut-Entität (etwa die id), in der das value-Feld enthalten ist, besteht nicht.

Beispiele

Typischer Anwendungsfall: Plurales Attribut auswerten

Eine Tupel-Suche soll alle greifbaren Instanzen des Entitätstyps "Adressbucheintrag" (AdressBookEntry, s. Adressbucheinträge) auswerten, die per Feld "Adresse" (address) jeweils genau eine Adresse (s. Adressen) referenzieren, und dabei einen Überblick über die dort über den Attributtyp "Kommunikationsinformation" (CommunicationInfo) hinterlegten Daten verschaffen.

Konkret soll je Adressbucheintrag genau ein Tupel ausgegeben werden, das unter anderem eine Liste (bzw. Collection) aller Kommunikationsinformationen enthält.

Konfiguration:

Der Screenshot rechts zeigt die für die Tupel-Suche konfigurierten Projektionen:

  • Zunächst soll eine Feldprojektion die addressBookId benennen, um das Adressbuch zu identifizieren, das den "gefundenen" Adressbucheintrag enthält. Ohne Einschränkungen in der Bedingung berücksichtigt die Suche Einträge aller (greifbaren) Adressbücher.

  • Die zweite Feldprojektion identifiziert den Adressbucheintrag eindeutig anhand seiner "ID" (id).

  • Die dritte Feldprojektion gibt den "Matchcode" aus der Adresse des Eintrags (address.accMatchCode) wieder, der den verwertenden Systemen oder Benutzern eine Zuordnung der gefundenen Daten ermöglichen soll.

  • Die im Bild aufgeklappte Collection Projektion leistet die in der Anforderung beschriebene Auswertung der "Kommunikationsinformationen" unter dem (Alias-)Namen COMMUNICATION_INFOS. Als Feld der Collection ist eine Attributprojektion mit folgenden Parametern konfiguriert:

    • Der Attributbesitzerpfad verweist über eine Feldprojektion auf das address-Feld, über das der Adressbucheintrag auf genau eine Adresse verweist.

    • Als Attribut-Typ ist der plurale Attributtyp "Kommunikationsinformation" ausgewählt.

    • Da kein Feld ausgewählt ist, listet die Attributprojektion komplette "Kommunikationsinformation"-Attributwerte auf, sodass der Empfänger Zugriff auf alle Nutzlast-Felder dieses Attributtyps (Kommunikationstyp, Kontext, Wert, Index) erhält.

images/download/attachments/162408869/image-2023-12-7_11-16-23-version-1-modificationdate-1701944185185-api-v2.png

Laufzeitbeispiel:

<core:TupleSearchResult maxResults="100" count="33">
<columns>
<name>addressBookId</name>
<name>id</name>
<name>address.accMatchCode</name>
<name>COMMUNICATION_INFOS</name>
</columns>
<result>
...
<row>
<item xsi:type="xsd:long">1051</item>
<item xsi:type="xsd:long">953</item>
<item xsi:type="xsd:string">EDDH</item>
<item xsi:type="list">
<entry id="12956" ... orderIndex="0" communicationType="EMAIL" communicationContext="noreply" xsi:type="base:AddressCommunicationInfo">
<communicationValue>noreply@ema.il</communicationValue>
</entry>
<entry id="12955" ... orderIndex="1" communicationType="EMAIL" communicationContext="alternate" xsi:type="base:AddressCommunicationInfo">
<communicationValue>noreply2@doma.in</communicationValue>
</entry>
<entry id="12957" ... orderIndex="2" communicationType="PHONE" communicationContext="info" xsi:type="base:AddressCommunicationInfo">
<communicationValue>+49 (40) 50750</communicationValue>
</entry>
</item>
</row>
<row>
<item xsi:type="xsd:long">1051</item>
<item xsi:type="xsd:long">952</item>
<item xsi:type="xsd:string">EDDF</item>
<item xsi:type="list">
<entry id="12960" ... orderIndex="0" communicationType="PHONE" communicationContext="info" xsi:type="base:AddressCommunicationInfo">
<communicationValue>+49 (180) 6 3724636</communicationValue>
</entry>
</item>
</row>
<row>
<item xsi:type="xsd:long">1051</item>
<item xsi:type="xsd:long">951</item>
<item xsi:type="xsd:string">EDDL</item>
<item xsi:type="list">
<entry id="12961" ... orderIndex="0" communicationType="PHONE" communicationContext="info" xsi:type="base:AddressCommunicationInfo">
<communicationValue>+49 (211) 4210</communicationValue>
</entry>
</item>
</row>
...
</result>
</core:TupleSearchResult>
  • Jedes row -Element ("Tupel") beinhaltet als viertes item eine Liste der dem Adressbucheintrag zugeordneten "Kommunikationsformationen".

  • Die Beispieldaten zeigen Attributwerte mit unterschiedlichem Kommunikationstyp (EMAIL, PHONE) und "Kontext" (info, alternate, noreply) zur Klassifikation der als "Wert" (communicationValue) angegebenen konkreten Informationen.

Variante: Um die "Kommunikationsinformationen" in einer CSV-Suche als möglichst direkt lesbaren Text zu "servieren", empfiehlt sich eine etwas andere Aufbereitung der Rückgabewerte aus der Attributprojektion:

  • Anstelle einer "Listenspalte" (Collection) in einem Tupel soll eine ggf. mehrzeilige Ausgabe der "Kommunikationsinformationen" mit Wiederholung der Kopfdaten des Adressbucheintrags erfolgen.

  • Die Nutzlast-Felder aus dem Attribut sollen auf einzelne Spalten verteilt werden.

Konfiguration:

Anstelle der Collection Projektion im vorherigen Beispiel kommen die im Screenshot (rechts) gezeigten vier Instanzen der Attributprojektion mit einer bis auf das Feld einheitlichen Parametrierung zum Einsatz:

  • Wie die aufgeklappte Instanz zeigt, bleiben der Attributbesitzerpfad und die Auswahl für Attribut (Attributtyp) unverändert.

  • Für jede Instanz wird ein anderes Feld aus der "Nutzlast" des Attributwerts ausgewählt:

    • orderIndex

    • communicationType

    • communicationContext

    • communicationValue

ANMERKUNG◄ Diese Projektionen können durch "Kopieren, Einfügen und Anpassen" recht schnell zusammengestellt werden. Wie oben abstrakt beschrieben führt dies nicht dazu, dass hier intern vier individuelle JOINS generiert und zur Laufzeit abgearbeitet werden. Vielmehr beziehen sich effektiv alle Instanzen der Attributprojektion automatisch auf denselben Join.

HINWEIS◄ Da kein Name angegeben ist, erscheinen die internen Feldnamen als Beschriftung je Ausgabespalte.

images/download/attachments/162408869/image-2023-12-7_13-22-28-version-1-modificationdate-1701951750680-api-v2.png

Laufzeitbeispiel:

Für denselben Ausschnitt der Beispieldaten liefert die CSV-Suche den unten dargestellten Text, in dem Adressbucheinträge (s. zweite Spalte, id) mit mehreren "Kommunikationsinformationen" mehrere Zeilen belegen.

addressBookId,id,address.accMatchCode,orderIndex,communicationType,communicationContext,communicationValue
...
1051,953,EDDH,0,EMAIL,noreply,noreply@ema.il
1051,953,EDDH,2,PHONE,info,+49 (40) 50750
1051,953,EDDH,1,EMAIL,alternate,noreply2@doma.in
1051,952,EDDF,0,PHONE,info,+49 (180) 6 3724636
1051,951,EDDL,0,PHONE,info,+49 (211) 4210
...

Besonderer Anwendungsfall: Typisierte Attribute eines Typs auswerten

Eine CSV-Suche soll den "Fortschritt" im Lebenszyklus von Sendungen durch eine Listenspalte visualisieren, die für jedes verwendete Datumsattribut dessen Datumstyp benennt.

Konfiguration:

Der Screenshot rechts zeigt die Konfiguration für Projektionen der CSV-Suche:

  • Die Feldprojektion bildet das Feld "ID" (id) der Sendung ab, um diese zu identifizieren.

  • Die Collection Projektion (Name "DATE_ATTRIBUTES") verwendet als Feld der Collection eine Attributprojektion mit folgender Parametrierung:

    • Ein Attributbesitzerpfad ist nicht erforderlich, da die Sendung im Kontext unmittelbarer Attributbesitzer ist.

    • Als Attribut ist der Attributtyp "Datumsattribut" ausgewählt.

    • In der Collection soll das Feld dateType erscheinen, das den Subtyp des Datumsattributs über einen Wert aus der Dynamischen Aufzählung Datumstyp benennt.

      ANMERKUNG◄ Im CSV erscheint für den Datumstyp der interne Name des Aufzählungswerts und nicht etwa eine zugehörige Lokalisierung.

images/download/attachments/162408869/image-2023-12-8_8-9-55-version-1-modificationdate-1702019396608-api-v2.png

Laufzeitbeispiel:

id,DATE_ATTRIBUTES
...
4802,[DISPATCH_DATE_PLANNED]
4701,[ARRIVAL_PLANNED]
4651,[ARRIVAL_PLANNED]
4402,[]
4401,[]
4301,[ARRIVAL_PLANNED]
4253,[ARRIVAL_PLANNED]
4203,[]
4202,[ARRIVAL_PLANNED]
4201,[]
4151,[]
4101,&quot;[VESSEL_DEPART, WAYPOINT_ARRIVAL_DATE, WAYPOINT_ARRIVAL_DATE, VESSEL_ARRIVAL, LOADING_DATE]&quot;
4051,&quot;[TEST_DATETYPE, ARRIVAL_PLANNED]&quot;
4006,[]
...

ANMERKUNGEN

  • Das Beispiel zeigt Sendungen mit Datumsattributen mit Subtypen, die singulär oder plural sein können.

  • Nur der Datumstyp WAYPOINT_ARRIVAL_DATE ist dabei eindeutig als plural zu erkennen, da er mehrfach in derselben Collection für eine Sendung erscheint.

  • Ob ein Datumstyp, der nur einfach erscheint, per Definition singulär ist, würde auch aus dem vollständigen Attributwert nicht hervorgehen. Auch für singuläre Attributwerte erscheint ein index-Feld mit dem Wert 0.

WICHTIG◄ Die hier demonstrierte Vorgehensweise zur Auswertung von Attribut-Subtypen ist nur wirklich praxistauglich, wenn folgende Einschränkungen unproblematisch sind:

  1. Die Einzelwerte in einer Collection Projektion können nicht sortiert werden. Die Datumstyp-Werte erscheinen auch nicht etwa in einer logischen bzw. chronologischen Reihenfolge (s. LOADING_DATE).

  2. Die Attributprojektion berücksichtigt alle Attribute des ausgewählten Typs, also auch solche, die aktuell nicht "gefüllt" sind.
    Exkurs;
    Wenn ein Attributwert gelöscht wird, bleibt in der Regel nicht nur die zugehörige Attribut-Entität in den Daten der Attributbesitzer-Entität erhalten, sondern auch der Attributwert selbst, da dieser weiter auf den Subtyp verweist:

          <shp:ShipmentDate id="1852" ... >
    <value dateType="TEST_DATETYPE"/>
    </shp:ShipmentDate>


    Die oben gezeigte Suche liefert in diesem Fall also den Datumstyp, obwohl der Attributwert keine weitere "Nutzlast" beinhaltet. Die Attributprojektion sieht auch keine Möglichkeit für eine entsprechende Einschränkung vor. Nur ein Attribut Join könnte das leisten.