Seite 3: Dynamische Diagramme mit Mermaid erstellen

Durch das JavaScript-basierte Tool Mermaid lassen sich in Polyglot Notebooks Abbildungen generieren. Allerdings unterstützt Mermaid keine Variablen. Daher wird an dieser Stelle der Mermaid-Code mithilfe von C# dynamisch erzeugt, basierend auf der Ausgabe der SQL-Query. Der erzeugte Mermaid-Code kann einen Befehl im Mermaid-Subkernel aufrufen, der dann die Grafik generiert.

Die benötigten Variablen wurden zu diesem Zeitpunkt bereits aus dem SQL-Subkernel geteilt. Mit der Produkt-ID kann man in einem String die Basis für das Tortendiagramm mitsamt Überschrift erzeugen (siehe Listing 4).

An diese Basis werden nun in einer Schleife nacheinander alle Einträge aus dem Ergebnis der Query angehängt, um im Anschluss mit dem Kernel.Root.SendAsync()-Befehl asynchron Code auf dem Mermaid-Subkernel auszuführen.

#!share --from sql-DemoKernel QueryResult
#!share --from sql-DemoKernel productId

var mermaidCodeStringBuilder = new StringBuilder();
mermaidCodeStringBuilder.AppendLine($"""
pie showData
    title Customers who bought product '{productId}'

"""
);

foreach (var element in QueryResult[0].Data){
    var customerId = element.FirstOrDefault(x => x.Key == "CustomerID").Value ?? "Unknown";
    var orderQty = element.FirstOrDefault(x => x.Key == "OrderQty").Value ?? "0";
    mermaidCodeStringBuilder.AppendLine($"\"{customerId}\": {orderQty}");
}

await Kernel.Root.SendAsync(new SubmitCode(mermaidCodeStringBuilder.ToString(), "mermaid"));

Listing 4: Generierung von Mermaid-Code und Aufrufen des Mermaid-Subkernels in einer C#-Zelle

Das durch Mermaid generierte Tortendiagramm in Abbildung 5 zeigt, welcher Kunde wie oft das Produkt 988 gekauft hat und somit von der Rückrufaktion betroffen ist.

Vergleich der Dateiformate

Für Polyglot Notebooks stehen die zwei Dateiformate .ipynb und .dib zur Verfügung. Bei .ipynb handelt es sich um das klassische Jupyter-Notebook-Format, das den Output des Codes in der Datei mit abspeichert. Output bedeutet hierbei die Ausgabe von ausgeführtem Code, der unter Umständen sensible Daten, wie Secrets oder personen- oder firmenbezogene Daten, enthalten kann und das Einchecken von Notebooks in Quellcodeverwaltungssystemen erschwert. Es ist daher sicherzustellen, dass der Output gelöscht wird. Das Format gewährleistet Kompatibilität zum Jupyter-Format und ermöglicht es, Notebooks auch in anderen Anwendungen zu bearbeiten, wie zum Beispiel JupyterLab.

Das .dib-Format hingegen speichert den Code in einer eigenen Struktur, die nicht mit Jupyter-Produkten kompatibel ist. Der Vorteil dieses Formats ist jedoch, dass das Notebook die Ausgabe des ausgeführten Codes nicht enthält, was die Arbeit mit sensiblen Daten wie Secrets und einem Codeverwaltungssystem wie Git erleichtert. Zusätzlich ist die Struktur flacher als die JSON-Struktur von .ipynb-Dateien, wodurch Codeänderungen bei der Code-Review leichter nachvollziehbar sind.

Sofern die Kompatibilität mit dem Jupyter-Format nicht erforderlich ist, sollte aufgrund der beschriebenen Vorteile mit dem .dib-Format gearbeitet werden.

Stolpersteine und Einschränkungen

Leider gibt es ein paar Stolpersteine und Einschränkungen, die beim Erstellen des hier verwendeten Beispiels aufgefallen sind. Zum einen besteht das genannte Problem mit dem .ipynb-Dateiformat, das aber nicht Polyglot-Notebooks-spezifisch ist. Das alternative Format von Poylglot Notebooks (.dib) ist dabei eine geeignete Lösung. Zudem ist die offizielle Dokumentation an diversen Stellen verbesserungswürdig, weist Lücken auf und verzögert das eigentliche Ziel der Umsetzung. Da Mermaid und HTML keine Variablen unterstützen, ist die dynamische Generierung von Diagrammen oder HTML umständlich.

Ein größeres Problem liegt allerdings darin, dass der Polyglot-Notebook-Kernel unter unbekannten Umständen in einen fehlerhaften Zustand geraten und einen Kernel-Neustart erfordern kann. Funktionieren IDE-Features wie Code-Vervollständigung oder Syntax- und Error-Highlighting nicht mehr, lässt sich das gegebenenfalls durch zwischenzeitliches Selektieren einer anderen Code-Zelle mit anschließendem Zurückwechseln beheben. Notfalls ist ein kompletter Neustart von VS Code erforderlich.