Crear una macro

Una macro es un flujo de trabajo avanzado (DAG) reutilizable con un contrato declarado de entrada y salida. Usted invoca una macro desde otro flujo de trabajo con un paso Macro Run o Macro Concurrent. Cada invocación se ejecuta en su propio esquema temporal aislado, de modo que la misma macro puede llamarse al mismo tiempo desde varios flujos principales o desde varias filas de inductores sin que las ejecuciones colisionen.

Use una macro cuando tenga una transformación de datos repetible y parametrizada (por ejemplo, “procesar un mes de datos de ventas de una región”) que desee invocar desde un flujo de trabajo de inductores una vez por mes, por región o por ambos. El invocador vincula tablas y variables a los puertos de entrada declarados de la macro; cuando esta termina, las tablas de salida declaradas se copian de vuelta a los destinos del invocador.

Nota

Las macros son una función exclusiva de los flujos de trabajo avanzados. Primero convierta su flujo de trabajo a avanzado. Los pasos dentro de la macro deben ser seguros para macros: transformaciones de tablas, importaciones, exportaciones, pasos de variables con alcance de ejecución, llamadas anidadas a Macro Run y algunos pasos de control de flujo. Las importaciones de dimensiones y los pasos que actualizan dimensiones se rechazan porque las dimensiones son un estado global del proyecto.

Pasos

1. Abra el proyecto que contiene el flujo de trabajo que desea convertir en macro.
2. Cambie a la pestaña Flujos de trabajo y seleccione la fila del flujo de trabajo.
3. En el panel derecho Detalles del flujo de trabajo, confirme que el Tipo de flujo de trabajo sea Avanzado. Si es estándar, use primero la acción Convertir a avanzado.
4. En la sección Macro del panel Detalles del flujo de trabajo, haga clic en Convertir en macro… y confirme en el cuadro de diálogo. El flujo de trabajo pasa al modo de macro y aparece un editor de puertos.
5. Haga clic en Agregar puerto para declarar cada entrada o salida que la macro acepta o produce. Para cada puerto:
   • Nombre: un identificador corto que el invocador usa para vincularse a este puerto (por ejemplo, month, region_sales).
   • Dirección: Entrada (el invocador proporciona este valor o esta tabla) o Salida (la macro produce este elemento y el invocador lo recoge).
   • Clase: Tabla para una tabla de datos, Escalar para un único valor (cadena, entero, decimal, booleano o fecha) o Dimensión para una referencia a una dimensión jerárquica.
   • Obligatorio: desactívelo si la macro puede ejecutarse sin que este puerto esté vinculado.
   • Nota: una nota breve sobre lo que representa este puerto, que se muestra a los autores en el formulario de vinculación del invocador.
6. Haga clic en Guardar puertos.

El flujo de trabajo ya es una macro. Los autores que agreguen un paso Macro Run en otro flujo de trabajo verán los puertos que usted declaró y se vincularán a ellos por nombre.

Cada puerto es un espacio con nombre y tipo dentro del contrato de la macro. Los invocadores se vinculan a los puertos por nombre: las entradas se copian hacia dentro y las salidas se copian de vuelta hacia fuera.

Invocar una macro

En el flujo de trabajo invocador:

1. Agregue un paso Macro: ejecutar.
2. En Macro que se ejecutará, seleccione el proyecto y el flujo de trabajo de la macro.
3. Input Port Bindings: para cada puerto de entrada que declara la macro, agregue una vinculación:
   • Los puertos de Tabla toman una tabla de origen del invocador; opcionalmente, seleccione un subconjunto de columnas y agregue un filtro (una cláusula WHERE que haga referencia a las variables escalares de entrada de la macro) para que solo se materialice la porción necesaria en el esquema de ejecución de la macro.
   • Los puertos Escalar / Dimensión toman un valor (a menudo una variable de flujo de trabajo del invocador); defínalo ANTES de la copia de las tablas hacia dentro, para que el filtro de la tabla de entrada pueda hacer referencia a él.
4. Vínculos de salida: para cada puerto de salida que produce la macro, apúntelo a una tabla de destino del invocador (se crea al momento si aún no existe).
5. Guarde el paso.

Cuando el flujo de trabajo principal se ejecuta y llega al paso Macro Run, el ejecutor hace lo siguiente:

1. Genera un nuevo run_id para esta invocación de la macro.
2. Crea un esquema temporal por ejecución (macrorun_<run_id>) en el catálogo del proyecto.
3. Copia las tablas de entrada vinculadas al esquema temporal (la proyección de columnas y el filtro se aplican durante la copia hacia dentro, de modo que el filtro se traslada a la fuente).
4. Establece las variables de entrada escalares y de dimensión vinculadas en la capa de variables con alcance de ejecución de la macro.
5. Ejecuta los pasos de la macro dentro del mismo proceso. Cada paso SQL de la macro lee y escribe en el esquema temporal en lugar del esquema del proyecto.
6. Copia las tablas de salida declaradas de vuelta a los destinos del invocador.
7. Elimina el esquema temporal (siempre, incluso si un paso de la macro falló).

Cada invocación recibe un run_id nuevo y su propio esquema temporal. Los pasos leen y escriben solo en ese esquema, que se elimina cuando termina la ejecución, ya sea por éxito, error o detención.

Como cada invocación tiene su propio esquema temporal, dos llamadas simultáneas a la misma macro (desde un bucle, una distribución en paralelo o flujos de trabajo independientes) nunca colisionan en los nombres de las tablas intermedias.

Ejecutar una macro por cada fila de inductores

Use Macro: ejecución simultánea cuando una tabla del invocador deba impulsar muchas invocaciones independientes de la macro.

1. Agregue un paso Macro: ejecución simultánea.
2. En Inductor, seleccione la tabla de inductores del invocador y establezca Ejecuciones simultáneas en el número máximo de invocaciones secundarias de la macro que se ejecutarán a la vez.
3. En Selección de datos de la tabla, asigne las columnas de la tabla de inductores que necesita cada invocación secundaria.
4. En Filtro de inductor, restrinja opcionalmente las filas de inductores que se procesarán.
5. En Macro, seleccione el flujo de trabajo de la macro.
6. En Vínculos de entrada, vincule los valores de las columnas de inductores a las variables escalares o de dimensión de la macro, y vincule las tablas del invocador a los puertos de tabla de la macro.
7. En Vínculos de salida, asigne los puertos de salida de la macro a las tablas de destino del invocador.

Cada fila de inductores seleccionada recibe un run_id y un esquema temporal independientes. Al detener el paso principal se detienen todas las invocaciones secundarias activas y se eliminan sus esquemas de ejecución.

Una invocación por fila de inductores, cada una en su propio esquema temporal, de modo que las tablas intermedias nunca colisionan. Ejecuciones simultáneas limita cuántas se ejecutan a la vez, y cada fila escribe en su propia tabla results_{region}.

Degradar una macro

Puede quitar el indicador de macro en cualquier momento haciendo clic en Degradar a avanzado… en el panel Detalles del flujo de trabajo. El flujo de trabajo vuelve a ser un flujo de trabajo avanzado normal y los pasos Macro Run del invocador que lo referencien fallarán en tiempo de ejecución con un error de “no es una macro”. Los puertos declarados se conservan en el registro, de modo que, si lo convierte de nuevo más adelante, se restauran.

Limitaciones (v1)

• Las macros pueden contener transformaciones de tablas, importaciones y exportaciones, porque las lecturas y escrituras de tablas quedan aisladas en el esquema temporal de la invocación. No se permiten las importaciones de dimensiones ni los pasos que actualizan dimensiones, porque las dimensiones son un estado global del proyecto. Otros pasos con efectos secundarios que no son de tablas, como las operaciones con documentos y las llamadas a agentes, no son seguros para macros en la v1.
• Las macros deben estar en el mismo proyecto que el invocador. Las macros entre proyectos aún no son compatibles.
• Un paso Macro Run no puede invocarse desde un paso Ejecutar flujo de trabajo, Workflow Loop o Ejecutar flujo de trabajo condicional: esos pasos se ejecutan sin aislamiento y romperían el contrato del esquema por ejecución. En su lugar, use un paso Macro Run en el invocador.

Siguientes pasos

• Referencia del paso Macro Run: la referencia campo por campo del paso invocador.
• Referencia del paso Macro Concurrent: ejecute una invocación de la macro por cada fila de la tabla de inductores.
• Paso Ejecutar flujo de trabajo: para subflujos de trabajo que no necesitan aislamiento por invocación.