Create a relation between entities

Entities represent objects; relations represent directed connections between them. In this lesson, add iot_sensor, connect it to the existing iot_machine, create iot_reads_from, and load an actual relation row with a Batch pipeline.

Prerequisites

• The populated iot_machine entity from the previous lesson
• Identity key id on iot_machine

Both endpoint entities must have identity keys. The relation dialog blocks creation when either endpoint has no identity key.

Prepare the iot_sensor entity and row

1. Open the practice collection's Builder under Ontology → Modeling.
2. Select Add Entity and enter:

3. Add these attributes.

4. Set both Identity Keys and Display Column to id, then select Create Entity.
5. Download iot_sensor.csv, or save the following content with that filename.

id,machine_id,sensor_type
sensor_001,machine_001,temperature

6. Select the saved IoT sensor node and add the CSV under Data → Upload.
7. Confirm row sensor_001 under Data.

Decide the direction first

Read a relation as Source Entity → Relation → Target Entity:

flowchart LR
    accTitle: Sensor-to-machine relation and relation-row loading
    accDescr: iot_sensor points to iot_machine through iot_reads_from while the sensor_machine_links dataset passes through mapping Code to create relation rows.
    sensor[iot_sensor<br/>source entity] -->|iot_reads_from| machine[iot_machine<br/>target entity]
    dataset[(sensor_machine_links)] --> mapper[map_sensor_machine_links]
    mapper -. load relation rows .-> relation{iot_reads_from}
    relation -. source .-> sensor
    relation -. target .-> machine

This means that a sensor is installed on and collects readings from a machine. Reversing the direction changes how graph queries and neighbor expansion interpret the connection.

Create the relation in Modeling

1. Open Ontology → Modeling.
2. Select the course collection and open Builder.
3. Drag the right connection handle of iot_sensor to iot_machine.
4. In Create Relation, confirm Source Entity iot_sensor and Target Entity iot_machine.
5. Enter the following details.

Names must be 1–63 characters, start with a lowercase letter, and contain only lowercase letters, digits, and underscores. A name such as IOT_READS_FROM is rejected.

Add a relation attribute

Under Attributes, add a value that belongs to the connection itself:

When at least one attribute is added, the system also manages the structural id column. Do not recreate id or the source and target reference columns as user attributes.

6. Select Create Relation.

Inspect the saved relation

Select the edge labeled Sensor reads from machine. The inspector shows:

• Overview, Attributes, Data, and History tabs
• Read-only Name, Source Entity, and Target Entity fields
• Source iot_sensor and target iot_machine
• Attribute installed_at

An empty Data tab is expected immediately after creation. Defining a relation does not load relation rows.

Understand the pipeline output columns

Rows for iot_reads_from require these columns:

For different endpoint entities, reference columns use <entity name>_<identity key>. A self-reference uses source_<entity name>_<identity key> and target_<entity name>_<identity key> to avoid a collision.

Load relation rows with a pipeline

Create a table dataset named sensor_machine_links through Add item → Dataset → Table. Define all four columns as Text, then download and upload sensor_machine_links.csv. You can also save the content below with that filename. Code will convert installed_at to Timestamp.

id,iot_sensor_id,iot_machine_id,installed_at
sensor_001__machine_001,sensor_001,machine_001,2026-07-01T09:00:00

Build the sensor_machine_links → map_sensor_machine_links → iot_reads_from flow shown in the earlier diagram.

1. Create a Batch pipeline in the same collection under Data → Pipelines.
2. Add Quick add → Code → Python and name it map_sensor_machine_links.
3. Enter this code.

import polars as pl

def run(sensor_machine_links, *, options=None, contexts=None):
    output = sensor_machine_links.with_columns(
        pl.col("id").cast(pl.Utf8),
        pl.col("iot_sensor_id").cast(pl.Utf8),
        pl.col("iot_machine_id").cast(pl.Utf8),
        pl.col("installed_at").str.to_datetime(strict=False),
    )
    return {"iot_reads_from": output}

4. Connect sensor_machine_links → map_sensor_machine_links → Sensor reads from machine.
5. In Code Options, confirm input key sensor_machine_links and output key iot_reads_from.
6. Confirm relation write mode Upsert.
7. Save as load_iot_reads_from and select Run now.
8. Confirm top-level status Ready and latest run Success.

Upsert updates a row when the same id arrives again. A different id creates another relation row even when Source and Target are identical, so generate deterministic IDs for repeatable runs.

Verify the loaded data

1. Confirm that the pipeline run completed in run history.
2. Return to Ontology → Modeling and select iot_reads_from.
3. Refresh Data and inspect the row and four columns.
4. Graph synchronization runs in the background; if the edge is not immediately visible in Graph Explorer, check again shortly.

Self-check

• The direction is iot_sensor → iot_machine.
• The system name is lowercase iot_reads_from.
• iot_sensor has row sensor_001.
• The relation has the installed_at attribute.
• The pipeline output includes id and both endpoint reference columns.
• Rows appear under the relation's Data tab after the run.

Next lesson

Next, inspect the loaded entities and relation in Graph Explorer and run Cypher using the actual lowercase names.