노드 추가 및 연결
워크플로우를 구성하는 노드를 추가하고 데이터 흐름을 연결하는 방법을 설명합니다.
노드 추가 방법
1. 빠른 추가 (Quick Add)
왼쪽 패널의 Quick Add 섹션에서 원하는 노드를 캔버스로 드래그 앤 드롭합니다. 팔레트는 데이터셋(델타·카프카·REST) · 온톨로지(엔티티·관계) · 코드(Python·SQL) 로 묶여 있습니다.
2. 컬렉션에서 가져오기
왼쪽 패널의 Collections 트리에서 이미 만들어 둔 데이터셋·코드를 찾아 드래그 앤 드롭합니다. 재사용성을 높이는 가장 좋은 방법이며, Quick Add에 없는 object 데이터셋도 여기서 끌어옵니다. 온톨로지 엔티티·관계는 컬렉션 트리가 아니라 Quick Add에서 추가합니다.
3. 컨텍스트 메뉴
캔버스 빈 공간을 우클릭하면 다음 항목으로 노드를 추가할 수 있습니다.
| 메뉴 항목 | 설명 |
|---|---|
| 데이터셋 추가 | 델타 / 카프카 / REST 하위 메뉴에서 선택 |
| 코드 추가 | Python / SQL |
| 엔티티 추가 / 관계 추가 | 온톨로지 엔티티·관계 노드 |
| 자동 정렬 | 노드 자동 배치 |
노드 위에서 우클릭하면 다음 옵션을 사용할 수 있습니다.
| 메뉴 항목 | 설명 |
|---|---|
| 편집 (Edit) | 인스펙터 열기 |
| 복제 (Duplicate) | 노드 복제 |
| 결과 데이터셋 추가 | (코드 노드) 출력 데이터셋 노드를 생성해 연결 |
| 삭제 (Delete) | 노드 삭제 |
4. 키보드 단축키
- 데이터셋 노드 추가:
Ctrl(Cmd) + Shift + D - 코드 노드 추가:
Ctrl(Cmd) + Shift + C
코드 노드 참조와 Save-As 모델
코드 노드는 컬렉션에 저장된 공용 코드 자산을 파이프라인에서 참조하는 방식으로 동작합니다. 동일한 코드를 여러 파이프라인에서 재사용할 수 있으며, 인스펙터에서 편집할 때 다음 규칙이 적용됩니다.
- 참조 코드 노드를 열어 내용을 수정하면, 인스펙터에 저장 방식 선택이 나타납니다.
- 원본에 대한 쓰기 권한이 있으면 원본 덮어쓰기를, 권한이 없으면 다른 이름으로 저장(Save As) 으로 현재 파이프라인용 사본을 만듭니다.
- 사본으로 저장하면 원본 코드 자산은 그대로 유지되어 다른 파이프라인에 영향을 주지 않습니다.
즉, 자동 분기를 만들지 않고 사용자가 명시적으로 분기 시점을 결정합니다.
노드 유형
데이터셋 노드 (Dataset Node)
데이터의 소스(Source) 또는 싱크(Sink) 역할을 합니다. 데이터셋의 서브타입(type: delta / kafka / rest / object)에 따라 적절한 어댑터가 사용됩니다.
| 서브타입 | 설명 | 용도 |
|---|---|---|
delta | Delta Lake 테이블 | 배치 데이터 처리, 버전 관리 |
kafka | Kafka 토픽 | 실시간 스트리밍 데이터 |
rest | HTTP 엔드포인트 | 외부 API 호출 |
object | 파일/객체 스토리지 | 비정형 파일 입출력 |
데이터셋 노드의 인스펙터는 스키마와 데이터를 읽기 전용으로 보여줍니다. 데이터셋의 연결(입력/출력)과 읽기 모드·쓰기 모드는 데이터셋 노드가 아니라, 연결된 코드 노드의 옵션 탭에서 설정합니다(아래 노드 연결 참고).
코드 노드 (Code Node)
데이터를 변환·처리하는 로직을 수행합니다. 코드 자원의 type(python 또는 sql)에 따라 실행 엔진이 선택됩니다.
| 타입 | 용도 |
|---|---|
| Python | 범용 데이터 처리, ML 모델 적용, 외부 API 호출 |
| SQL | 데이터 변환, 집계, 조인, 필터링 |
코드 실행 계약은 다음과 같습니다.
Python — run(input, options) 함수를 정의하고 {"output": DataFrame} 형식으로 반환합니다(입력은 Polars DataFrame).
import polars as pl
def run(input, options):
output = input.filter(pl.col("total") > 1000)
return {"output": output}
SQL — input을 입력 테이블 이름으로 사용하며, 쿼리 결과가 출력이 됩니다.
SELECT category, SUM(amount) AS total_amount, COUNT(*) AS order_count
FROM input
GROUP BY category
ORDER BY total_amount DESC
Entity / Relation 노드 (온톨로지 자원)
온톨로지로 정의된 엔티티(Entity) 와 관계(Relationship) 도 step의 입출력으로 사용할 수 있습니다.
캔버스에 Entity / Relation 노드가 배치된 상태. 인스펙터의 속성 탭에 식별 키·표시 컬럼·backing dataset 정보가 보여야 합니다. PK 누락 경고도 함께 보여주면 좋습니다.
- PK 필수: 엔티티/관계는 식별 키(Identity Keys)가 정의되어 있어야 합니다. 키가 비어 있으면 노드에 경고 아이콘이 표시됩니다.
- backing dataset: 노드는 엔티티/관계가 가리키는 backing dataset에 연결됩니다. 인스펙터의 속성 탭에서 매핑된 컬럼·키를 확인합니다.
- 표시 컬럼(Display Column): 인스턴스를 1차 라벨로 식별할 컬럼입니다.
노드 연결
데이터의 흐름을 정의하기 위해 노드들을 연결합니다.
- 선행 노드(Upstream)의 오른쪽 핸들(Output)에 마우스를 가져갑니다.
- 클릭 후 드래그하여 후행 노드(Downstream)의 왼쪽 핸들(Input)에 놓습니다.
- 연결선(Edge)이 생성되며 데이터 의존성이 설정됩니다.
연결 규칙
- 데이터셋 / Entity / Relation 노드 → 코드 노드: 데이터 읽기 (소스)
- 코드 노드 → 데이터셋 / Entity / Relation 노드: 데이터 쓰기 (싱크)
- 코드 노드 → 코드 노드: 중간 결과 전달
- 데이터셋 → 데이터셋 직접 연결은 허용되지 않습니다(중간에 코드 노드 필요).
연결 후에는 코드 노드의 옵션 탭에 입력/출력 바인딩이 기록되며, 거기서 읽기 모드(증분/전체)와 쓰기 모드(추가/덮어쓰기/병합)를 설정합니다. 자세한 규칙은 노드 연결 문서를 참고하세요.
노드 관리
- 이동: 노드를 드래그하여 위치를 변경합니다.
- 복제: 노드를 선택하고 우클릭 메뉴의 복제 또는
Ctrl(Cmd)+D를 사용합니다. - 삭제: 노드를 선택하고
Delete키를 누르거나 우클릭 메뉴의 삭제를 선택합니다. - 자동 정렬: 캔버스 컨트롤의 자동 정렬 드롭다운에서 레이아웃을 선택합니다.
| 레이아웃 | 설명 |
|---|---|
| 좌 → 우 (LR) | 왼쪽에서 오른쪽 방향 |
| 상 → 하 (TB) | 위에서 아래 방향 |
| 파이프라인 DAG | 방향성 비순환 그래프 레이아웃 |
| Force-Directed | 힘 기반 자동 정렬 |
| 원형 (Circular) | 원형 배치 |
| 격자 (Grid) | 격자형 배치 |
| 계층형 (Hierarchical) | 계층 구조 배치 |
- 그룹 선택:
Shift+ 드래그로 여러 노드를 한 번에 선택합니다.