Tx macros in transformation modeling enable users to create reusable scripts for data manipulation within Tx Objects. Tx macros are defined, compiled, and executed through a script-based interface, allowing users to define operations once and reuse them across different processes, ensuring consistency and reducing redundancy.
Creating a Tx macro
To create a new Tx macro:
Navigate to the Tx Explorer.
Click on the three-dot icon next to Tx macros to open the context menu.
Select Create new. This will generate a new Tx macro object with a default script template, which opens in the Script Editor.
Customize the script by defining the logic you need.
Once a Tx macro is created, its name will default to macroName. You can modify this in the script editor, and the change will be reflected across the project. Tx macro naming must follow the Python naming rules for functions that will be validated in the script:
macroNamemust start with a letter (a-z, A-Z) or an underscore (_), followed by letters, digits (0-9), or underscores. It cannot start with a digit. It cannot start and end with double underscores (__).macroNamecannot be a Python keyword or reserved word, such asif,else,for,while,import,defmacroNamecannot contain punctuation symbols such as !, @, #, $, %, etc. Spaces are not allowed.
Editing a Tx macro
To edit a Tx macro:
Click on the Tx macro object in the Tx Explorer.
A new tab with the Script Editor and Results Tab will open. Make changes directly in the script.
Compile the script using the Compile Macro button. The parameters defined in compilation within the Tx macro are only examples to test the development. These parameters need to be defined each time a Tx Macro is called in a Tx object. Any errors or warnings will be shown in the Results Tab.
When editing a Tx macro, the name of the macro (macroName) will be validated. Errors will be displayed in the Errors & Warnings tab. Some typical validation checks include:
Duplicate Tx macro names
Missing required properties
Incorrect Python function naming rules
How Tx macro parameters work
Defining parameters in Tx macros: When defining a Tx macro, you can specify parameters that act as placeholders. These parameters receive values when the Tx macro is called. For example, a parameter could be a column name, a filter condition, or any other value that needs to change dynamically depending on the context of the Tx macro’s execution.
Using parameters in the Tx macro Body: Inside the Tx macro body, parameters can be used to perform operations or manipulate SQL code dynamically. When the Tx macro is invoked, the provided values replace the parameters, allowing the same Tx macro logic to be applied in different contexts.
Calling Tx macros and passing arguments: When calling a Tx macro, you pass arguments corresponding to the defined parameters. These arguments can be strings, numbers, or other expressions, depending on the needs of the script. For example:
{{ macroName('column1', 'value') }}.Optional parameters with default values: You can also set default values for parameters when defining the Tx macro. If a default value is provided, the parameter becomes optional when calling the Tx macro. If no argument is passed for that parameter, the default value will be used automatically. For example:
{{ macroName('column1=MYCOLUMN', 'value') }}.
Duplicating and deleting Tx macros
Duplicate Tx macro: Right-click on an existing Tx macro and select Duplicate. This will create an editable copy with the same script and append a logical identifier to its name.
Delete Tx macro: Select the Delete option from the context menu. A confirmation dialog will appear, but there are no warnings regarding dependencies on the Tx macro in other objects. Deleting a Tx macro is permanent and cannot be undone.
Compiling a Tx macro
After defining or editing a Tx macro, it can be compiled to test it. The compile process checks the Tx macro for syntax errors and other issues:
Click the Compile Macro button.
If the Tx macro has parameters, they must be entered in the Compile Parameters box. If not provided, the compilation will fail.
The Results Tab will display the success or failure of the compilation, with any resulting SQL shown after successful compilation.
Using a Tx macro in Tx objects
When editing any script in my project, I can reference a Tx macro object by using Jinja syntax for this: {{ macroName(macro params values) }}. The Tx Macro will be compiled and resolved with any execution in the Tx object, Validate create, Create, Validate run or Run.
When I reference a Tx macro object in any script, this does not create a relationship in the object’s diagram.
See also: