Entity identities and relationships
Declare entity IDs in mappings and keep the source records behind each entity
An entity ID identifies one thing. A class IRI identifies its type. A source identity identifies the record that described it. Preserve all three when mapping data so evidence and queries can connect the same order across systems.
Example names
| Identifier | Example | Meaning |
|---|---|---|
| Class IRI | https://example.com/operations#Order | The type declared in the model |
| Entity ID | https://example.com/orders/1 | One particular order |
| Source namespace | erp-orders | The source's identity scope |
| Source key | order_id | The record's key field |
| Source ID | O-001 | The key value from that system |
Choose stable entity IDs, not row offsets or a newly generated ID on every run. A source key is provider-scoped; identical-looking IDs from two systems do not automatically prove that they refer to the same entity.
Map customers and their orders
You need a Semogram account, pipeline authoring access, a compiled model containing Order, Customer and placedBy, source rows with entity_id, customer_entity_id, customer_name, and a fact-store endpoint. The complete operations model defines these terms. Use a test row:
{"entity_id":"https://example.com/orders/1","customer_entity_id":"https://example.com/customers/acme","customer_name":"Acme"}In an Ontology mapping node, add two entity rules and a relationship rule. These are mapping entries inside the node's complete configuration:
Map Order ID from {entity_id} and Customer ID from {customer_entity_id}. Map Customer.customerName from customer_name using its full IRI. Add placedBy with subject {entity_id} and object {customer_entity_id}. Review both entity rules and relationship endpoints before materializing.
{
"entities": [
{
"class": "https://example.com/operations#Order",
"id": {
"template": "{entity_id}"
}
},
{
"class": "https://example.com/operations#Customer",
"id": {
"template": "{customer_entity_id}"
},
"properties": {
"https://example.com/operations#customerName": {
"from": "customer_name",
"as": "string"
}
}
}
],
"relationships": [
{
"predicate": "https://example.com/operations#placedBy",
"subject": {
"template": "{entity_id}"
},
"object": {
"template": "{customer_entity_id}"
}
}
]
}Preserve source identity entries with namespace, key and sourceId for each entity when the rows provide them. Verify the stored Order→Customer link points to the intended customer ID; a relationship label in the model graph is not an instance link.
Matching entities across sources
Identity is declared, not inferred. Two sources describe the same entity when their mappings produce the same entity ID. For example, both a supplier feed and a filings feed can build https://example.com/suppliers/{duns} from the DUNS number each carries. Materialization then updates one entity, keeps a source identity for each record that described it, and applies the materializer's conflict policy when the sources disagree on a property value.
Two guards keep declared identity honest:
- An ID already used by another class is rejected.
- A source identity that maps to two different entity IDs raises an
ontology_identity_conflict. The node'sinvalidRecordssetting decides whether the record is quarantined or the fact set is rejected.
If two sources share no key, they remain separate entities. Choose a shared business key in both mappings rather than relying on names matching.