Zio.Ingestion()

수집 파이프라인이 채운 **원본 데이터(ingestion_data 테이블)**를 직접 다룹니다. 메일 · DB · 스프레드시트 · 웹 · API 로 들어온 것이 여기 raw_data 로 쌓입니다. 조회 · 세기 · 생성 · 수정 · 삭제(CRUD)를 Zio.entity 와 같은 방식으로 합니다.

필드 이름을 짐작하지 마십시오

수집 스키마는 인스턴스 · 산업마다 완전히 다릅니다 (음식 · 건축 · 패션 …). 어떤 스키마가 있고 그 안에 어떤 필드가 있는지는 먼저 Zio.ingestion.schemas() 로 확인하십시오. 필드 이름을 짐작하면 조용히 빈 결과가 나옵니다.

무엇을 물어볼 수 있나

아래 <스키마명> · <필드명> 은 자리표시자입니다. 실제 이름은 schemas() 로 확인한 것을 씁니다.

이런 요청을 받으면	이렇게
무엇을 수집하고 있어? / 어떤 항목이 있어?	Zio.ingestion.schemas()
OO 데이터 최근 것부터 보여줘	Zio.ingestion("<스키마명>").order_by("-ingested_at").fetch()
이 조건에 맞는 것만 보여줘	.where(**{"<필드명>": "<값>"}).fetch()
이 조건에 맞는 게 몇 개야?	.where(**{"<필드명>": "<값>"}).count()
여러 필드 중 하나라도 맞으면 (OR)	.where_or(status__contains="x", sender_email__contains="y").fetch() 같은 스키마의 여러 조건을 OR 로 묶습니다(다른 .where() 와는 AND). 한 덩어리 안에 상단 컬럼과 raw_data 필드가 섞여도 됩니다. 여러 번 부르면 각 호출이 별개의 OR 덩어리. 접미사는 .where() 와 같습니다. 읽기(fetch·count)에만 걸립니다 — update·delete 에 OR 을 걸면 의도보다 많은 건을 건드릴 수 있어 받지 않습니다.
아직 처리 안 된 / 에러난 것만	.where(status="error").fetch() · process_state 비트 조건
값을 고쳐줘 / 상태를 바꿔줘	.where(...).update({...})
이것들 지워줘	.where(...).delete()
한 건 수동으로 넣어줘	Zio.ingestion("<스키마명>").create({...})

관계 · 그룹 집계는 여기가 아닙니다

“누가 누구랑 거래했나” 같은 관계 질문이나 “항목값별로 몇 건씩” 같은 묶음(group by) 집계는 분석이 끝나 지식 그래프에 들어간 것을 봐야 합니다 → Zio.node. 여기(Zio.ingestion)는 원본이라 조건 조회와 .count() 까지만 합니다.

수집데이터 Fluent CRUD API

Method	Description
Zio.ingestion.schemas()	수집 스키마 목록을 가져옵니다. 각 항목은 {name, group, description, count, columns[]} — name 은 고유 식별자(주소로 씀), group 은 파이프라인 종류(예: odbc, 여럿이 공유), columns 에 그 스키마의 실제 필드명 · 타입이 들어 있습니다. 조회 전에 먼저 부르십시오.
Zio.ingestion(schema)	한 수집 스키마를 대상으로 하는 Fluent 체이닝의 시작점입니다. schema 에는 schemas() 가 준 name 을 넣습니다 — name 은 유일하게 강제되므로 이것이 정식 주소입니다. group(파이프라인 종류) 이름을 넣으면 주소가 아니라 그 그룹 안의 스키마 이름들을 알려주며 되돌립니다 — 그중 하나를 고르십시오. (숫자 schema_id 도 받긴 합니다만, 이름이 유일해진 지금은 쓸 일이 없습니다.)
.where(**filters)	조건을 겁니다. raw_data 안의 필드와 상단 컬럼(id · status · process_state · source_identifier · ingested_at) 둘 다 됩니다. 접미사: __contains · __gte · __lte · __in 등. 필드명이 한글 · 공백이면 .where(**{"필드명": 값}) 형태로 넘깁니다.
.order_by(*fields)	정렬. 이름 앞의 - 가 내림차순 (예: "-ingested_at").
.fetch(limit=100, skip=0)	조건에 맞는 데이터를 GraphResult 로 가져옵니다. raw_data 를 평탄화하고 id · status · process_state 를 함께 담습니다.
.count()	조건에 맞는 건수를 셉니다. (묶음 집계는 없습니다 — 위 안내 참고)
.create(props)	데이터 한 행을 넣습니다. props 는 raw_data 필드입니다. 기본값으로 status="pending" · process_state=1(수집 완료) 이 들어가 후속 공정이 흐릅니다. 보통은 파이프라인이 하는 일이라 드물게 씁니다.
.where(...).update(props)	조건에 맞는 행을 고칩니다. raw_data 필드도, status · process_state 도 바꿀 수 있습니다. 조건(where)이 없으면 거절합니다.
.where(...).delete()	조건에 맞는 행을 지웁니다. 딸린 것(분석 · 심층분석 · 첨부 · 추론 큐)과 디스크의 첨부 파일까지 함께 지웁니다. 되돌릴 수 없고, 조건이 없으면 거절합니다.

공정 이력 · 상태값 — process_state 와 status

데이터가 어느 공정까지 왔는지는 process_state(비트 누적)가, 엔진이 그것을 처리할지는 status 가 정합니다. 이 값을 update 로 바꾸면 cron 워커가 알아서 재처리합니다 — 재실행 자체는 이 SDK 가 하지 않습니다.

process_state	정수값	뜻
Bit 0	1	수집 완료
Bit 1	2	데이터 강화 (AI 누락 보완)
Bit 2	4	카테고리 분류
Bit 3	8	집계 / 요약
Bit 4	16	에이전트(Dynamic) · 지식 그래프 처리
Bit 5	32	최종 추론

status	엔진	뜻
pending	가동	처리 대기 (신규 또는 수동 재처리 하달)
processing	잠금	워커 작업 중 (중복 방지)
done	정지	현재 할당된 공정 일단락
error	중단	예외로 멈춤 (확인 필요)
paused	중단	사용자가 수동으로 멈춤

※ 수집 단계(Bit 0~3)를 되돌리면 후속 비트(Bit 4 · 5)는 자동으로 0 으로 리셋되어 신선도를 지킵니다.

예시 (실제 스키마 · 필드명은 schemas() 로 확인 — 아래는 자리표시자)

from zio_ontology import Zio

# 1. 무엇을 수집하고 있나 — 필드명은 여기서 확인한다 (인스턴스마다 다르다)
for s in Zio.ingestion.schemas():
    print(s["name"], s["count"], [c["name"] for c in s["columns"]])

# 2. 조건에 맞는 건수 세기
#    <스키마명> · <필드명> 은 위에서 확인한 실제 이름으로 바꾼다
n = Zio.ingestion("<스키마명>").where(**{"<필드명>": "<값>"}).count()

# 3. 최근 것부터 100건 조회
rows = Zio.ingestion("<스키마명>").order_by("-ingested_at").fetch(limit=100).data

# 4. 조건에 맞는 값 고치기 (where 없으면 거절)
Zio.ingestion("<스키마명>").where(**{"<필드명>": "<값>"}).update({"<필드명>": "<새값>"})

# 5. 상태를 바꿔 재처리 흐르게 하기 (cron 이 알아서 다시 처리)
Zio.ingestion("<스키마명>").where(id=123).update({"status": "pending", "process_state": 1})

# 6. 조건에 맞는 것 지우기 (딸린 것·첨부 파일까지 함께, 되돌릴 수 없음)
Zio.ingestion("<스키마명>").where(**{"<필드명>": "<값>"}).delete()

---

원본을 고치면 파생 결과는 따라오지 않습니다

raw_data 를 update 로 바꿔도, 이미 만들어진 지식 그래프 · 분석 결과는 자동으로 바뀌지 않습니다. 분석 결과까지 새로 반영하려면 process_state 의 해당 비트를 되돌려(예: 수집 비트만 남기고 나머지 0) cron 이 다시 처리하게 하거나, 그래프를 직접(Zio.node) 고치십시오.