Ihre Arbeit wiederverwenden: Variablen, Makros und UDFs

~30 Minuten · eine Variable, ein Makro, eine benutzerdefinierte Transformation

Der erste Workflow, den Sie erstellen, enthält meist alles fest verdrahtet – eine Region, einen Monat, einen Tabellennamen. Er funktioniert einmal. Dieses Tutorial ist der Sprung vom Benutzer zum Power-User: Sie machen aus dieser einmaligen Pipeline ein Asset, das Sie auf jede Region richten, von überall aufrufen und mit eigenem Python erweitern können.

Drei Werkzeuge leisten die Arbeit, und sie bauen aufeinander auf:

Werkzeug	Was es beseitigt	Wann Sie es einsetzen
Workflow-Variable	Fest verdrahtete Werte, die über Schritte verstreut sind	Derselbe Wert (ein Monat, eine Region, ein Schwellenwert) taucht in mehr als einem Schritt auf
Makro	Per Kopieren und Einfügen vervielfachte Schrittabfolgen	Eine parametrisierte Abfolge wird häufig ausgeführt – pro Region, pro Monat, pro Treiberzeile
User Defined Transform (UDF)	Die Lücke, die die Standardschritte nicht schließen können	Keine Standardtransformation (oder Kombination) leistet, was Sie brauchen, und Sie können es in Python schreiben

Sie brauchen nicht alle drei in jedem Workflow. Fügen Sie jedes in dem Moment hinzu, in dem der Schmerz, den es beseitigt, tatsächlich auftritt.

Jedes Werkzeug deckt mehr ab als das vorherige. Fügen Sie sie hinzu, wenn der Bedarf entsteht – nicht vorher.

Voraussetzungen

• Ein PlaidCloud-Workspace und ein Projekt mit einem bereits erstellten Workflow – idealerweise dem aus Daten laden, transformieren und veröffentlichen.
• Sicherer Umgang mit dem Hinzufügen und Ausführen von Workflow-Schritten. Falls das neu für Sie ist, beginnen Sie mit dem Workflows-Leitfaden.

Schritt 1: Mit einer Workflow-Variable parametrisieren

Eine Variable ist ein benannter Wert, den Ihre Schritte statt eines Literals lesen. Ändern Sie sie an einer Stelle, und jeder Schritt, der auf sie verweist, folgt. PlaidCloud führt Variablen auf zwei Ebenen: Projektvariablen werden von allen Workflows des Projekts gemeinsam genutzt; Workflowvariablen gehören zu einem Workflow und sind der natürliche Weg, Informationen zwischen seinen Schritten weiterzugeben.

1. Klicken Sie in der Hierarchie Workflows auf das Symbol variables, um die Variablentabelle zu öffnen.
2. Fügen Sie eine Variable hinzu – geben Sie ihr einen klaren Namen wie target_region und legen Sie ihren aktuellen Wert fest (zum Beispiel East).
3. Verweisen Sie in einem Schritt, der diesen Wert derzeit fest verdrahtet, auf die Variable, statt das Literal einzutippen.
4. Führen Sie den Schritt aus. Ändern Sie dann den Wert der Variable in der Tabelle und führen Sie erneut aus – derselbe Schritt verarbeitet nun einen anderen Ausschnitt, ohne dass der Schritt selbst bearbeitet wird.

In der Variablentabelle sehen Sie außerdem aktuelle Werte, bearbeiten sie und löschen Variablen, die Sie nicht mehr brauchen.

Projektebene vs. Workflow-Ebene. Legen Sie einen Wert auf Projektebene ab, wenn mehrere Workflows dieselbe Einstellung benötigen, und auf Workflow-Ebene, wenn er nur für die Schritte eines Workflows gilt. Im Zweifel beginnen Sie eng – mit einer Workflow-Variable – und heben sie erst dann auf Projektebene, wenn ein zweiter Workflow sie braucht.

Das vollständige Bild dazu, wo Variablen liegen und wie Sie sie verwalten, finden Sie unter Workflow-Variablen verwalten.

Schritt 2: Eine Abfolge als Makro verpacken

Eine Variable parametrisiert einen Wert. Ein Makro parametrisiert eine ganze Abfolge von Schritten. Es ist ein wiederverwendbarer erweiterter (DAG-)Workflow mit einem deklarierten Eingabe-/Ausgabevertrag – denken Sie an „einen Monat Umsatz für eine Region verarbeiten“ –, den Sie aus einem anderen Workflow einmal pro Monat, pro Region oder beides aufrufen. Jeder Aufruf läuft in seinem eigenen isolierten Arbeitsschema, sodass dasselbe Makro viele Male gleichzeitig laufen kann, ohne dass sich die Ausführungen in die Quere kommen.

Makros sind ein reines Feature erweiterter Workflows. Konvertieren Sie den Workflow zuerst in einen erweiterten. Schritte innerhalb eines Makros müssen makrotauglich sein – Tabellentransformationen, Importe, Exporte, auf die Ausführung begrenzte Variablenschritte und verschachtelte Makroaufrufe sind in Ordnung; Dimensionsimporte und Schritte, die Dimensionen aktualisieren, werden abgelehnt, weil Dimensionen projektglobaler Zustand sind.

Einen Workflow in ein Makro umwandeln

1. Öffnen Sie das Projekt und wählen Sie auf der Registerkarte Workflows den Workflow aus, den Sie wiederverwenden möchten.
2. Vergewissern Sie sich im Bereich Workflow-Details, dass Workflow-Typ auf Erweitert steht – verwenden Sie zuerst In Erweitert konvertieren, wenn er Standard ist.
3. Klicken Sie im Abschnitt Makro auf In Makro konvertieren… und bestätigen Sie. Ein Port-Editor erscheint.
4. Klicken Sie für jede Eingabe oder Ausgabe, die das Makro annimmt oder erzeugt, auf Port hinzufügen. Legen Sie für jeden Port fest:
   • Name – der Bezeichner, an den der Aufrufer bindet (zum Beispiel month, region_sales).
   • Richtung – Eingabe (der Aufrufer liefert sie) oder Ausgabe (das Makro erzeugt sie).
   • Art – Tabelle, Skalar (ein einzelner String / Integer / Float / Bool / Datumswert) oder Dimension.
   • Erforderlich – deaktivieren Sie die Option, wenn das Makro auch ohne gebundenen Port laufen kann.
   • Notiz – ein kurzer Hinweis, der Autoren im Bindungsformular auf der Aufruferseite angezeigt wird.
5. Klicken Sie auf Ports speichern.

Aus einem anderen Workflow aufrufen

1. Fügen Sie im aufrufenden Workflow einen Schritt Makro: Ausführen hinzu.
2. Wählen Sie unter Auszuführendes Makro das Projekt und den Makro-Workflow aus.
3. Input Port Bindings – binden Sie jeden Eingabe-Port. Skalar- und Dimensions-Ports nehmen häufig eine Workflow-Variable der Aufruferseite entgegen (die aus Schritt 1); Tabellen-Ports nehmen eine Quelltabelle entgegen, optional spaltenprojiziert und gefiltert.
4. Output Port Bindings – richten Sie jeden Ausgabe-Port auf eine Zieltabelle der Aufruferseite.
5. Speichern Sie den Schritt und führen Sie den Workflow aus.

Um das Makro einmal pro Zeile einer Treibertabelle auszuführen – etwa eine Region pro Zeile –, verwenden Sie stattdessen einen Schritt Makro: Gleichzeitige Ausführung und begrenzen Sie mit Gleichzeitige Ausführungen, wie viele gleichzeitig laufen. Jede Zeile erhält ihr eigenes Arbeitsschema und Ziel.

Die vollständige Anleitung Feld für Feld, einschließlich des Isolationslebenszyklus einer Ausführung, finden Sie unter Ein Makro erstellen.

Schritt 3: Eigene Logik mit einer User Defined Transform hinzufügen

Die Standardtransformationen decken fast alles ab und werden laufend auf Leistung optimiert – greifen Sie zuerst zu ihnen. Wenn aber kein Standardschritt (allein oder in Kombination) leistet, was Sie brauchen, können Sie mit einer User Defined Transform (UDF) in Standard-Python wechseln, mit der vollständigen PlaidCloud-API und Paketen wie Pandas, NumPy und SciPy.

Eine UDF können Sie auf zwei Arten erstellen: direkt in PlaidCloud schreiben und pflegen oder auf eine Datei in einem verbundenen Git-Repository verweisen (das Änderungen bei der nächsten Ausführung automatisch übernimmt und Branches und Tags zur Releasesteuerung unterstützt).

Die Funktion schreiben

1. Öffnen Sie den Workflow, wählen Sie die Registerkarte Benutzerdefiniert und klicken Sie auf Add User Defined Function.

2. Geben Sie der UDF eine ID und klicken Sie dann auf das Symbol Edit function logic, um den Editor zu öffnen.

3. Schreiben Sie Ihre Logik. Eine minimale UDF verbindet sich, liest eine Quelle, transformiert in Pandas und speichert ein Ziel:

   from plaidcloud.utilities.connect import PlaidConnection
   from plaidcloud.utilities import frame_manager as fm
   
   conn = PlaidConnection()
   
   # Read a table configured as a source on the step
   source = conn.udf.source_by_name('sales_clean')
   df = conn.get_data(source)
   
   # Custom logic the standard steps don't cover
   df['margin_band'] = df['margin'].apply(
       lambda m: 'high' if m > 0.4 else 'low'
   )
   
   # Write to a table configured as a target on the step.
   # Sources are read by their configured name; fm.save writes to a table PATH (leading slash).
   fm.save(df, name='/output/sales_scored', append=False)

Zum Workflow hinzufügen

1. Fügen Sie auf der Registerkarte Analyze Steps einen Schritt User Defined Transform dort hinzu, wo Sie ihn brauchen – genau wie eine Standardtransformation.
2. Wählen Sie in der Schrittkonfiguration den Typ: UDF analysieren (eine gespeicherte Funktion) oder Externes Quellcode-Repository (Git – wählen Sie dann Verbindung, Branch und Dateipfad).
3. Definieren Sie die Quell- und Zieltabellen, die die UDF verwendet. Sie können im Code direkt auf Tabellen zugreifen, aber ihre Deklaration hier registriert die Abhängigkeiten und macht sie über conn.udf.source_by_name(...) / target_by_name(...) verfügbar.
4. Fügen Sie optional schrittspezifische Werte unter Weitere Variablen hinzu, die mit conn.udf.variable_by_name(...) gelesen werden können.

Deklarieren Sie Ihre Tabellen in der Konfiguration, nicht nur im Code. Eine UDF, die eine Tabelle direkt liest, läuft zwar trotzdem, aber PlaidCloud weiß dann nicht, dass die Tabelle eine Abhängigkeit ist – sodass Lineage und Ausführungsreihenfolge sie nicht berücksichtigen können. Wenn Sie Quellen und Ziele in der Schrittkonfiguration auflisten, bleibt der Abhängigkeitsgraph korrekt.

Projekt- und Workflow-Variablen aus Schritt 1 sind auch innerhalb der UDF erreichbar, über conn.analyze.workflow.variable_values(...) und conn.analyze.project.variable_values(...) – so steuert derselbe Parameter Ihre Standardschritte und Ihren eigenen Code. Vollständige API-Beispiele finden Sie in der Referenz zur User Defined Transform.

Das ist der Sprung vom Benutzer zum Power-User. Sie haben eine einmalige Pipeline in wiederverwendbare Assets verwandelt – einen Wert, den Sie per Variable umlenken können, eine ganze Abfolge, die Sie als Makro überall aufrufen können, und eigenes Python, das erreicht, was die Standardschritte nicht erreichen.

Wie es weitergeht

• Workflow-Variablen verwalten – Projekt- vs. Workflow-Ebene und die Variablentabelle.
• Ein Makro erstellen – Ports, Isolation der Ausführung und ein Makro pro Zeile ansteuern.
• Referenz zur User Defined Transform – die vollständige API-Oberfläche für eigenes Python.
• Workflows-Leitfaden – Bedingungen, Schleifen und alles andere, was die Orchestrierungsebene bietet.
• Daten mit SQL transformieren – das Schwester-Tutorial für den Fall, dass die Antwort eine Abfrage ist und kein Code.