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()까지만 합니다.
수집데이터 Fluent CRUD API
섹션 제목: “수집데이터 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, 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_imageOCR 할 이미지 첨부 없음 ·engine_offOCR 엔진이 꺼져 있음(운용자가/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() 의 nameING = 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 글자(이미지 첨부) · 없으면 Nonepath = 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