Scan and aggregate the Neo4j knowledge graph (ABox). You cannot create containers (nodes/attributes) here—that is determined by the ontology (TBox). What each of your four entry points can do is listed side-by-side in the table in Zio.Database (Overview).
You can query graph data using method chaining on the built‑in Graph object.
Method
Description
Sample
.schema()
The cell definition of this label. {label, defined_in:[{twin_id, twin_title, display_property, properties[...]}]}. A name may exist in multiple ontologies, so it also tells you which ontology it came from — if the cells differ, that’s what you’ll see.
Zio.node("Inquiry").schema()
.available_edges()
The outgoing and incoming relationships of this label. {out:[{rel, to}], in:[{rel, from}]}. The names you put into .out(rel, to=...) are here — don’t guess. Relationship names are created by the ontology author; HAS_PRIORITY and hasSentiment can coexist in one ontology.
Zio.node("Inquiry").available_edges()
Zio.node.labels()
The labels that currently exist on the graph and their counts. [{label, count}]. Zio.ontology.list() is “what you drew”, this is “what’s actually there” — seeing the mismatch is what this value is useful for.
Zio.node.labels()
Zio.node(label)
Specify the label of the node where exploration starts.
Zio.node("Inquiry")
.where(**kwargs)
Filter on properties of the currently focused node. Supports comparison suffixes (see Comparison Suffix table below). Multiple arguments are combined with AND.
.where(status="OPEN", yyyymmdd__gte="2026-03-01")
.where_or(**kwargs)
Combine multiple conditions with OR (different from other wheres which are AND). Use when any one of several fields matches — previously you had to split queries and combine in Python. Suffixes are the same as .where(). You can OR up to 1‑hop nodes beyond relationships — first declare a hop with alias and mix with alias.property keys. The alias must be a declared hop (otherwise it fails — you cannot guess the relationship name), and keys without dots refer to the currently focused node as in .where(). Return nodes are chosen with .select() (if omitted, the last hop is returned). Search OR uses optional_out — if the hop is required, rows without that relationship are dropped. Each call creates a separate OR block which then ANDs together.
Follow a relationship forward (→) one hop. to is the label of the destination node, alias is the name you attach there (defaults to something derived from the label), from_ is where you branch from (defaults to the previous node).
.out("CREATED_BY", to="Customer")
.in_(rel_type, to, alias, from_)
Follow a relationship backward (←) one hop. The other side points at me. Arguments are the same as .out().
.in_("DUE_ON", to="Order")
.with_relations(only=None)
Attach all 1‑hop relationships to the node in one go. Each result row is the node’s properties plus an additional relations field, e.g. {"Priority": [...], "Category": [...]}. If no argument is given it attaches everything from .available_edges()["out"]; you can also filter by a list of target labels or a dict like {"rel":…, "to":…}. See the “relationships in one go” section below.
.with_relations(["Priority", "Category"])
.select(**kwargs)
Project arbitrary properties with aliases (Projection). In multi‑join queries you can also fetch intermediate node or relationship attributes. The left side is the alias you give, the right side is name.property. If no name is given it defaults to something derived from the label – see “names attached to nodes” below.
Specify result ordering. Prefix a field with - for descending. Multiple fields are prioritized in order. When used together with .select() you sort by the aliases you attached; you cannot sort on values that aren’t returned. If no .select() is given, it sorts on the node’s property names directly. Only one column is available from .code() or .entity().
.order_by("-work_date", "work_name")
.group_by(**fields)
Specify what to group by. Same shape as .select(), and the grouping key is preserved in the result. Must be used with .aggregate() — if you only give .group_by() it will not group and will return the last node unchanged (a console warning appears). If you want only specific fields, use .select().
.group_by(status="work.status")
.aggregate(**specs)
Specify what to count per group. Only Count, Collect, First, and Sum are allowed. You can give a where clause for each aggregation to count only those that match the condition.
.aggregate(works=Count("work", distinct=True))
.count(of=None, distinct=False)
Return one count (a number). It does not fetch a list and then call len(). Grouped counts are obtained with .group_by() + .aggregate().
Zio.node("Work").where(status="완료").count()
.limit(val)
Explicitly limit the maximum number of rows returned.
.limit(10000)
.create(props)
Create a new node with the specified properties (CREATE). The display name (_display) is automatically calculated by the SDK.
Create if missing, otherwise match. What counts as “the same” is determined by .where() (the equality condition). on_create runs only when creating; on_match runs only when a matching node already exists. This differs from first querying and then calling .create() because another operation could create the same node in between, resulting in two nodes.
Merge nodes that match the condition into one other node of the same label. All relationships are moved to the target node and the source node disappears. Use this when you want to gather split nodes into a single one — using .update() to rename would create two nodes with the same name, and relationships wouldn’t follow.
Zio.node('Client').where(client_name='GS THE FRESH').consolidate_into(client_name='GS더프레쉬')
.optional_out(...) / .optional_in(...)
Same hop but the row remains even if that relationship does not exist (OPTIONAL MATCH). Arguments are the same as .out(). Caution: filtering a node after an optional hop with .where() is not a filter — because of OPTIONAL MATCH, preceding rows are not filtered and the node’s properties become null (the same result as no condition). To actually filter on that relationship, use .out()/.in_() (required match) or the helper below. (If you put a where after an optional hop, a console warning appears.)
Required‑match hop + target filter in one line. Equivalent to .out(rel, to).where(target_filters), but you don’t need to move the cursor back; required match means rows that do not satisfy the condition are properly filtered out (avoiding the optional trap). Filter suffixes are the same as .where().
Based on the chain built above, generate and execute a safe Cypher query and return a GraphResult object.
res = Zio.node("Inquiry").fetch()
.to_cypher()
Return the assembled Cypher and parameters as a string. Does not execute. Use it to see how the chain was translated for debugging — even if you don’t have Neo4j tools in your SSH environment. It only shows the translation of the chain (not a schema dump), and raw input cannot be inserted here.
This was the place where you would pass Cypher verbatim. In skill‑running environments there’s no engine source or DB connection, and the SDK alone is a gate; it doesn’t go through that gate. Calling it tells you what to switch to in words.
Use the functions above instead — they follow graph changes automatically, but hand‑written Cypher will silently drift off course.
Labels, relationship names, and property names are placeholders that point to schema, while the right side of .where() is a value to filter on. These two are different — values safely become parameters, but names go straight into the query text. Therefore never insert user input or LLM‑generated strings directly into name placeholders.
# 위험 — 바깥에서 온 값을 라벨·이름 자리에
label = user_input # 예: LLM 이 고른 라벨
Zio.node(label).where(**{user_key: 1}) # label·user_key 가 그대로 질의에 박힌다
# 안전 — 이름은 내가 아는 것으로 고정, 바깥 값은 '값 자리'로
Zio.node("Inquiry").where(subject__contains=user_input) # user_input 은 파라미터로 나간다
If an odd string appears in a name placeholder, the SDK will block and explain why (labels/relationships not matching English letters, digits, underscore; invalid property names). To pick a consistent label, use Zio.node.labels() to get the actual list of existing names and choose from there.
Use this when you want to see everything attached to that inquiry. .out() follows one relationship at a time, so if there are nine relationships you’d have to ask nine times for one inquiry. .with_relations() folds them into a single query.
The numbers are the actual counts measured in the helpdesk instance. Inside CALL (n) { OPTIONAL MATCH … RETURN collect(…) } the number of rows does not multiply by the number of relationships — missing relationships return an empty list.
Only one hop. Relationship chains are not followed. Increasing depth turns a single‑node graph into thousands of rows. If you need two hops, use .out().
You can’t mix with “select and gather” style. Using .select(), .group_by(), .aggregate(), or .out() together changes what constitutes one row, so it’s blocked. Gather after receiving the result in Python.
If names clash, relationships are also attached. If two paths go to the same label, the cell name becomes Priority instead of HAS_PRIORITY:Priority — this prevents one from overriding the other.
Append __suffix to a key in .where() to change the comparison method. Without a suffix it’s =. It works the same for ontology (Cypher) and custom tables (SQL).
All names come from your design; the SDK only supplies suffixes.
The title, qty shown below are just examples, not SDK‑defined names. Node names and field names are written exactly as they appear in the industry‑specific ontology design. It’s the same place you’d use when writing SQL.
SELECT * FROM Worklog WHERE subject LIKE '%GS25%'
└ 노드 ┘ └ 필드 ┘ └ 비교 ┘
Therefore if industries differ, the names will be entirely different.
Only the word after __ is understood by the SDK (see table below). Without it it’s =. If you give multiple conditions they all must be satisfied (AND). The engine never sees your field name. If you use a name that isn’t in the design, the query returns empty or errors — typos will surface.
Suffix
Meaning
Example
__gt / __gte
Greater than / greater or equal
.where(qty__gte=100)
__lt / __lte
Less than / less or equal
.where(yyyymmdd__lte="2026-03-31")
__ne
Not equal
.where(status__ne="CLOSED")
__in
Value is in a list. Must be an array; an empty list matches nothing
.where(client_name__in=["GS25", "보나캠프"])
__startswith / __endswith
Starts with / ends with
.where(email__endswith="@zio.run")
__contains
Contains
.where(title__contains="장애")
__contains_all / __contains_any
Value is a list. All contained / any contained. Used when you split the search string by spaces — you can’t apply two __contains to the same field. An empty list matches nothing
.where(work_name__contains_all=["GS25", "포스"])
__isnull
True means no value, false means has a value
.where(closed_at__isnull=True)
Unknown suffixes return an error
A typo like __gtee will produce an error and list usable suffixes. Previously the condition would be completely discarded and all rows would be returned — no error was thrown. If a property name itself contains __, it is interpreted as a suffix, so rename it.
There are four countable functions. You do not supply function names as strings — writing something like aggregate(cnt="count(*)") merely shortens Cypher; it’s not wrapped by the SDK.
Aggregate
What
Example
Count(of, distinct, where)
Count. If of is omitted it defaults to count(*).
Count("n", distinct=True)
Collect(of, distinct)
Gather values into a list
Collect("client.client_name", distinct=True)
First(of, distinct)
The first of the gathered ones. Useful when there’s only one department or position but the path causes multiple hits.
Aggregations that receive a where count only those that match the condition. The syntax is the same as .where() — comparison suffixes are used unchanged.
After aggregation you’re left with only the grouping key and the aggregate result. Original node properties have already folded away, so sorting on them will fail.
When writing text for an AI, you can place {{#node.property}} or {{$table.field}}. Just before sending to the model it is replaced with the actual list.
Where you can write
What
Domain · role prompt
Each row of the system_prompt table in the basic code
Data source description
The description field in pipeline builder → collection settings
Field instruction · output format
Pipeline schema → AI Prompt · Output Format
Agent node prompt
Agent builder → AI model call node
Future prompt fields will work the same. Replacement happens only once at the model‑call gate, so new screens don’t need separate handling.
Notation
What comes in
{{$job_type.type_name}}
The list of values preset in basic code. If a role=prompt field exists it also includes descriptions
{{#Client.client_name}}
List of nodes already stored in the ontology
{{#Client.client_name?limit=50}}
Display limit. Defaults to 200 if omitted; logs if truncated
{{$job_type.type_name?use=Y}}
Filter. Only rows that match
{{$job_type.type_name?use=Y&grade=A,B}}
Multiple filters. Connect with &; comma means OR among the values. Do not wrap an extra pair of braces — writing {{{$…}}} leaves the outer braces as literal text
Output Format 에 이렇게 적으면
{
"client": "거래처 명칭. 아래에 같은 뜻이 있으면 그 이름을 그대로 쓰십시오: {{#Client.client_name}}",
"work_type": "다음 중 하나만: {{$job_type.type_name}}. 다른 값을 만들지 마십시오"
}
모델에게는 이렇게 갑니다
{
"client": "거래처 명칭. 아래에 같은 뜻이 있으면 그 이름을 그대로 쓰십시오: GS25, 한화비전, 쿠팡, ...",
"work_type": "다음 중 하나만: 설치, 교체, 철수, 점검, ... 다른 값을 만들지 마십시오"
}
Write instructions directly
# (stored) and $ (preset) are opposite instructions — one means “create if missing”, the other means “don’t go outside the list”. Write how you want it next to the list. The system will mix them.
If a reference can’t be found or the result is zero, {{...}} stays as literal text. Removing the value leaves a fragment like “one of these only: ” which confuses the model.
Names attached to nodes (alias)
.select(), .order_by(), aggregates, and from_ refer to each other using names. If omitted they’re derived from the label — Zio.node("Worklog") becomes worklog, .out("HAS_WORK", to="Work") becomes work.
Default name: first letter of the label in lowercase. Work → work, WorkType → workType.
If you pass through the same label twice:work, work2 with a trailing number. If it’s confusing, specify alias= explicitly.
Relationship attributes are read as <targetname>_rel, e.g. work_rel.qty.
Naming is like SQL/Cypher — it’s the “FROM” side. (FROM worklog wl, (w:Work))
Zio.node("Worklog") # 이름: worklog
.out("HAS_WORK",to="Work") # 이름: work
.optional_out("FOR_CLIENT",to="Client") # work 에서 이어짐
If branches split, specify with from_ where you branch. If omitted it continues from the node just reached — if you drop from_ above the author, you’ll go from the customer to nothing. Giving a non‑existent name stops and tells you what names are available.
Names come from labels, so inserting an intermediate hop doesn’t shift subsequent names. Earlier versions used temporary names like t0, t1 that pushed everything else.
Rules for node absorption integration (.consolidate_into())
Target must be the same label. If you start with Zio.node("Client"), the target is also Client. Cross‑label consolidation isn’t supported.
Attributes are taken by the target node. If both sides have the same attribute, the target’s value remains; attributes missing on the target come from the absorbed side.
Relationships are all moved. Duplicate relationships of the same type to the same target are merged into one.
If no target exists, it simply renames. Absorbing nothing is equivalent to .update(). The result is always “one node with that name”.
If no matching nodes exist, nothing happens. Running again yields the same result (idempotent).
It cannot be undone. Absorbed nodes disappear. Verify what will merge by calling .fetch() first.
The return value is the surviving target node. If nothing was merged, you get an empty result — check if .data is empty to see whether a change occurred.
Automatic calculation of display name (_display)
Every node has a _display property that shows in the graph UI. Skill writers do not need to set this manually. When .create() or .update() is called, the SDK reads the ontology’s defined Display Property and automatically calculates and stores it. It shares the same calculator (graphdb/display.py) as the ontology writer (writer.py), so results are always consistent.
Single property name: If the ontology defines verdict, that value becomes the display name. → _display = "위험"
Brace template:{[sequence}차]{by} is replaced with attribute values. → _display = "[1차]mail.example.com"
Missing value becomes an empty string. If no Display Property exists, _display is untouched.
Calculation failures do not raise exceptions. The SDK is designed so that a display name issue does not halt the skill’s core storage operation.
These rules come from the status=live ontology. Inside the API container the SDK reads PostgreSQL directly; skills running in the Zero‑Trust sandbox fetch rules via GET /api/sdk/ontology/display-rules. Only { node_name: Display Property } is exported, not the whole ontology. It caches once per process, so after changing the ontology you must restart the skill to apply new rules.
Ontologies are not retroactively applied. Changing a Display Property does not alter _display of already stored nodes; only newly created or updated nodes use the new rule. The ontology is a forward‑looking reference, not a rewrite tool for past data.