Zio.entity()
This section deals with tables in the PostgreSQL usr schema. You can create and drop tables, but you cannot change their column definitions—only Zio.code supports that. For a comparison of tables, see Zio.Database (overview).
Custom Table API
Section titled “Custom Table API”You can dynamically create tables (DDL) in the usr isolation schema of PostgreSQL and perform CRUD operations (DML) with security handling (SQL Injection defense) using a Fluent API chaining style.
| Method | Description |
|---|---|
Zio.entity(table_name) |
The entry point for a Fluent API chain to manipulate PostgreSQL tables and views. |
.create_table(columns, display_name, description) |
Accepts a list of column information (name, type, pk, nullable, etc.) and pre-creates the table along with system metadata. If a table with the same name already exists, it is rejected — to delete and recreate, call .drop_table() first. |
.drop_table(force=False) |
Deletes the entire table. It cannot be undone. If any rows remain, it is rejected and reports how many rows exist — clearing an incorrectly created empty table differs from deleting a populated ledger. To force deletion, set force=True. Zio.raw("DROP TABLE …") is blocked — that path could have left the usr schema. |
.add_column(column) |
Adds a single column at the end. {name, type, nullable, default, desc} – the same format as a line in create_table. Existing rows will have this new column empty. Primary keys cannot be added later; if nullable: False, a default must be provided (to fill existing rows). (Example: Zio.entity("teacher").add_column({"name": "memo", "type": "Text"})) |
.rename_column(old_name, new_name) |
Renames a column. All values are moved – the column is not deleted. |
.drop_column(column_name, force=False) |
Removes a single column. Only that column’s data disappears, other columns and rows remain unchanged. It cannot be undone. If any row contains a value in that column, it is rejected and reports how many rows exist — same rule as drop_table. To force removal, set force=True. |
.create(props) |
Inserts a new data row into the table (INSERT). |
.where(**kwargs) |
Specifies filter conditions. (Example: id=1, source_file__contains="manual", etc.) |
.where_or(**kwargs) |
Groups multiple conditions on the same table with OR (different from AND used by other .where() calls). Use when any of several columns match, as was previously required to split queries and combine them in Python. The suffixes (__contains, etc.) are the same as in .where(). Each call creates a separate OR clause that is combined with AND across clauses. Only applies to fetch()·count() (read operations) – applying OR to update()·delete() could affect more rows than intended, so it is disallowed. (Example: .where_or(title__contains=kw, body__contains=kw)) |
.columns(*names) |
Selects only the specified columns for fetch(). If omitted, all (SELECT *). Reads only needed columns to save memory and speed – heavy columns (e.g., password hashes) are not fetched. (Example: Zio.entity("users").columns("user_name", "aliases").fetch()) |
.update(props) |
Updates rows that match the filter condition (where). |
.delete() |
Deletes rows that match the filter condition (where). |
.fetch() |
Retrieves rows that match the filter condition (where) as a GraphResult. |
Custom Table Fluent CRUD Practical Example
Section titled “Custom Table Fluent CRUD Practical Example”from zio_ontology import Zio
# 1. 테이블 선제 생성 (DDL)def initialize_database(): columns = [ {"name": "id", "type": "Integer", "pk": True}, {"name": "source_file", "type": "String", "nullable": True}, {"name": "content", "type": "Text", "nullable": True} ] # usr."test_manual" 테이블 생성 및 메타데이터 자동 등록 Zio.entity("test_manual").create_table(columns=columns, display_name="테스트 매뉴얼")
# 2. CRUD 시나리오 수행 (DML)def run_db_operations(): # 데이터 삽입 (Create) new_row = Zio.entity("test_manual").create({ "source_file": "manual_v1.pdf", "content": "사출성형 온도 관리 수칙..." }).data # 데이터 수정 (Update) Zio.entity("test_manual").where(source_file="manual_v1.pdf").update({ "content": "사출성형 온도 및 압력 관리 수칙..." }) # 데이터 조회 (Fetch) results = Zio.entity("test_manual").where(source_file__contains="manual").fetch().data print(results) # 데이터 삭제 (Delete) Zio.entity("test_manual").where(id=1).delete()Collecting Created Tables into a Pipeline — User‑Defined DB (usr_db)
Section titled “Collecting Created Tables into a Pipeline — User‑Defined DB (usr_db)”Tables and views built with Zio.entity() can be fed into a collection pipeline just like other collected data, undergoing structuring, scoring, and ontology flow. Among collection target types, “User‑Defined DB” (usr_db) is the path. Unlike ODBC, there is no connection information – the engine reads only from usr in read‑only mode.
- Register a connection. You can do this via the UI (Pipeline Builder → User‑Defined DB) or with SDK code by inserting a row into the base table
usr_db(example below). - Define collection schema and primary key. In Pipeline Builder, choose “Analyze schema from data source” → “Save collection schema” → specify the PK column (e.g.,
id). The schema name follows the connection name at creation time. Without a PK, the same row will accumulate on each run. - Read collected data —
Zio.ingestion("신용카드승인데이터")(using the schema name).
from zio_ontology import Zio
# 1. 연결 등록 — 기초코드 표 usr_db 에 행 하나Zio.code("usr_db").create({ "conn_name": "신용카드승인데이터", "query": "SELECT * FROM card_expense_records WHERE use_date >= '@getDate()' LIMIT 100", "use_yn": "Y",})The rules for query are that only SELECT is allowed (WITH … SELECT included). Prefixing with usr. is optional (FROM card_expense_records = usr.card_expense_records). Names starting with public., pg_…, or information_schema. are rejected. Reserved words (e.g., @getDate(), @getDateTime()) and case‑insensitive identifiers must be quoted — otherwise, a literal like 2026-10-17 is interpreted as subtraction. The amount read is determined by SELECT, so start with a LIMIT. Duplicate rows are filtered out using the collection schema’s PK, and already retrieved rows will not return again even if their content changes.
Changing columns follows the same rules as DataStudio
Section titled “Changing columns follows the same rules as DataStudio”
add_column,rename_column, anddrop_columnuse the same functions as when you edit a table in the DataStudio UI — the table, column descriptions, and registry all change at once, and any failure rolls back everything. There is no need to recreate the table or move values manually.
(주)지오유 · 경기 용인시 처인구 유림로154번길(유방동 673-2) 20-13
CEO 신달수·Business no. 142-81-36612·E-commerce no. 용인처인-0118호·Privacy officer 신달수·Email shindalsoo@gmail.com·Tel 1833-3623·Fax 02-6918-4006