Entity And Relation Write Guide

中文：实体与关系写入指南

Runtime entity and relation write workflow after model import.

Start With Model Definitions

Import a model pack before writing runtime data:

make dev
go run ./cmd/umctl --addr http://localhost:8080 workspace create demo '{"name":"Demo"}'
go run ./cmd/umctl --addr http://localhost:8080 umodel import demo examples/quickstart-multidomain

Write Entities

Bundled multi-domain quickstart sample:

go run ./cmd/umctl --addr http://localhost:8080 entity write demo examples/quickstart-multidomain/sample-data/entities.json

Equivalent REST endpoint:

POST /api/v1/entitystore/{workspace}/entities:write

Verify Entities

go run ./cmd/umctl --addr http://localhost:8080 query run demo ".entity with(domain='devops', name='devops.service') | limit 20"

Keyword search:

go run ./cmd/umctl --addr http://localhost:8080 query run demo ".entity with(domain='devops', name='devops.service', query='checkout') | project __entity_id__,display_name | limit 20"

Write Relations

go run ./cmd/umctl --addr http://localhost:8080 topo write demo examples/quickstart-multidomain/sample-data/relations.json

Equivalent REST endpoint:

POST /api/v1/entitystore/{workspace}/relations:write

Verify Topology

go run ./cmd/umctl --addr http://localhost:8080 query run demo ".topo | graph-call getDirectRelations([(:\"devops@devops.service\" {__entity_id__: '10000000000000000000000000000101'})]) | limit 20"

Expire Records

Expire entities:

go run ./cmd/umctl --addr http://localhost:8080 entity expire demo 10000000000000000000000000000101 "retired from sample"

Expire relations:

go run ./cmd/umctl --addr http://localhost:8080 topo expire demo <relation-id> "retired from sample"

Rules

• Keep sample data deterministic.
• Use IDs that are stable across docs, tests, and screenshots.
• Write model definitions first, runtime data second.
• Read runtime data only through Query Service.
• Prefer small examples that show search, direct relation lookup, and relation types clearly.