노드 추가
파이프라인 캔버스에 데이터 입력, 처리, 출력에 필요한 노드를 추가합니다. 노드를 배치한 뒤 각 노드의 속성을 설정합니다.
노드 추가 방법
빠른 추가
왼쪽 구성 요소 라이브러리의 빠른 추가에서 원하는 노드를 캔버스로 끌어다 놓습니다. 노드는 데이터셋(델타·카프카·REST), 온톨로지(엔티티·관계), **코드(Python·SQL)**와 **변환(선택/필터·조인·유니온·집계·이름변경/형변환)**으로 구분됩니다.
기존 자산 불러오기
왼쪽 패널의 컬렉션 트리에서 기존 데이터셋·코드 자산을 찾아 끌어다 놓습니다. 빠른 추가에 없는 object 데이터셋도 컬렉션 트리에서 선택합니다. 온톨로지 엔티티·관계는 빠른 추가에서 추가합니다.
구성 요소 라이브러리의 기존 코드를 캔버스로 끌어다 놓으면 코드 참조 삽입 창이 열립니다. 파이프라인과 같은 컬렉션에 있는 Code를 이름으로 검색하고 Python·SQL 언어를 확인한 뒤 추가합니다. 컬렉션 트리에서 기존 Code를 직접 끌어다 놓아도 같은 공유 참조가 만들어집니다. 빠른 추가의 Python / SQL은 새 코드 초안을 만드는 동작이므로 기존 Code 참조와 구분합니다.
마우스 오른쪽 버튼 메뉴
캔버스 빈 공간에서 마우스 오른쪽 버튼을 클릭하면 다음 항목이 표시됩니다.
| 메뉴 항목 | 설명 |
|---|---|
| 데이터셋 추가 | 델타, 카프카, REST 중에서 선택합니다. |
| 코드 추가 | Python 또는 SQL을 선택합니다. |
| 엔티티 추가 / 관계 추가 | 온톨로지 엔티티 또는 관계 노드를 추가합니다. |
| 자동 정렬 | 노드를 선택한 방식으로 정렬합니다. |
노드를 선택한 뒤 마우스 오른쪽 버튼을 클릭하면 다음 옵션이 표시됩니다.
| 메뉴 항목 | 설명 |
|---|---|
| 편집 | 속성 패널을 엽니다. |
| 복제 | 노드를 복제합니다. |
| 결과 데이터셋 추가 | 코드 노드에 출력 데이터셋 노드를 만들어 연결합니다. |
| 삭제 | 노드를 삭제합니다. |
키보드 단축키
- 데이터셋 노드 추가:
⌘Shift+D(macOS) /Ctrl+Shift+D(Windows)를 누릅니다. - 코드 노드 추가:
⌘Shift+C(macOS) /Ctrl+Shift+C(Windows)를 누릅니다.
코드 노드를 다른 이름으로 저장하기
코드 노드는 컬렉션에 저장된 공용 코드 자산을 불러옵니다. 여러 파이프라인이 같은 코드 자산을 참조합니다. 속성 패널에서 코드를 수정할 때는 다음 규칙을 따릅니다.
- 불러온 코드 노드를 열어 내용을 수정하면, 속성 패널에 저장 방식 선택이 나타납니다.
- 원본을 고칠 권한이 있으면 원본 덮어쓰기를 선택합니다. 권한이 없거나 원본을 유지하려면 다른 이름으로 저장을 선택해 사본을 만듭니다.
- 사본으로 저장하면 원본 코드 자산은 그대로 남으므로 다른 파이프라인에는 영향을 주지 않습니다.
노드 유형
데이터셋 노드
데이터셋 노드는 데이터를 읽거나 처리 결과를 저장합니다. 데이터셋의 type 값(delta, kafka, rest, object)에 따라 연결 방식이 달라집니다.
| 서브타입 | 설명 | 용도 |
|---|---|---|
delta | 버전 관리 테이블 | 배치 데이터 처리, 버전 관리 |
kafka | 메시지 스트림 | 실시간 스트리밍 데이터 |
rest | HTTP 엔드포인트 | 외부 API 호출 |
object | 파일/객체 스토리지 | 비정형 파일 입출력 |
데이터셋 노드의 속성 패널은 스키마와 데이터를 읽기 전용으로 표시합니다. 입력·출력과 읽기 모드·쓰기 모드는 연결된 코드 노드의 옵션 탭에서 설정합니다. 연결 규칙은 노드 연결하기에서 확인합니다.
코드 노드
코드 노드는 데이터를 변환하거나 집계합니다. 코드 자산의 type에 따라 Python 또는 SQL 편집기를 사용합니다.
| 타입 | 용도 |
|---|---|
| Python | 데이터 처리, 머신러닝 모델 적용, 외부 API 호출 |
| SQL | Polars SQL을 사용한 데이터 변환, 집계, 조인, 필터링 |
코드 실행 계약은 다음과 같습니다.
Python에서는 연결별 입력 매개변수와 options, contexts를 받는 run 함수를 정의하고 딕셔너리를 반환합니다. 새 연결에는 input과 output이 기본 키로 제안될 수 있지만 코드 노드의 옵션 탭에서 바꿀 수 있습니다. 함수 매개변수와 반환 키를 옵션 탭의 입력·출력 키와 맞춥니다.
import polars as pl
def run(input, *, options=None, contexts=None):
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
네이티브 변환 노드: 반복되는 표준 변환은 코드를 작성하지 않고 다음 노드로 구성합니다.
- 선택/필터는 입력 1개, 전달할 컬럼·선택 별칭과 선택적 필터식을 설정합니다. 컬럼을 지정하지 않으면 모두 전달합니다.
- 조인은 왼쪽·오른쪽 입력 2개, 내부·왼쪽·오른쪽·전체 조인 유형과 양쪽 조인 키를 설정합니다. 필요한 출력 컬럼과 별칭을 추가합니다.
- 유니온은 입력 2개 이상을 선택해 행을 합칩니다. 입력 스키마의 컬럼 이름과 타입을 맞춥니다.
- 집계는 입력 1개, 그룹화 컬럼과 집계 대상·함수·출력 별칭을 설정합니다.
- 이름변경/형변환은 입력 1개에서 컬럼별 출력 이름·별칭과
utf8,int64,float64,bool형 변환을 설정합니다.
입력 데이터셋·소스·엔티티·관계를 먼저 연결하면 속성 패널의 컬럼 선택기가 해당 스키마를 후보로 제안합니다. 변환이 참조하는 입력·출력 키는 캔버스 연결 포트와 같아야 합니다. 설정한 뒤 검증으로 누락된 입력·키·형식을 확인하고 미리보기로 저장하지 않은 결과를 최대 50행까지 확인합니다. 오류가 나면 버튼 아래의 서버 검증 메시지를 확인합니다. 임의 Python 패키지, 외부 호출, 복잡한 분기처럼 다섯 연산으로 표현할 수 없는 처리는 코드 노드를 사용합니다.
엔티티·관계 노드
온톨로지에서 정의한 엔티티와 관계를 단계의 입력이나 출력으로 사용합니다.
- 식별 키: 엔티티에는 파이프라인 입출력에 사용할 식별 키가 있어야 합니다. 관계 노드는 스키마에 식별 키가 없으면 경고 아이콘을 표시할 수 있으므로 실행 전에 대상 스키마와 런타임 요구 사항을 확인합니다. 이 경고는 관계 생성 조건과는 별개입니다.
- 속성: 속성 패널의 속성 탭에서 식별 키와 표시 컬럼을 포함한 스키마를 읽기 전용으로 확인합니다.
- 표시 컬럼: 목록과 상세 화면에서 각 항목을 대표할 컬럼입니다.
엔티티·관계를 데이터셋과 함께 사용하려면 데이터셋을 코드 노드의 입력으로, 엔티티·관계를 코드 노드의 출력으로 설정합니다. 필드는 자동으로 연결되지 않으므로 코드 출력의 컬럼 이름과 타입을 대상 스키마에 맞춥니다.
노드를 연결하려면
노드를 배치한 뒤 노드 연결하기에서 연결 방향, 허용되는 조합, 읽기·쓰기 모드를 설정합니다.
노드 관리
- 이동: 노드를 끌어 위치를 변경합니다.
- 복제: 노드를 선택한 뒤 마우스 오른쪽 버튼을 클릭하고 복제를 선택하거나
⌘D(macOS) /Ctrl+D(Windows)를 사용합니다. - 삭제: 노드를 선택하고
Delete키를 누르거나 마우스 오른쪽 버튼 메뉴의 삭제를 선택합니다. - 자동 정렬: 캔버스 컨트롤의 자동 정렬 드롭다운에서 레이아웃을 선택합니다.
| 레이아웃 | 설명 |
|---|---|
| 좌 → 우 | 왼쪽에서 오른쪽으로 배치합니다. |
| 상 → 하 | 위에서 아래로 배치합니다. |
| 파이프라인 DAG | 데이터 흐름 방향에 따라 배치합니다. |
| Force-Directed | 연결 관계에 따라 노드 간격을 조정합니다. |
| 원형 | 노드를 원형으로 배치합니다. |
| 격자 | 노드를 격자에 맞춰 배치합니다. |
메뉴의 계층형은 독립 실행 항목이 아니라 좌 → 우와 상 → 하를 묶는 그룹 제목입니다.
- 그룹 선택:
Shift를 누른 채 빈 영역을 끌어 여러 노드를 한 번에 선택합니다.
공유 Code 참조 노드의 메타 영역에는 이 Code를 함께 사용하는 다른 파이프라인 수가 표시됩니다. 숫자에 마우스를 올리면 최대 5개 이름과 나머지 개수를 확인합니다. 속성 패널의 개요 → 원본 코드에서 원본 이름·별칭·설명·식별자를 확인하고 컬렉션에서 보기를 누르면 컬렉션 트리가 원본 위치까지 펼쳐집니다. 파이프라인 단계에 따로 입력한 별칭·설명은 이 단계 표시에서 원본 Code의 표시 정보보다 우선합니다. 본문을 고치면 원본 덮어쓰기 또는 다른 이름으로 저장을 선택하며, 후자는 공유 참조가 아닌 독립 사본을 만듭니다.
이름, 별칭, 복제
각 노드에는 이름과 별칭이 있습니다. 이름은 파이프라인 안에서 같은 유형끼리 고유한 테이블 식별자입니다. 별칭은 화면에 표시되는 이름이며 개요 탭에서 바꿉니다. 이름은 대부분 읽기 전용이며 새로 추가한 데이터셋 초안에서만 편집합니다.
- 복제 이름 규칙: 노드를 복제하면 이름 뒤에
_copy가 붙습니다(예:orders→orders_copy). 같은 이름이 이미 있으면_copy_2,_copy_3처럼 숫자가 이어집니다(_copy_1은 쓰지 않습니다). - 기존 자산의 이름이 중복되는 경우: 코드 노드의 옵션 탭에서 기존 데이터셋·엔티티·관계를 선택했을 때 같은 유형과 이름의 노드가 있으면 새 이름으로 저장 창이 열립니다. 새 이름의 사본을 만들어 연결합니다. 자세한 규칙은 노드 연결하기에서 확인합니다.