매크로 만들기

매크로는 입력/출력 계약이 선언된 재사용 가능한 고급(DAG) 워크플로입니다. 다른 워크플로에서 Macro Run 단계 또는 Macro Concurrent 단계로 매크로를 호출하며, 각 호출은 자체의 격리된 스크래치 스키마에서 실행되므로 같은 매크로를 여러 상위 워크플로나 여러 드라이버 행에서 동시에 호출해도 실행이 충돌하지 않습니다.

반복 가능하고 매개변수화된 데이터 변환(예: “한 지역의 한 달 판매 데이터 처리”)을 월별, 지역별 또는 둘 다에 대해 드라이버 워크플로에서 한 번씩 호출하려는 경우 매크로를 사용하십시오. 호출자는 테이블과 변수를 매크로에 선언된 입력 포트에 바인딩하며, 매크로가 끝나면 선언된 출력 테이블이 호출자 쪽 대상으로 복사됩니다.

단계

매크로로 만들 워크플로가 들어 있는 프로젝트를 엽니다.
워크플로 탭으로 전환하고 워크플로 행을 선택합니다.
오른쪽의 워크플로 세부 정보 패널에서 워크플로 유형이 고급인지 확인합니다. 표준이면 먼저 고급으로 변환 작업을 사용하십시오.
워크플로 세부 정보 패널의 매크로 섹션에서 매크로로 변환… 을 클릭하고 대화 상자에서 확인합니다. 워크플로가 매크로 모드로 전환되고 포트 편집기가 나타납니다.
포트 추가를 클릭해 매크로가 받거나 생성하는 각 입력 또는 출력을 선언합니다. 각 포트에 대해 다음을 지정합니다.
- 이름 — 호출자가 이 포트에 바인딩할 때 사용하는 짧은 식별자(예: month, region_sales).
- 방향 — 입력(호출자가 이 값이나 테이블을 제공) 또는 출력(매크로가 이를 생성하고 호출자가 가져감).
- 종류 — 데이터 테이블은 테이블, 단일 값(문자열 / 정수 / 실수 / 부울 / 날짜)은 스칼라, 계층형 차원 참조는 차원.
- 필수 — 이 포트가 바인딩되지 않아도 매크로를 실행할 수 있으면 선택을 해제합니다.
- 메모 — 이 포트가 나타내는 내용에 대한 짧은 설명으로, 호출자 쪽 바인딩 양식에서 작성자에게 표시됩니다.
포트 저장을 클릭합니다.

이제 워크플로는 매크로입니다. 다른 워크플로에 Macro Run 단계를 추가하는 작성자에게 선언한 포트가 표시되며, 작성자는 이름으로 포트에 바인딩합니다.

각 포트는 매크로 계약에서 이름과 형식이 지정된 하나의 슬롯입니다. 호출자는 이름으로 포트에 바인딩하며, 입력은 안으로 복사되고 출력은 밖으로 복사됩니다.

매크로 호출

호출자 워크플로에서 다음을 수행합니다.

매크로: 실행 단계를 추가합니다.
실행할 매크로에서 프로젝트와 매크로 워크플로를 선택합니다.
입력 바인딩 — 매크로가 선언한 입력 포트마다 바인딩을 추가합니다.
- 테이블 포트에는 호출자 쪽 소스 테이블을 지정합니다. 선택적으로 열의 일부를 선택하고 필터(매크로의 스칼라 입력 변수를 참조하는 WHERE 절)를 추가해 필요한 부분만 매크로의 실행 스키마에 구체화할 수 있습니다.
- 스칼라 / 차원 포트에는 값(대개 호출자의 워크플로 변수)을 지정합니다. 테이블 입력 필터가 참조할 수 있도록 테이블 복사 입력 전에 설정됩니다.
출력 바인딩 — 매크로가 생성하는 출력 포트마다 호출자 쪽 대상 테이블을 지정합니다(없으면 즉시 생성됩니다).
단계를 저장합니다.

상위 워크플로가 실행되어 Macro Run 단계에 도달하면 러너가 다음을 수행합니다.

이번 매크로 호출을 위한 새 run_id를 발급합니다.
프로젝트 카탈로그에 실행별 스크래치 스키마(macrorun_<run_id>)를 만듭니다.
바인딩된 입력 테이블을 스크래치 스키마로 복사합니다(복사 입력 시 열 프로젝션과 필터가 적용되므로 필터가 푸시다운됩니다).
바인딩된 스칼라 / 차원 입력 변수를 매크로의 실행 범위 변수 오버레이에 설정합니다.
매크로의 단계를 프로세스 내에서 실행합니다. 매크로 내부의 모든 SQL 단계는 프로젝트 스키마 대신 스크래치 스키마를 읽고 씁니다.
선언된 출력 테이블을 호출자의 대상으로 다시 복사합니다.
스크래치 스키마를 삭제합니다(매크로 내부의 단계가 실패했더라도 항상 삭제합니다).

모든 호출은 새 run_id와 자체 스크래치 스키마를 받습니다. 단계는 해당 스키마만 읽고 쓰며, 실행이 성공, 오류, 중지 중 어떤 결과로 끝나든 스키마는 삭제됩니다.

각 호출에 자체 스크래치 스키마가 있으므로 같은 매크로를 동시에 두 번 호출해도(반복문, 팬아웃 또는 독립된 워크플로에서) 중간 테이블 이름이 충돌하지 않습니다.

드라이버 행마다 매크로 하나씩 실행

하나의 호출자 테이블이 여러 개의 독립된 매크로 호출을 구동해야 할 때는 매크로: 동시 실행을 사용합니다.

매크로: 동시 실행 단계를 추가합니다.
드라이버에서 호출자 쪽 드라이버 테이블을 선택하고 동시 실행을 동시에 실행할 하위 매크로 호출의 최대 수로 설정합니다.
테이블 데이터 선택에서 각 하위 호출에 필요한 드라이버 테이블 열을 매핑합니다.
드라이버 필터에서 필요하면 처리할 드라이버 행을 제한합니다.
매크로에서 매크로 워크플로를 선택합니다.
입력 바인딩에서 드라이버 열 값을 매크로의 스칼라 또는 차원 변수에 바인딩하고, 호출자 쪽 테이블을 매크로의 테이블 포트에 바인딩합니다.
출력 바인딩에서 매크로 출력 포트를 호출자 쪽 대상 테이블에 매핑합니다.

선택된 각 드라이버 행은 별도의 run_id와 스크래치 스키마를 받습니다. 상위 단계를 중지하면 활성 상태인 모든 하위 호출이 중지되고 해당 실행 스키마가 삭제됩니다.

드라이버 행마다 하나의 호출이 자체 스크래치 스키마에서 실행되므로 중간 테이블이 충돌하지 않습니다. 동시 실행은 한 번에 실행되는 수를 제한하며, 각 행은 자신의 results_{region} 테이블에 씁니다.

매크로 강등

워크플로 세부 정보 패널에서 고급으로 강등… 을 클릭하면 언제든 매크로 플래그를 해제할 수 있습니다. 워크플로는 일반 고급 워크플로로 되돌아가며, 이를 참조하는 호출자 쪽 Macro Run 단계는 실행 시 “not a macro” 오류로 실패합니다. 선언된 포트는 레코드에 남아 있으므로 나중에 다시 변환하면 복원됩니다.

제한 사항 (v1)

테이블 읽기와 쓰기가 호출의 스크래치 스키마로 격리되므로 매크로에는 테이블 변환, 가져오기, 내보내기를 포함할 수 있습니다. 차원은 프로젝트 전역 상태이므로 차원 가져오기와 차원을 업데이트하는 단계는 허용되지 않습니다. 문서 작업과 에이전트 호출처럼 테이블이 아닌 다른 부작용이 있는 단계는 v1에서 매크로에 안전하지 않습니다.
매크로는 호출자와 같은 프로젝트에 있어야 합니다. 프로젝트 간 매크로는 아직 지원되지 않습니다.
Macro Run 단계는 Run Workflow 단계, Workflow Loop 단계 또는 조건부 Run Workflow 단계에서 호출할 수 없습니다. 이러한 단계는 격리 없이 실행되어 실행별 스키마 계약을 깨뜨리기 때문입니다. 대신 호출자에서 Macro Run 단계를 사용하십시오.

다음 단계

Macro Run 단계 참조 — 호출 단계의 필드별 참조입니다.
Macro Concurrent 단계 참조 — 드라이버 테이블 행마다 매크로 호출을 하나씩 실행합니다.
Run Workflow 단계 — 호출별 격리가 필요하지 않은 하위 워크플로용입니다.