vexplor/노드_플로우_데이터소스_설정_가이드.md

노드 플로우 데이터 소스 설정 가이드

개요

노드 플로우 편집기에서 테이블 소스 노드와 외부 DB 소스 노드에 데이터 소스 타입을 설정할 수 있습니다. 이제 버튼에서 전달된 데이터를 사용할지, 아니면 테이블의 전체 데이터를 직접 조회할지 선택할 수 있습니다.

지원 노드

1. 테이블 소스 노드 (내부 DB)

• 위치: 노드 팔레트 > 데이터 소스 > 테이블 소스
• 용도: 내부 데이터베이스의 테이블 데이터 조회

2. 외부 DB 소스 노드

• 위치: 노드 팔레트 > 데이터 소스 > 외부 DB 소스
• 용도: 외부 데이터베이스의 테이블 데이터 조회

데이터 소스 타입

1. 컨텍스트 데이터 (기본값)

💡 컨텍스트 데이터 모드
버튼 실행 시 전달된 데이터(폼 데이터, 테이블 선택 항목 등)를 사용합니다.

사용 예시:
• 폼 데이터: 1개 레코드
• 테이블 선택: N개 레코드

특징:

• ✅ 버튼에서 제어한 데이터만 처리
• ✅ 성능 우수 (필요한 데이터만 사용)
• ✅ 사용자가 선택한 데이터만 처리
• ⚠️ 버튼 설정에서 데이터 소스를 올바르게 설정해야 함

사용 시나리오:

• 폼 데이터로 새 레코드 생성
• 테이블에서 선택한 항목 일괄 업데이트
• 사용자가 선택한 데이터만 처리

2. 테이블 전체 데이터

📊 테이블 전체 데이터 모드
선택한 테이블의 **모든 행**을 직접 조회합니다.

⚠️ 대량 데이터 시 성능 주의

특징:

• ✅ 테이블의 모든 데이터 처리
• ✅ 버튼 설정과 무관하게 동작
• ✅ 자동으로 전체 데이터 조회
• ⚠️ 대량 데이터 시 메모리 및 성능 이슈 가능
• ⚠️ 네트워크 부하 증가

사용 시나리오:

• 전체 데이터 통계/집계
• 일괄 데이터 마이그레이션
• 전체 데이터 검증
• 백업/복원 작업

설정 방법

1단계: 노드 추가

1. 노드 플로우 편집기 열기
2. 좌측 팔레트에서 테이블 소스 또는 외부 DB 소스 드래그
3. 캔버스에 노드 배치

2단계: 테이블 선택

1. 노드 클릭하여 선택
2. 우측 속성 패널 열림
3. 테이블 선택 드롭다운에서 테이블 선택

3단계: 데이터 소스 설정

1. 데이터 소스 설정 섹션으로 스크롤
2. 데이터 소스 타입 드롭다운 클릭
3. 원하는 모드 선택:
   • 컨텍스트 데이터: 버튼에서 전달된 데이터 사용
   • 테이블 전체 데이터: 테이블의 모든 행 조회

4단계: 저장

• 변경 사항은 즉시 노드에 반영됩니다.
• 별도 저장 버튼 불필요 (자동 저장)

사용 예시

예시 1: 선택된 항목만 처리 (컨텍스트 데이터)

시나리오: 사용자가 테이블에서 선택한 주문만 승인 처리

플로우 구성:

[테이블 소스: orders]
  └─ 데이터 소스: 컨텍스트 데이터
     └─ [조건: status = 'pending']
        └─ [업데이트: status = 'approved']

버튼 설정:

• 제어 데이터 소스: table-selection (테이블 선택 항목)

실행 결과:

• 사용자가 선택한 3개 주문만 승인 처리
• 나머지 주문은 변경되지 않음

예시 2: 전체 데이터 일괄 처리 (테이블 전체 데이터)

시나리오: 모든 고객의 등급을 재계산

플로우 구성:

[테이블 소스: customers]
  └─ 데이터 소스: 테이블 전체 데이터
     └─ [데이터 변환: 등급 계산]
        └─ [업데이트: grade = 계산된 등급]

버튼 설정:

• 제어 데이터 소스: 무관 (테이블 전체를 자동 조회)

실행 결과:

• 모든 고객 레코드의 등급 재계산
• 1,000개 고객 → 1,000개 모두 업데이트

예시 3: 외부 DB 전체 데이터 동기화

시나리오: 외부 ERP의 모든 제품 정보를 내부 DB로 동기화

플로우 구성:

[외부 DB 소스: products]
  └─ 데이터 소스: 테이블 전체 데이터
     └─ [Upsert: 내부 DB products 테이블]

실행 결과:

• 외부 DB의 모든 제품 데이터 조회
• 내부 DB에 동기화 (있으면 업데이트, 없으면 삽입)

노드 실행 로직

컨텍스트 데이터 모드 실행 흐름

// 1. 버튼 클릭
// 2. 버튼에서 데이터 전달 (폼, 테이블 선택 등)
// 3. 노드 플로우 실행
// 4. 테이블 소스 노드가 전달받은 데이터 사용

{
  nodeType: "tableSource",
  config: {
    tableName: "orders",
    dataSourceType: "context-data"
  },
  // 실행 시 버튼에서 전달된 데이터 사용
  input: [
    { id: 1, status: "pending" },
    { id: 2, status: "pending" }
  ]
}

테이블 전체 데이터 모드 실행 흐름

// 1. 버튼 클릭
// 2. 노드 플로우 실행
// 3. 테이블 소스 노드가 직접 DB 조회
// 4. 모든 행을 반환

{
  nodeType: "tableSource",
  config: {
    tableName: "orders",
    dataSourceType: "table-all"
  },
  // 실행 시 DB에서 전체 데이터 조회
  query: "SELECT * FROM orders",
  output: [
    { id: 1, status: "pending" },
    { id: 2, status: "approved" },
    { id: 3, status: "completed" },
    // ... 수천 개의 행
  ]
}

성능 고려사항

컨텍스트 데이터 모드

• ✅ 성능 우수: 필요한 데이터만 처리
• ✅ 메모리 효율: 선택된 데이터만 메모리에 로드
• ✅ 네트워크 효율: 최소한의 데이터 전송

테이블 전체 데이터 모드

• ⚠️ 대량 데이터 주의: 수천~수만 개 행 처리 시 느려질 수 있음
• ⚠️ 메모리 사용: 모든 데이터를 메모리에 로드
• ⚠️ 네트워크 부하: 전체 데이터 전송

권장 사항:

• 데이터가 1,000개 이하: 테이블 전체 데이터 사용 가능
• 데이터가 10,000개 이상: 컨텍스트 데이터 + 필터링 권장
• 데이터가 100,000개 이상: 배치 처리 또는 서버 사이드 처리 필요

디버깅

콘솔 로그 확인

데이터 소스 타입 변경 시:

✅ 데이터 소스 타입 변경: table-all

노드 실행 시:

// 컨텍스트 데이터 모드
🔍 테이블 소스 노드 실행: orders
📊 입력 데이터: 3건 (컨텍스트에서 전달됨)

// 테이블 전체 데이터 모드
🔍 테이블 소스 노드 실행: orders
📊 테이블 전체 데이터 조회: 1,234건

일반적인 문제

Q1: 컨텍스트 데이터 모드인데 데이터가 없습니다

A: 버튼 설정을 확인하세요.

• 버튼 설정 > 제어 데이터 소스가 올바르게 설정되어 있는지 확인
• 폼 데이터: form
• 테이블 선택: table-selection
• 테이블 전체: table-all

Q2: 테이블 전체 데이터 모드가 느립니다

A:

1. 데이터 양 확인 (몇 개 행인지?)
2. 필요하면 컨텍스트 데이터 + 필터링으로 변경
3. WHERE 조건으로 범위 제한

Q3: 외부 DB 소스가 오래 걸립니다

A:

1. 외부 DB 연결 상태 확인
2. 네트워크 지연 확인
3. 외부 DB의 인덱스 확인

버튼 설정과의 관계

버튼 데이터 소스 vs 노드 데이터 소스

버튼 설정	노드 설정	결과
table-selection	context-data	선택된 항목만 처리 ✅
table-all	context-data	전체 데이터 전달됨 ⚠️
무관	table-all	노드가 직접 전체 조회 ✅
form	context-data	폼 데이터만 처리 ✅

권장 조합:

1. 선택된 항목 처리:
   버튼: table-selection → 노드: context-data

2. 테이블 전체 처리:
   버튼: 무관 → 노드: table-all

3. 폼 데이터 처리:
   버튼: form → 노드: context-data

마이그레이션 가이드

기존 노드 업데이트

기존에 생성된 노드는 자동으로 context-data 모드로 설정됩니다.

업데이트 방법:

1. 노드 선택
2. 속성 패널 열기
3. 데이터 소스 설정 섹션에서 table-all로 변경

베스트 프랙티스

✅ 좋은 예

// 시나리오: 사용자가 선택한 주문 취소
[테이블 소스: orders]
  dataSourceType: "context-data"  // ✅ 선택된 주문만 처리
  ↓
[업데이트: status = 'cancelled']

// 시나리오: 모든 만료된 쿠폰 삭제
[테이블 소스: coupons]
  dataSourceType: "table-all"  // ✅ 전체 조회 후 필터링
  ↓
[조건: expiry_date < today]
  ↓
[삭제]

❌ 나쁜 예

// 시나리오: 단일 주문 업데이트인데 전체 조회
[테이블 소스: orders]
  dataSourceType: "table-all"  // ❌ 불필요한 전체 조회
  ↓
[조건: id = 123]  // 한 개만 필요한데 전체를 조회함
  ↓
[업데이트]

요약

언제 어떤 모드를 사용해야 하나요?

상황	권장 모드
폼 데이터로 새 레코드 생성	컨텍스트 데이터
테이블에서 선택한 항목 수정	컨텍스트 데이터
전체 데이터 통계/집계	테이블 전체 데이터
일괄 데이터 마이그레이션	테이블 전체 데이터
특정 조건의 데이터 처리	테이블 전체 데이터 + 조건
외부 DB 동기화	테이블 전체 데이터

핵심 원칙

1. 기본은 컨텍스트 데이터: 대부분의 경우 이것으로 충분합니다.
2. 전체 데이터는 신중히: 성능 영향을 고려하세요.
3. 버튼과 노드를 함께 설계: 데이터 흐름을 명확히 이해하세요.

관련 문서

• 제어관리_데이터소스_확장_가이드.md - 버튼 데이터 소스 설정
• 노드 플로우 기본 가이드 (준비 중)

업데이트 이력

• 2025-01-24: 초기 문서 작성
  • 테이블 소스 노드에 데이터 소스 타입 추가
  • 외부 DB 소스 노드에 데이터 소스 타입 추가
  • context-data, table-all 모드 지원