노드 그룹 (Node Groups)
그룹은 다른 노드들을 담는 컨테이너 노드입니다. 모든 그룹은 내부에 포함된 노드들을 시각적으로 정리해주지만, 일부 그룹 유형은 더 나아가 해당 노드들의 실행 방식까지 제어합니다(노드들을 함께 실행하거나 반복 실행하는 등). 이 페이지에서는 그룹의 생성, 구성 및 실행에 대해 설명합니다. 일반 노드 작업에 대해서는 노드 작업 가이드를 참조하세요.
그룹 생성
그룹화할 노드들을 선택한 후(나중에 노드를 끌어다 넣을 빈 그룹을 만들려면 아무것도 선택하지 않음) 다음 중 하나를 수행합니다:
Cmd/Ctrl+G를 눌러 기본값으로 지정된 그룹 유형을 사용하여 즉시 그룹을 생성합니다.Shift+Cmd/Ctrl+G를 누르거나 마우스 오른쪽 버튼을 클릭하고 Create Group을 선택하여 그룹 유형 선택기를 먼저 엽니다.
그룹 유형 선택기에는 설치된 라이브러리에서 사용할 수 있는 모든 그룹 유형이 나열되며, Add Node 메뉴와 동일한 방식으로 검색할 수 있습니다. 유형을 선택하기 전에 하단의 Make default for Cmd/Ctrl+G를 선택하면 다음 번에는 선택기를 건너뛰고 바로 생성됩니다. 기본값을 설정하기 전까지는 Cmd/Ctrl+G를 눌러도 선택기가 열립니다.
새 그룹은 생성 시 선택된 노드들을 약간의 여백과 함께 감싸는 크기로 자동 지정됩니다. 노드를 기존 그룹 본문으로 드래그하면 해당 그룹에 추가되고, 자식 노드를 밖으로 드래그하면 그룹에서 제거됩니다.
그룹 유형
표준 라이브러리와 함께 제공되는 그룹 유형은 크게 두 가지 제품군으로 나뉩니다:
| 유형 | 실행 여부 | 기능 |
|---|---|---|
| Group | 미실행 | 순수 구성용입니다. 설명 필드와 함께 노드를 시각적으로 묶어주며, 노드를 단일 단위로 실행하거나 실행 순서에 영향을 주지 않습니다. |
| Subflow Node Group | 실행 | 내부의 모든 노드를 하나의 단위로 병렬 실행합니다. |
| ForEach Group | 실행 | 입력 목록(List) 또는 딕셔너리(Dict)의 각 항목당 한 번씩 내용을 실행합니다. |
| For Loop Group | 실행 | 숫자 범위(start/end/step)의 각 값당 한 번씩 내용을 실행합니다. |
| Retry Group | 실행 | 실행 실패 시 구성 가능한 재시도 횟수까지 내용을 다시 실행합니다. |
일반 Group에는 Run Group 버튼이 없습니다. 실행 가능한 노드가 아니므로 내부 노드가 개별적으로 실행되는 것 외에 엔진이 그룹 단위로 실행할 작업이 없기 때문입니다. 표에 있는 다른 모든 유형은 서브플로우 그룹(subflow group)입니다. 자식 노드를 담기 위한 전용 서브플로우를 생성하며, 그룹 노드 자체가 외부 플로우 그래프에서 단일 실행 단위가 됩니다.
Subflow Node Group
가장 기본적인 실행형 그룹입니다. 그룹이 실행되면 내부의 모든 노드가 자체 서브플로우에서 함께 실행되며, 그 결과 출력들이 그룹 자체의 출력 파라미터로 다시 수집됩니다. 가독성을 위해 여러 노드 클러스터를 더 큰 플로우의 한 단계로 취급하고 싶거나, 각 노드를 개별 실행하는 대신 단일 Run Group 버튼을 사용하고 싶을 때 유용합니다.
ForEach Group
목록이나 딕셔너리를 반복합니다. 리스트(또는 dict)를 items 입력에 연결하면, 그룹은 항목당 한 번씩 자식 노드를 실행하며 해당 항목을 current_item에, 항목의 인덱스를 index에 노출하여 자식 노드가 사용할 수 있도록 합니다. 반대편의 new_item_to_add 입력은 각 반복의 값을 그룹의 results 출력 리스트로 수집합니다.
그룹 설정의 Execution Mode를 통해 반복을 한 번에 하나씩(one at a time) 실행할지 동시에 모두(all at once) 실행할지 선택할 수 있습니다. 순차(sequential) 모드에서만 Skip to Next Iteration 및 Break Out of Loop 제어 입력을 지원합니다. 모든 반복이 이미 동시에 실행 중인 상태에서는 건너뛸 "다음 반복"이 없으므로, 일괄 모드로 전환하면 이 입력들이 자동으로 숨겨집니다. 설정의 Testing Mode 토글을 사용하면 루프 본문을 배선하는 동안 전체 리스트 대신 선택한 단일 인덱스만 실행해 볼 수 있습니다.
For Loop Group
ForEach와 구조는 동일하지만 리스트 대신 숫자 범위를 반복합니다(start, end, step, 그리고 범위에 끝값을 포함할지 제어하는 Include end value 토글). ForEach와 동일한 Execution Mode, results, skip, break 메커니즘을 공유합니다.
Retry Group
내용 실행이 실패했을 때 다시 실행합니다. 자식 노드의 성공 경로를 그룹의 Succeeded 제어 입력에 연결하고, 실패 경로를 Failed에 연결합니다. Failed가 트리거되고 시도 횟수(Max Iterations, 기본값 3)가 남아 있으면 전체 그룹이 다시 실행됩니다. Succeeded가 트리거되거나 시도 횟수가 소진되면 다운스트림으로 실행이 계속되며, was_successful 파라미터에 성공 여부가 보고됩니다. Raise on failure 토글을 켜면 재시도 한도가 소진되었을 때 was_successful을 false로 설정하고 계속 진행하는 대신 워크플로우를 오류와 함께 중단합니다.
그룹 경계를 가로지르는 연결 배선 (Wall Parameters)
서브플로우 그룹 외부에서 내부 노드로(또는 내부에서 외부로) 연결되는 모든 배선은 그룹 노드 자체에 존재하는 월 파라미터(wall parameter)를 통해 라우팅됩니다. 이는 그룹의 왼쪽 가장자리(유입되는 항목) 또는 오른쪽 가장자리(유출되는 항목)에 표시됩니다. 이를 직접 수동으로 생성할 필요는 없습니다. 내부 노드의 핸들에서 외부 노드로(또는 그 반대로) 연결선을 드래그하면 월 파라미터가 자동으로 생성되어 직결 배선됩니다.
내부적으로 각 월 파라미터는 프록시 역할을 합니다. 엔진은 직접 연결을 삭제하고 그룹에 일치하는 파라미터를 추가한 다음, 한 번이 아닌 두 단계에 걸쳐 다시 연결합니다. 월 연결이 있는 노드를 그룹 밖으로 드래그하면 해당 연결은 단일 직접 연결로 다시 복원되고 더 이상 사용되지 않는 월 파라미터는 사라집니다. 그룹 내부의 두 노드가 동일한 외부 소스에 접근해야 하는 경우 각각 생성되지 않고 단일 월 파라미터를 공유합니다.
일반 Group은 이러한 작업을 수행하지 않습니다. 분리할 서브플로우가 없으므로 연결선이 경계를 그대로 통과합니다.
그룹 내 그룹 중첩 (Nesting)
원하는 만큼 깊게 그룹 안에 다른 그룹을 포함할 수 있습니다. 한 그룹을 다른 그룹의 본문으로 드래그하거나, 그룹을 다른 노드와 함께 선택하고 Cmd/Ctrl+G를 누르면 내부 그룹이 외부 그룹의 자식이 되며 이미 내부에 있던 모든 항목이 함께 이동합니다.
중첩은 대규모 플로우를 가독성 높은 계층으로 나누는 방법입니다. 예를 들어 본문 자체가 Subflow Node Group인 ForEach Group을 구성하면, 각 반복마다 수많은 개별 노드 대신 명명된 작업 클러스터가 실행되도록 만들 수 있습니다.
단일 그룹이 제공하는 모든 동작이 각 계층에 동일하게 적용됩니다. 외부 그룹을 실행하면 내부 그룹도 그 일부로 함께 실행되므로 개별적으로 실행할 필요가 없습니다. 축소, 롤업, Fit to nodes는 명령을 호출한 해당 그룹에만 적용되며 내부에 중첩된 항목에는 영향을 주지 않습니다.
연결 배선도 동일한 방식으로 중첩됩니다. 외부 그룹 바깥에서 두 단계 깊이에 위치한 노드로 연결되는 선은 통과하는 각 그룹의 월 파라미터를 거치므로, 경계를 하나씩 거쳐 안쪽으로 데이터 흐름을 추적할 수 있습니다. 한 그룹 내부에만 머무는 연결은 그룹이 얼마나 깊이 중첩되어 있든 월 파라미터가 생성되지 않으며, 경계를 넘을 때만 생성됩니다.
Ungroup(그룹 해제)은 한 번에 한 계층씩 벗겨냅니다. 외부 그룹을 그룹 해제하면 내부 그룹은 온전한 상태를 유지하며 자식 노드를 포함한 채 캔버스의 기존 위치에 그대로 남습니다. 그룹을 삭제할 때도 내부에 있던 항목들에 대해 동일하게 동작합니다.
에디터에서 허용하지 않는 유일한 배치는 그룹이 자기 자신 내부로 들어가는 순환 중첩입니다. 실행할 최상위 그룹이 남지 않게 되므로 그룹을 자신의 하위 자손 그룹으로 드래그하는 작업은 거부됩니다.
접기 및 롤업 (Collapsing and rolling up)
그룹 헤더의 쉐브론(V자 아이콘)을 클릭하면 그룹을 접기(collapse)할 수 있습니다. 접힌 그룹은 자식 노드를 숨기고 월 파라미터만 표시되도록 크기가 축소됩니다(월 파라미터가 없으면 "Group collapsed"라는 한 줄만 표시됨). 이는 배선 기능을 유지하면서 대형 그룹을 입력 및 출력 크기로 빠르게 축소하는 가장 빠른 방법입니다.
롤업 (Roll up) — 설정에서 Node Roll-Up이 활성화된 경우 그룹 헤더를 더블클릭하거나 접기 버튼 옆의 롤업 버튼을 사용하면 레이아웃을 버리지 않고 유사한 작업을 수행합니다. 그룹의 현재 너비와 자식 노드 위치를 그대로 유지하면서 헤더 높이만큼 축소되므로, 다시 확장하면 이전 상태 그대로 즉시 복원됩니다.
노드에 맞춤 (Fit to nodes)
Fit to nodes(Shift+F로 단일 그룹 선택 시 실행하거나 그룹의 우클릭 메뉴 / 툴바 사용)는 모든 면에 고정된 여백을 두고 현재 내부에 있는 노드들을 딱 맞게 감싸도록 그룹 상자의 크기를 조정합니다. 수동으로 자식 노드를 추가하거나 제거한 후 그룹 상자가 실제 내부 노드 위치와 맞지 않을 때 사용하세요.
그룹 해제 (Ungrouping)
그룹의 우클릭 메뉴 또는 툴바에서 Ungroup을 선택하면 그룹 래퍼가 제거되고 자식 노드는 그룹 상대 위치에서 캔버스 절대 위치로 변환되어 원래 자리에 그대로 남습니다. 서브플로우 그룹의 경우 전용 서브플로우도 함께 정리되고 모든 월 연결이 원래 노드 간의 직접 연결로 복원되므로, 그룹화 구조만 제거될 뿐 기본 배선은 전혀 손실되지 않습니다.
그룹 노드를 (그룹 해제하는 대신) 완전히 삭제하는 경우에도 자식 노드에 동일하게 적용됩니다. 자식 노드가 그룹과 함께 삭제되지 않고 분리되어 캔버스에 남게 됩니다.
그룹 실행
실행 가능한 그룹 유형은 모든 그룹이 가진 접기 및 복제 컨트롤과 함께 툴바에 Run Group 버튼이 표시됩니다(그룹이 선택되었을 때 표시됨). 그룹을 실행하면 단일 노드를 실행할 때와 마찬가지로 해당 그룹과 업스트림의 모든 종속 노드가 순차적으로 확인 및 해결(resolve)됩니다.
서브플로우 그룹에는 노드가 실제로 실행될 위치를 선택하는 Execution Environment(실행 환경) 설정(그룹 설정 팝오버)도 제공됩니다. 기본값은 Local Execution(캔버스의 다른 모든 노드와 마찬가지로 엔진 프로세스 내부에서 실행)이며, 원격으로 워크플로우를 게시하고 실행하는 기능을 등록한 설치 라이브러리에 따라 추가 옵션이 나타납니다.
그룹이 실행되는 동안 헤더에 일반 노드와 동일한 Running / Resolved / Unresolved 상태 표시 캡슐(pill)이 표시됩니다. 일반 Group은 단위별로 실행되지 않으므로 이 상태 캡슐이 표시되지 않습니다.