Skip to content

Zio.code()

Only one of your entry points has a lock on the table.
To compare it with the net, refer to the table in Zio.Database (개요).

Basic Code reads and writes tables managed by people in the skill. The {{$테이블.필드}} that you feed into a prompt contains data that looks like what is seen on screen.

Why this entry point is necessary. Basic code stores JSONB in the data column of the code_rows table. Without this entry point, the skill would have to know that storage structure and write SQL with Zio.raw()—a raw access to the engine’s internal structure—and if the storage method changes, all instances of the skill break together.

The engine does not know what tables exist. Construction uses 공종, fashion uses 브랜드, food service uses 점포. Both table names and column names are passed only as arguments. Do not put code that assumes a particular table into the SDK or engine.

Method Description
Zio.code(table_name) Specifies one Basic Code table. Use the table ID (English name) from the Basic Code screen. Specifying a non‑existent table raises a LookupError—it does not silently return an empty list for typos.
.where(**kwargs) Filters rows. Use comparison suffixes as is. (e.g., use_yn="Y", client_name__startswith="GS")
.where_or(**kwargs) Groups multiple conditions on the same table with OR (different from other .where() which are AND). Use when any one of several columns should match—previously you had to split queries and combine them in Python. Suffixes (__contains, etc.) work like .where(). Calling it multiple times creates separate OR groups that are combined with AND. It only applies to read operations (fetch()·count())—applying OR to update()·delete() can affect more rows than intended, so it is disallowed. (e.g., .where_or(client_name__contains=kw, aliases__contains=kw))
Zio.code.list() First checks what tables exist. Returns [{table_name, title, description, field_count}]—no rows are returned. Don’t repeatedly try Zio.code("guess") with an unknown name; choose from here.
.fetch() Retrieves a list of rows as GraphResult. Each row is a flat dict where the column names are keys unchanged. The row identifier _id is included.
.info() Retrieves a dict describing the table itself: {table_name, title, description, fields:[{name, label, type}]}. If no title was given, title defaults to the table name.
.create(props) Inserts one row. Duplicates are not checked—what constitutes a duplicate varies by table, so check with .where(...).fetch() before inserting.
.update(props) Updates rows that match the condition. Only the specified columns are overwritten; others remain unchanged. Raises ValueError if no condition is given.
.delete() Deletes rows that match the condition and returns the deleted rows—so you know what was removed. Raises ValueError if no condition is given.
.create_table(columns, title, description) Creates a table. columns=[{name, label, type}]. The created table is managed by people in the screen afterward—the skill does not lock it. When first created there are no locks (just like a table made in the screen).
.add_column(column) Adds one column to the end. {name, label, type}. Existing rows will have that column empty—values are not inserted automatically.
.drop_column(column_name) Removes a column from the declaration. Values already stored in rows are not deleted—if you add a column with the same name again it reappears. The value disappears from the screen but is still returned by .fetch() (unless filtered out). Trying to use a dropped column raises ValueError. You cannot drop the last remaining column.
.rename_column(old_name, new_name) Renames a column and moves the values in rows accordingly. If you only change the declaration, the old key remains with its value; it is neither deleted nor visible.
.drop_table(force=False) Deletes the table and all its rows. If other parts of the system reference this table, the operation is refused and the dependents are reported. To force deletion even when referenced, use force=True. Returns {table_name, deleted_rows, dependencies}.
.resolve(value, name, alias=None) Checks whether the table knows a notation for the given value. If it does, returns the canonical name; otherwise returns None. It only accepts an exact match—case, whitespace, and punctuation are ignored (GS 25 = GS25).
.suggest(value, name, alias=None, limit=3) Picks similar canonical names when .resolve() fails. These are candidate options for the user to confirm. The input may include aliases; only the canonical name is returned.
.name_conflicts(name, alias=None) Reports aliases that belong to more than one canonical name: [{"alias": "편의점", "claimed_by": ["GS25", "CVSNET"]}]. An empty list means no conflicts.

There is a table that blocks — PermissionError

Section titled “There is a table that blocks — PermissionError”

Locks are written on the table itself. The screen (Basic Code management) and the SDK see the same values—if they differ, there can be a gap where “the screen cannot do it but the skill can.” |

Field What it locks
is_data_user_editable Entire rows. If off, only read operations (fetch·count·info) are allowed.
allowed_actions Which actions are permitted. If set to ["update"], values can be changed but the row cannot grow or be deleted. Empty means all actions are allowed.
is_schema_user_editable Column structure. Affects add_column·drop_column·rename_column·drop_table.

When blocked, a sentence explaining why and what is possible appears. Read that sentence and stop—creating a new table with the same name or retrying the same call does not solve it. Locks are removed by people in the screen.

PermissionError: 'llm_callers' 표는 삭제를 허용하지 않습니다. 이 표에 허용된 것: 수정.
PermissionError: 'llms' 표는 칸 구성이 잠겨 있습니다(칸 추가 거부).
시스템이 칸 이름으로 읽는 표라, 바뀌면 조회가 조용히 어긋납니다.
행은 잠금과 별개입니다 — 값만 고치려면 create·update·delete 를 쓰십시오.

Locked tables are those that the engine reads by column names: llms, llm_callers, system_configs, collectors, common_code. Tables created by a manager are not locked—whether made in the screen or set up by a skill, they behave the same.

Which column is the canonical name and which is an alias is known only to the person who created the table. Construction uses 공종명, fashion uses 브랜드명, and some tables have no alias columns at all. If the SDK predefines a name like aliases, that instantly becomes industry‑specific, and for tables without an alias column it silently does nothing.

Zio.code("client").resolve("GS편의점", name="client_name", alias="aliases")
# → 'GS25' 별칭에 100% 일치
Zio.code("client").resolve("하나비전", name="client_name", alias="aliases")
# → None 모르는 표기다. 되물을 차례
Zio.code("client").suggest("하나비전", name="client_name", alias="aliases")
# → ['한화비전', '하나시스'] 사람에게 보여줄 후보
# 별칭 칸이 없는 표는 alias 를 안 주면 됩니다 — 정식명만 재료가 됩니다
Zio.code("product").suggest("삼성전자", name="product_name")

There is a reason why .resolve() and .suggest() are not combined into one function. Mixing “known” and “similar” can cause you to ask about something you didn’t need to or skip something that should be asked. If .resolve() gives an answer, proceed; if it does not, use .suggest() to get candidates—this two‑step flow is standard.

It’s better not to touch a dictionary when it’s wrong. When the same alias belongs to two canonical names (e.g., “편의점” for two convenience store companies), which one gets chosen is determined by the order in the table, and no one can later find out why that happened. .resolve()·.suggest() never use such an alias, so it won’t attach it incorrectly, but to know that the table is wrong you should call .name_conflicts(). It does not tell you what to do—skipping the entire table is a domain decision.

Use .info()’s title in sentences shown to people

Section titled “Use .info()’s title in sentences shown to people”

Reading a table and reading about a table are different. .fetch() gives you a list of customers, while .info() tells you that the table is “major customers.”

# 나쁨 — 사람은 'client' 가 뭔지 모른다
질문 = f"기초코드에 없는 값입니다: '{값}'"
# 나쁨 — 담당자가 화면에서 표 이름을 바꿔도 문장은 안 따라온다
질문 = f"주요거래처에 없는 값입니다: '{값}'"
# 좋음
title = Zio.code(code_table).info()["title"]
질문 = f"{title}에 없는 값입니다: '{값}'. 어느 쪽입니까?"

The Korean name of a table is what the domain manager attaches on the screen. If you write it in the skill, from that moment the same name lives in both places, and the manager will not know why the screen no longer shows the name they changed.

Reject update·delete without a condition. If data disappears all at once there is no way to recover it. Always use .where().

Reject columns that are not declared. The screen only draws declared columns, so if you accept them they will be stored but never visible later. Error messages include the columns that can be used on that table.

The owner of Basic Code is the domain manager. A skill adds a line to a table set up by people in the screen; it does not write into its own storage. If a skill needs to create or delete tables, use Zio.entity()—that’s for data with changing state and that disappears (task queues, processing history).

Practical Example of Basic Code Usage — Normalizing Notation

Section titled “Practical Example of Basic Code Usage — Normalizing Notation”

Even if the model picks “GS THE FRESH,” you might want to store it in the graph as “GS더프레쉬.” Where each notation goes is written only in Basic Code; the engine does not know those rules.

from zio_ontology import Zio, zio_skill
@zio_skill
def normalize_names(code_table: str, code_field: str,
alias_field: str, node_label: str,
dry_run: bool = True):
"""기초코드의 별칭 칼럼을 읽어 갈라진 노드 표기를 정식 표기로 모은다.
표 이름·칼럼 이름을 전부 인자로 받으므로 어느 산업에서든 그대로 쓴다.
"""
table = Zio.code(code_table)
# 1) 그래프의 실제 표기를 하나씩 표에 물어본다.
# 사전을 손으로 짜지 않는다 — 별칭 충돌(같은 별칭이 두 정식명에 걸린 것)을
# 거르는 것도 표기 열쇠를 만드는 것도 .resolve() 안에 들어 있다.
planned, unknown = [], []
for node in Zio.node(node_label).fetch().data:
name = node.get(code_field)
if not name:
continue
canon = table.resolve(name, name=code_field, alias=alias_field)
if canon is None:
# 표에 없는 새 값 — 임의로 가까운 이름에 붙이지 않는다.
# 닮은 후보는 사람에게 보여줄 것이지, 코드가 고를 것이 아니다.
unknown.append({
"value": name,
"options": table.suggest(name, name=code_field, alias=alias_field),
})
elif canon != name:
planned.append((name, canon))
# 2) 확인하고 실행한다
if dry_run:
return {"planned": planned, "unknown": unknown, "applied": False}
for name, canon in planned:
Zio.node(node_label).where(**{code_field: name}).consolidate_into(**{code_field: canon})
return {"planned": planned, "unknown": unknown, "applied": True}

Note that dry_run defaults to True. .consolidate_into() cannot be undone, so from the skill side it’s safest to first preview what will merge and then execute in two steps.

The options stored in unknown become buttons on the confirmation screen. It is fine if there are no candidates—then a person can write it directly, and putting that answer into the alias column means .resolve() will find it next time. Confirmation ends after one round.

(주)지오유 · 경기 용인시 처인구 유림로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