Zio.Entity()

This page deals with tables in the PostgreSQL usr schema. You can create and drop tables, but you cannot change their column definitions — that is only possible with Zio.code. To compare against a network view, see the table in Zio.Database (Overview).

Custom Table API

You can dynamically create tables (DDL) within the usr isolation schema of PostgreSQL and perform CRUD operations (DML) with security handling (SQL Injection protection) in a Fluent API chaining style.

Method	Description
`Zio.entity(table_name)`	The entry point for Fluent API chaining 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 name already exists, it is rejected — call `.drop_table()` first if you want to delete and recreate.
`.drop_table(force=False)`	Deletes the entire table. This cannot be undone. If any rows remain, it rejects the operation and reports how many rows exist—removing an accidentally created empty table differs from wiping a populated ledger. Use `force=True` to proceed anyway. `Zio.raw("DROP TABLE …")` is blocked — that path could have left the `usr` schema.
`.create(props)`	Inserts a new row into the table (INSERT).
`.where(**kwargs)`	Specifies filter conditions. (e.g., `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 one of several columns matches, as in keyword searches—previously you had to split queries and combine them in Python. The suffixes (`__contains`, etc.) work like `.where()`. Each call creates a separate OR clause that is then combined with AND. Only `fetch()` and `count()` (read operations) support OR; applying OR to `update()` or `delete()` could affect more rows than intended, so it is disallowed. (e.g., `.where_or(title__contains=kw, body__contains=kw)`)
`.columns(*names)`	Selects only the columns you want returned by `fetch()`. If omitted, all (`SELECT *`). Fetching only needed columns saves memory and speed—heavy columns (e.g., password hashes) are not retrieved. (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 data matching the filter condition (`where`) and returns it as a `GraphResult`.

Practical Example of Custom Table Fluent CRUD

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()

There is no handle to change columns
Section titled “There is no handle to change columns”

The usr tables are either created or dropped; you cannot modify them. Calling add_column, drop_column, or rename_column raises an AttributeError that explains why it’s not possible and what should be done instead.

If you need to change a column, create a new table with the desired name using create_table, transfer the data, and then drop the old table with drop_table(force=True). The ability to freely modify columns exists only in the core code (Zio.code) — that path also moves the row values.