Im vorliegenden Blogbeitrag wird der in DeltaMaster verfügbare Bulk-Import vorgestellt. Beim Bulk-Import werden alle Zeilen einer CSV-Datei gesammelt importiert, was im Vergleich zum bisherigen zeilenweisen Import zu einer deutlichen Laufzeitreduzierung führt. Die geführte Benutzeroberfläche bietet dem Benutzer die Möglichkeit, eine Datei für den Import auszuwählen, zusätzliche Parameter für den Import bereitzustellen und fehlerhafte Datensätze zu identifizieren. Die Importdatei wird zunächst in eine Staging-Tabelle geladen und dort validiert. Fehlerhafte Datensätze werden ausgewiesen, korrekte Datensätze werden in die Zieltabelle überführt. Durch diese Flexibilität und Transparenz ergeben sich für Anwender deutliche Vorteile gegenüber der Ausführung eines Datenimportpakets über SSIS. Der Bulk-Import ist in das Erweiterungsmenü von DeltaMaster (Custom App) integriert und ist seit Version 6.2.7 im Web-Client und seit Version 6.3.1 im Windows-Client verfügbar. Zunächst wird die Konfiguration des Bulk-Imports erläutert, dann gehen wir auf die Durchführung eines definierten Bulk-Imports in DeltaMaster ein.
Konfiguration des Bulk-Imports
Berechtigung des DeltaMaster 6 Service
Da der Bulk-Import ausschließlich über den DeltaMaster 6 Service ausgeführt wird, müssen entsprechende Anwendungen im DeltaMaster Repository gespeichert werden. Das Benutzerkonto des DeltaMaster 6 Service muss auf der Datenbank, in welcher das Erweiterungsmenü implementiert ist, in der Datenbankrolle DeltaMaster_CustomApp hinzugefügt werden. Das Benutzerkonto des DeltaMaster 6 Service benötigt allerdings keine Berechtigung auf das Erweiterungsmenü (Bericht Rights in Analysesitzung DeltaMaster ETL).
Importverzeichnis des DeltaMaster 6 Service
Zudem wird für den DeltaMaster 6 Service ein Importverzeichnis in Datei DeltaMaster.Service.exe.config in Abschnitt <appSettings> definiert:
<add key="CustomAppImportDirectory" value="C:\_delme\CustomAppImport" />
Dieses Verzeichnis wird verwendet, um während des Bulk-Imports eine Kopie der CSV-Datei zu erzeugen, sowie deren Metainformationen im XML-Format zu speichern. Hierdurch können in den Schritten Parameter oder Validierung (Abschnitt 2) unterbrochene Importvorgänge (Status Processing) zu einem späteren Zeitpunkt fortgesetzt werden, ohne dass das Benutzerkonto des DeltaMaster 6 Service Zugriff auf die originäre Datei bzw. dessen Verzeichnis benötigt. Diese Dateien bleiben nach Abschluss des Importvorgangs zu Dokumentationszwecken im definierten Importverzeichnis bestehen.
Konfiguration Datenimport und Parameter in DeltaMaster ETL
Nach Implementierung der ETL-Solution DeltaMaster CustomApp kann in der Analysesitzung DeltaMaster ETL im Bericht Menu Entries ein Eintrag mit Subtype 9 – Datenimport (Bulk) definiert werden. Im Feld Criteria 1 kann der Namenskern (CoreTabName) für die Erstellung aller notwendigen relationalen Objekte definiert werden (Tabelle [dbo].T_SYS_CustomAppMenue]). Optional können für den Importprozess zusätzliche Parameter definiert werden, welche die Anwender während des Importvorgangs bereitstellen können. Beispielsweise könnten Anwender beim Import von Plandaten die gewünschte Planversion definieren, auf welche die Plandaten während des Importvorgangs geschrieben werden sollen. Die Einrichtung solcher Parameter erfolgt identisch zu anderen Menütypen des Erweiterungsmenüs im ETL-Bericht Procedure Parameters (Tabelle [dbo].T_SYS_CustomAppMenue_ProcParameters]). Diese Parameter werden von den Validate- und Commit-Prozeduren als Inputparameter verarbeitet.
Metaprozedur aus DeltaMaster ETL – Datenbankobjekte
Anschließend kann die von DeltaMaster ETL erstellte Metaprozedur [dbo].[P_BC_Generate_CustomApp2ImportObj] zur Erzeugung aller für den Bulk-Import notwendigen relationalen Datenbankobjekte verwendet werden. Die Prozedur erstellt automatisch folgende Datenbankobjekte:
Benutzerdefinierter Tabellendatentyp
- [dbo].[UDTT_<CoreTabName>_Stage]
- entspricht der Struktur der zu importierenden CSV-Dateien
- wird in der Stage-Prozedur verwendet, um die aus der CSV-Datei gelesenen Datensätze in die Stage-Tabelle zu überführen
Stage-Tabelle
- [dbo].[T_<CoreTabName>_Stage]
- Zieltabelle der Stage-Prozedur, in welche die Datensätze aus der CSV-Datei importiert werden
Stage-Prozedur
- [dbo].[P_<CoreTabName>_Stage]
- importiert unter Verwendung des benutzerdefinierten Tabellendatentyps als Inputparameter die Datensätze aus der CSV-Datei in die Stage-Tabelle
- wird als erste Prozedur beim Bulk-Import ausgeführt
Validate-Prozedur
- [dbo].[P_<CoreTabName>_Validate]
- dient zur projektspezifischen Validierung von Datensätzen
- kann um beliebige Datensatzprüfungen erweitert werden
- kennzeichnet fehlerhafte Datensätze in der Stage-Tabelle in Spalte [Valid] mit dem Wert 1
- schreibt fehlerhafte Datensätze in Tabelle [dbo].[T_SYSLOG_CustomApp_ImportInvalidRow]
- schreibt projektspezifische Fehlermeldungen in Tabelle [dbo].[T_SYSLOG_CustomApp_ImportInvalidRowError]
- aktualisiert die Anzahl an validen Datensätzen in Tabelle [dbo].[dbo.T_SYSLOG_CustomApp_ImportTransaction] in Spalte [RowsValid]
- verwendet für den Importprozess optional definierte Parameter als Inputparameter
- wird nach der Stage-Prozedur als zweite Prozedur beim Bulk-Import ausgeführt
Commit-Prozedur
- [dbo].[P_<CoreTabName>_Commit]
- schreibt valide Datensätze aus der Stage-Tabelle in die finale Zieltabelle des Bulk-Imports
- löscht (valide) Datensätze aus der Stage-Tabelle
- verwendet für den Importprozess optional definierte Parameter als Inputparameter
- wird nach der Validate-Prozedur als dritte Prozedur beim Bulk-Import ausgeführt
Die Datenbankrolle DeltaMaster_CustomApp muss zusätzlich auf die oben aufgeführten Datenbankobjekte berechtigt werden. Die automatisch erstellten Stage-, Validate- und Commit-Prozeduren stellen Vorlagen dar, welche manuell an den jeweiligen Anwendungsfall angepasst werden können und sollten. Um unterschiedliche Importvorgänge voneinander abgrenzen zu können, werden die Datensätze eines jeden Importvorgangs mit einer eindeutigen TransactionID gekennzeichnet.
Zusätzlich werden durch die Metaprozedur [dbo].[P_BC_Generate_CustomApp2ImportObj] die für den Bulk-Import notwendigen Spaltendefinitionen des benutzerdefinierten Tabellendatentyps in Tabelle [dbo].[T_SYS_CustomApp_ImportColumnDefinition] eingetragen. Die Eintragungen in dieser Tabelle müssen immer exakt zur Importdatei passen. Bei Änderungen, von z. B. Datentypen, müssen auch die Eintragungen in dieser Tabelle geändert werden.
Innerhalb einer Datenbank können auch mehrere Bulk-Importe mit verschiedenen Namenskernen konfiguriert werden.
Metaprozedur aus DeltaMaster ETL – Parameter
Nachfolgend erfolgt eine Definition der für die Metaprozedur [dbo].[P_BC_Generate_CustomApp2ImportObj] notwendigen Input- und Outputparameter.
Inputparameter
@TabName = obligatorisch; Name der Zieltabelle
@CoreTabName = nicht notwendig wenn in Tabelle [dbo].[T_SYS_CustomAppMenue] Spalte [Criteria1] gepflegt ist; sonst obligatorisch
@MenueID = obligatorisch; Tabelle [dbo].[T_SYS_CustomAppMenue] Spalte [Menue_ID]
@AvoidAlterProc = optional; per Default wird die automatische Neuerzeugung des benutzerdefinierten Tabellendatentyps und der Stage-/Validate-/Commit-Prozeduren nicht verhindert (= 0)
@AvoidAlterTable = optional; per Default wird die automatische Neuerzeugung der Stage-Tabelle nicht verhindert (= 0)
Outputparameter
@UDTTCodeDrop: Code zum Löschen des benutzerdefinierten Tabellendatentyps
@TableStageCodeDrop: Code zum Löschen der Stage-Tabelle
@ProcStageCodeDrop: Code zum Löschen der Stage-Prozedur
@ProcValidateCodeDrop: Code zum Löschen der Validate-Prozedur
@ProcCommitCodeDrop: Code zum Löschen der Commit-Prozedur
@UDTTCodeCreate: Code zum Erzeugen des benutzerdefinierten Tabellendatentyps
@TableStageCodeCreate: Code zum Erzeugen der Stage-Tabelle
@ProcStageCodeCreate: Code zum Erzeugen der Stage-Prozedur
@ProcValidateCodeCreate: Code zum Erzeugen der Validate-Prozedur
@ProcCommitCodeCreate: Code zum Erzeugen der Commit-Prozedur
@ProcFillImportColumnDefinitionCode: Code zum Befüllen von Tabelle [dbo].[T_SYS_CustomApp_ImportColumnDefinition]
Durchführen eines definierten Bulk-Imports in DeltaMaster
Nach Auswahl des Menüeintrags für den Bulk-Import im Erweiterungsmenü (Abbildung 1) gibt eine Übersicht Auskunft über bereits durchgeführte Importvorgänge (Abbildung 2).
Abbildung 1: Erweiterungsmenü
Abbildung 2: Übersicht
Neben der Import-ID, dem Dateinamen und einem Zeitstempel wird der Status der Importvorgänge (Processing, Failed, Succeeded), sowie die Anzahl der gelesenen, importierten und fehlerhaften Datensätze ausgewiesen. Status Processing kennzeichnet im Abschnitt Parameter oder Validierung unterbrochene Importvorgänge, welche fortgesetzt werden können.
Um einen neuen Importvorgang zu starten, wird zunächst über die Schaltfläche “Importdatei wählen” eine Importdatei aus dem Datei Explorer gewählt. Nach Auswahl erscheint eine Vorschau der entsprechenden Importdatei mit zusätzlicher Angabe von Name und Größe der Datei, sowie die Anzahl an gefunden Spalten und Zeilen. Im Beispiel werden Plandaten für den Umsatz pro Monat, Kunde und Produkt importiert (Abbildung 3).
Abbildung 3: Vorschau
Durch eine Klick auf Weiter können im folgenden Dialog optional die Parameter für den Importvorgang gesetzt werden. Die Parameter selbst wurden, wie in Abschnitt 1 beschrieben, im ETL-Bericht Procedure Parameters (Tabelle [dbo].[T_SYS_CustomAppMenue_ProcParameters]) definiert. Im Beispiel kann die Planversion gewählt werden, auf welche die importierten Datensätze geschrieben werden sollen (Abbildung 4).
Abbildung 4: Parameter
Im dritten Schritt des Importvorgangs wird die Stage-Prozedur ausgeführt und durch Ausführung der Validate-Prozedur eine Validierung der in der Stage-Tabelle enthaltenen Datensätze durchgeführt. Fehlerhafte Datensätze werden mit zuvor definierten Meldungstexten ausgewiesen (Abbildung 5). Die Definition eines fehlerhaften Datensatzes muss, wie bereits beschrieben, manuell in der Validate-Prozedur angelegt werden.
Abbildung 5: Validierung – fehlerhaft
Nach erfolgreicher Validierung wird die Commit-Prozedur ausgeführt, die die Daten an die definierte Zieltabelle überführt (Abbildung 6). Im Abschnitt Zusammenfassung wird letztlich noch die Anzahl an importierten Datensätzen ausgewiesen (Abbildung 7).
Abbildung 6: Validierung – erfolgreich
Abbildung 7: Zusammenfassung
In der manuellen Implementierung innerhalb der Commit-Prozedur können alle weiteren Schritte definiert werden, um die Importdatei in das gewünschte Format der Zieltabelle zu überführen. So könnte beispielweise eine Rückschreibeprozedur aufgerufen werden, sodass importierte Datensätze, welche auf aggregierter Ebene vorliegen, in die Rückschreibetabelle verteilt werden. Nach Ende des Importvorgangs ist dieser auch in eingangs erwähnter Übersicht ersichtlich und der nächste Import kann gestartet werden.
Referenzen
DeltaMaster Feature Notes 6.2.7 – Abschnitt 7
DeltaMaster Feature Notes 6.2.8 – Abschnitt 20
DeltaMaster Feature Notes 6.3.1 – Abschnitt 18
DeltaMaster ETL Handbuch – Abschnitt 129
