엔티티 설계 — 이름 · Identity · Display · 속성 타입

엔티티는 현실 세계의 객체 한 종류를 추상화한 단위입니다. 본 레슨은 빌더에서 엔티티를 한 개 만들고, 다음 레슨의 데이터셋 매핑까지 이어 갈 수 있도록 스키마 메타데이터까지 채워 둡니다. 예시는 IoT 시나리오의 가장 작은 엔티티 IOT_Machine 한 개.

사전 준비

• 자기 컬렉션 한 개 (없다면 분석가 코스 02 레슨의 컬렉션 만들기 단계로 5 분 안에 준비).
• 그 컬렉션 안에 데이터셋이 한 개 이상 있어야 합니다. 03 레슨의 매핑 단계에서 씁니다. 깨끗한 데이터셋이 아니어도 됩니다 — 컬럼명과 타입만 알면 됩니다.

빌더는 좌측 사이드바의 ONTOLOGY → Modeling 에서 진입합니다. 본인 컬렉션 컨텍스트로 진입했다면 collection_id 가 자동 적용됩니다.

빈 캔버스에서 엔티티 한 개 올리기

1. 빌더 캔버스가 빈 상태에서 상단 + Entity 버튼을 누르거나, 좌측 템플릿 패널에서 Person 같은 미리 정의된 템플릿을 캔버스로 드래그합니다.
2. 우측 인스펙터(속성 패널)가 열립니다. 본 레슨은 템플릿이 아니라 수동 생성으로 진행합니다.

이 시점에 캔버스에는 익명 노드 한 개가 떠 있고, 인스펙터는 비어 있습니다. 다음 다섯 영역을 위에서 아래로 채웁니다.

1. 기본 정보 — 이름 · 별칭 · 설명

• Name — 시스템 이름. 영문 대문자 + 도메인 접두어 권장(예: IOT_Machine). 이 이름이 Cypher 쿼리의 :Label 로 그대로 노출되므로 한국어/공백/하이픈은 피합니다.
• Alias — 사용자에게 보여줄 별칭. 인스펙터 · 노드 라벨 · 글로벌 검색의 1차 타이틀로 씁니다. 한국어 자연어 그대로(예: CNC 기계).
• Description — 1–2 줄 자연어 설명. 인스펙터 AI 버튼으로 자동 생성할 수도 있지만, 한 줄이라도 본인 단어로 적어두면 6 개월 뒤 본인을 살려 줍니다(예: "machine_id 로 식별되는 공장 내 CNC 기계 단위 엔티티입니다.").
• Collection — 필수. 컬렉션 컨텍스트로 들어왔다면 자동 채움. 비어 있으면 저장 시 422.

2. 스키마 — 속성 정의

스키마 영역에서 엔티티가 가질 속성을 한 줄씩 추가합니다. 이 시점에는 어떤 컬럼이 데이터셋에 있는지를 머리에 두고 1:1 로 맞춰 적습니다. IOT_Machine 예시:

속성 타입은 다음 6 종이 1차로 쓰입니다.

• Text — 문자열. ID · 코드 · 자연어. (예: machine_id)
• Integer — 정수. 카운트 · 횟수. (예: sensor_count)
• Float — 실수. 비율 · 점수. (예: latest_health_score)
• Boolean — 참/거짓. 플래그.
• Date — 날짜만.
• Timestamp — 날짜 + 시각. 시계열 · 이벤트의 발생 시점.

해당 도메인에 더 정밀한 타입(예: Decimal)이 필요해지면 사용자 매뉴얼의 엔티티 관리 페이지가 확장 타입을 정리해 둡니다. 본 페이지 하단의 관련 사용자 매뉴얼 블록을 참고.

3. Identity Keys — 인스턴스 고유 식별

스키마 한 줄 옆의 Identity Key 체크박스가 그 컬럼을 고유 식별 키로 잠급니다. IOT_Machine 예시는 machine_id 한 컬럼만 체크.

• 복수 컬럼 체크 가능(복합 키). 예: (supplier_id, contract_period).
• 비어 있으면 빌더에 경고가 뜨고, 이 엔티티를 쓰는 파이프라인의 Entity 노드가 실행 시점 페이로드 검증에서 실패합니다. 본 레슨은 항상 한 줄 이상 체크하고 진행합니다.

4. Display Column — UI 1차 라벨

같은 스키마 영역의 Display Column 드롭다운에서 전체 스키마 중 하나를 1차 라벨로 지정합니다. IOT_Machine 예시는 식별 자체가 라벨 역할을 하므로 machine_id 그대로 둡니다. 사람이 읽는 자연어 컬럼이 있다면 그쪽이 더 자연스럽습니다(예: name, customer_name).

이 한 줄이 채워지면 그래프 탐색기에서 노드를 클릭했을 때 "익명 노드 1234" 가 아니라 그 인스턴스의 라벨이 그대로 뜹니다.

5. 저장 — 그리고 자가 점검

캔버스 상단의 저장 (또는 Ctrl/Cmd + S) 을 누르면 엔티티가 컬렉션 안에 등록됩니다. 다음 네 가지를 인스펙터에서 한 번에 확인합니다.

• 노드 라벨이 별칭으로 떠 있는가 (예: CNC 기계)
• 시스템 이름이 부제목에 떠 있는가 (예: IOT_Machine)
• Identity Keys 한 줄 이상 체크돼 있는가
• Display Column 이 한 컬럼으로 지정돼 있는가

저장 후 같은 컬렉션의 다른 작업자가 같은 엔티티를 짧은 간격으로 다시 저장하면 Self-overwrite 경고 가 인스펙터에 뜹니다 — 한 번 더 멈춰 의도를 확인합니다.

자가 점검

• 엔티티 한 개가 자기 컬렉션 안에 저장됐는가
• name / alias / description 세 줄이 모두 채워졌는가
• Identity Keys 한 줄 이상, Display Column 한 줄이 지정됐는가
• 속성 타입 6 종 중 도메인에 맞는 두 종 이상을 직접 골라 봤는가

다음 레슨

다음 레슨은 본 엔티티의 속성을 자기 컬렉션의 데이터셋 컬럼에 1:1 로 매핑합니다. 매핑이 끝나면 백엔드 sink 가 그래프 데이터베이스로 인스턴스를 채우고, 그래프 탐색기에서 첫 노드가 보이기 시작합니다.