Semogram Docs
OntologyMaterialize facts

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

IdentifierExampleMeaning
Class IRIhttps://example.com/operations#OrderThe type declared in the model
Entity IDhttps://example.com/orders/1One particular order
Source namespaceerp-ordersThe source's identity scope
Source keyorder_idThe record's key field
Source IDO-001The 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:

Source 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's invalidRecords setting 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.