콘텐츠로 이동

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()
한 건 수동으로 넣어줘 못 넣습니다 — 수집 표에는 수집 파이프라인을 통해서만 들어갑니다. 아래 .create(props) 참고

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

섹션 제목: “관계 · 그룹 집계는 여기가 아닙니다”

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

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, include_derived=True) 조건에 맞는 데이터를 GraphResult 로 가져옵니다. 한 건은 완전체 — 스키마별 필드 + 공통 메타 + 공통 파생(security_scan · ocr · inference_result · analysis_result). 구조는 아래 「한 건의 구조」 참고. 대량 조회로 파생 계산이 부담이면 include_derived=False (원본 + 메타만, 빠름).
.count() 조건에 맞는 건수를 셉니다. (묶음 집계는 없습니다 — 위 안내 참고)
.create(props) 쓸 수 없습니다. 수집 표에는 수집 파이프라인을 통해서만 들어갑니다 — 중복 검사(PK) · 정형화 · 처리 상태를 파이프라인이 정하기 때문입니다. 부르면 그 까닭을 적어 거절합니다. 새 데이터는 그 수집 스키마의 파이프라인(수집 연결 + 스케줄)으로 가져옵니다. 지난 날짜는 @getDate(-7) 처럼 부릅니다. 고친 지난 건을 다시 받으려면 그 건을 delete() 하고 파이프라인이 다시 가져가게 합니다 — 이미 있는 PK 는 건너뛰는 것이 설계입니다.
.where(...).update(props) 조건에 맞는 행을 고칩니다. raw_data 필드도, status · process_state 도 바꿀 수 있습니다. 조건(where)이 없으면 거절합니다.
.where(...).delete() 조건에 맞는 행을 지웁니다. 딸린 것(분석 · 심층분석 · 첨부 · 추론 큐)과 디스크의 첨부 파일까지 함께 지웁니다. 되돌릴 수 없고, 조건이 없으면 거절합니다.
.attachments(id) 그 수집 건(id = _ingestion_id)에 딸린 첨부 목록(메타 + OCR 텍스트). 항목은 {file_name, file_size, saved, cdr_status, ocr_status, ocr_text, ocr_meta}. saved=False 는 차단 · 본문검사 첨부(저장 파일 없음). 첨부는 그 수집 건과 묶여서만 닿습니다.
.attachment(id, "파일명") 첨부 1개 핸들. .bytes() 소독된 본문 바이트 · .text() OCR 로 뽑은 글자(이미지 첨부, 없으면 None) · .save(["상대경로"]) 스킬 폴더에 파일로 저장(경로 안 주면 원래 파일명, 상대경로만 — 폴더 밖 금지).

한 건의 구조 — fetch() 가 돌려주는 1건

섹션 제목: “한 건의 구조 — fetch() 가 돌려주는 1건”

한 건은 세 켜로 이뤄집니다. ①만 스키마마다 다르고, ②③은 어느 수집건이든 같은 모양입니다 — 에이전트가 받는 state["input"] 과 동일합니다.

켜 내용
① 스키마별 (가변) raw_data 를 평탄화한 필드 — subject · body · sender_email …. 필드명은 짐작하지 말고 schemas() 의 columns 로 확인하십시오(인스턴스 · 산업마다 다릅니다).
② 공통 메타 (고정) _ingestion_id · id · status · process_state · source_identifier · ingested_at · schema_id
③ 공통 파생 (고정 구조) 엔진 · 분석이 채우는 네 섹션. 비어도 키 구조는 그대로입니다(빈 {} 가 아님): security_scan · ocr · inference_result · analysis_result.
# fetch() 한 건의 완전한 모양 — ② 공통 메타 · ③ 공통 파생은 늘 이 구조
{
# ① 스키마별 (schemas() 의 columns 로 확인 — 아래는 예시일 뿐, 실제 필드는 다름)
"subject": "...", "body": "...", "sender_email": "...",
# ② 공통 메타
"_ingestion_id": 20543, "id": 20543, "status": "done", "process_state": 63,
"source_identifier": "<...>", "ingested_at": "2026-11-11T03:14:41-05:00", "schema_id": 1,
# ③ 공통 파생 — 고정 구조 (비어도 키는 그대로)
"analysis_result": { }, # 1차 정적 분석 (키는 설계별)
"inference_result": { # 2차 AI 최종 추론
"spam_yn": true, "verdict": "...", "reason": "...",
"scanner_engine": "...", "detected_indicators": []
},
"security_scan": { # 정밀검사 (보안 엔진)
"status": "safe", "av_infected": false, "yara_matched": false,
"url": { "total": 0, "malicious": 0, "suspicious": [] }, "cdr_cleaned": 0
},
"ocr": { # OCR 추출 (이미지 글자)
"extracted": false, "status": "no_image",
"count": 0, "char_count": 0, "items": [], "merged_text": ""
}
}

ocr.status — “0건”이 왜 0건인가

섹션 제목: “ocr.status — “0건”이 왜 0건인가”

ok 이미지에서 글자 뽑음(count > 0) · no_text 이미지는 돌았으나 글자 0 · no_image OCR 할 이미지 첨부 없음 · engine_off OCR 엔진이 꺼져 있음(운용자가 /monitoring 에서 켜야 합니다). 셋 중 무엇인지 이 한 필드로 구분합니다. ocr.items[] 의 각 항목은 {file_name, text, char_count, avg_conf}, ocr.merged_text 는 첨부별 머리말을 달아 이어붙인 소비용 글자입니다.

첨부 파일 — .attachments(id) · .attachment(id, "파일명")

섹션 제목: “첨부 파일 — .attachments(id) · .attachment(id, "파일명")”

수집 1건에 딸린 소독(CDR)된 첨부를, 그 레코드와 묶인 맥락으로 다룹니다. 파일시스템을 통째로 여는 것이 아니라 (스키마 · 수집ID) 스코프를 지납니다. 글자만 필요하면 대개 여기까지 안 와도 됩니다 — fetch() 의 ocr.merged_text 에 이미 첨부에서 뽑은 글자가 실려 옵니다. 원본 파일(표 있는 PDF · 엑셀 등)을 직접 다룰 때만 아래를 씁니다.

SCHEMA = "<스키마명>" # schemas() 의 name
ING = 844 # 수집 건 id (= fetch 의 _ingestion_id)
# ① 이 건에 뭐가 붙었나 — 맥락(메타 + OCR 글자)
for a in Zio.ingestion(SCHEMA).attachments(ING):
print(a["file_name"], a["file_size"], a["ocr_status"])
f = Zio.ingestion(SCHEMA).attachment(ING, "invoice.pdf")
raw = f.bytes() # 소독된 본문 바이트 (그대로 파싱)
text = f.text() # OCR 글자(이미지 첨부) · 없으면 None
path = f.save() # 스킬 폴더에 'invoice.pdf' 로 저장
path = f.save("inbox/a.pdf") # 하위 경로(상대만) — 웹 탐색기 · SSH 서 그대로 보임

소독된 파일만 내려옵니다(차단 · 저장 안 된 첨부는 saved=False 이고 .bytes() 가 404). .save() 는 스킬 폴더 밖으로는 못 씁니다(상대경로만). 읽기 전용이고, 이 인스턴스의 수집 건에만 닿습니다.

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

섹션 제목: “공정 이력 · 상태값 — 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() 로 확인 — 아래는 자리표시자)

섹션 제목: “예시 (실제 스키마 · 필드명은 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) 고치십시오.

(주)지오유 · 경기 용인시 처인구 유림로154번길(유방동 673-2) 20-13

대표자 신달수·사업자등록번호 142-81-36612·통신판매업 신고번호 용인처인-0118호·개인정보 관리책임자 신달수·전자우편 shindalsoo@gmail.com·전화 1833-3623·팩스 02-6918-4006