Alteryx Designer Desktop Knowledge Base

Definitive answers from Designer Desktop experts.

CS Macro Dev: Batch Macros – when to use the Group By, the Control Parameter or both!

Alteryx Community Team
Alteryx Community Team

This article is part of the CS Macro Development Series. The goal of this series is to communicate tips, tricks, and the thought process that goes into developing good, dynamic macros.

When should you use the Group By function of the Batch macro versus using the Control Parameter tool or even both? In most cases we recommend using the Group By with “simple” batch macros and the Control Parameter with more “complex” batch macros, but I want to be a little more specific and give a few scenarios where you would use one over the other, or even both.

Group By:Group by.png

As mentioned above, the Group By can be used in simpler Batch macros. For instance, your data set contains store data and date data. In the Batch macro, you want to process each store individually so that the date data does not overlap with all of the stores. In this case, creating the Batch macro will allow you to process each store individually. In order to use the Group By, change the workflow configuration to Batch macro and add Macro Input and Macro Output Interface tools. This will be enough to create the Batch macro and enable the Group By function.

When you deploy the macro, you will see:macro.png The inverted question mark¿is the Control Group By field. This is the data that you are going use to group by. So in our example, this would be the list of stores. Good rule is to use either a Unique tool or Summarize tool just before the macro to create a list with each variable showing only once for the Control Group list. The other Input will be your data.

In the Input Group By field, the field will be your data that contains the same groups as the Control Group. You can think of it as a join. If you are pulling your Control Group from the same data set it will more than likely be the same field.

The Group By function is used in situations where you want to take groups of data and process those groups one at a time. i.e.: Where you are not using the group to change other tools within the macro, but wanting to pass each group and process one at a time.

Control Parameter:

The Control Parameter Interface tool allows the user to update specific tools within the Batch Macro with the Control Group. If within your macro you need certain tools to be configured by the Control Group - whether it’s a certain formula, filter, or report - you can use the Control Parameter and the subsequent Action tool (that appears once connected) to update the tool with the Control Group data.

Generally the rule of thumb is that if you need to Batch a tool within the macro, then you will need a Control Parameter to update that tool.

A great example of using the Control Parameter can be found in your Sample data. Help>Sample Workflow>Macro Samples>Batch Macro Sample Workflow

When to use both:

The best way to explain when you would use both the Group By and the Control Parameter is when you want to Batch a large group through the macro, but then also Batch data within a smaller group of the larger group. For instance, say you want to do some calculations with a region of stores; then within that region you want to do calculations with ZIP codes. You can use the Group By to select your region field and then use the Control Parameter to update your tools with the ZIP Codes.

This macro would look first for the region group specified in the group list and then move to batching the data by ZIP code and run through the macro.

The sample attached was completed in

9 - Comet
9 - Comet

Thanks for the great explanation on how to configure batch macros, Dan. 


I recently took at a look at batch macro performance to examine the advantages and disadvantages of Control Parameters vs the Group By method.


Here is my analysis: