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.
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.
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.
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.
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
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.
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.