Design your first entity

Create an iot_machine entity in the Modeling builder and configure its name, alias, attributes, Identity Keys, and Display Column.

10 min

An entity represents one kind of real-world object, such as a customer, product, or machine. In this lesson, you define the structure of iot_machine in the Modeling builder. You will load its data through a pipeline in the next lesson.

Prerequisite

One collection in which you can work.

From the left sidebar, select ONTOLOGY → Modeling.

Add an entity to the canvas

If the canvas has no entities, select Add Entity in the center.
To start from the left panel, select Expand (>) on the canvas edge if the panel is collapsed. Switch from the default Templates tab to Entities, then select the + button to the right of the search field.
Create Entity opens on Details. Enter the basics, then switch to Attributes; the tabs are freely selectable rather than a forced wizard.

1. Enter the name and description

Name — Enter iot_machine. Names must be 1–63 characters, start with a lowercase letter, and contain only lowercase letters, digits, and underscores. Uppercase names such as IOT_Machine are rejected.
Alias — The user-facing name. Example: CNC machine.
Description — One or two sentences describing the entity. Example: A CNC machine in the factory, identified by id.

When you open the dialog from a collection-scoped builder, the collection is already fixed and is not shown as an editable field.

2. Define attributes

On the Attributes tab, add these attributes one row at a time.

Name	Alias	Description	Data type	Nullability
`id`	Machine ID	Unique machine identifier	Text	NOT NULL
`sensor_count`	Sensor count	Number of attached sensors	Integer	NULL
`reading_count`	Reading count	Cumulative reading count	Integer	NULL
`latest_recorded_at`	Latest reading time	Time of the latest reading	Timestamp	NULL
`anomaly_count`	Anomaly count	Cumulative anomaly count	Integer	NULL
`latest_health_score`	Latest health score	Most recent health score	Double	NULL

This schema uses Text, Integer, Timestamp, and Float. The picker also offers narrower and database-native choices such as Smallint, Bigint, Double, Numeric, Boolean, and Date. Choose based on source meaning and the target storage contract; transform mismatched source columns in the loading pipeline.

New attributes are NOT NULL by default. Keep only id as NOT NULL and toggle Nullable for the other five rows in this example. Nullability is separate from identity-key selection; use the key icon in the next step to add id to Identity Keys.

3. Set Identity Keys

In the attributes table, hover over the id row and select the key icon that appears. The selected attribute is added to Identity Keys with key order 1.

You can select multiple attributes to create a composite key.
An Entity output using Upsert requires Identity Keys.

4. Set the Display Column

Choose the attribute that labels graph nodes under Display Column. Select id for this example. Display Column is separate from Identity Keys and does not satisfy the identity-key requirement.

5. Create and check the inspector

Select Create Entity at the bottom of the dialog. Select the saved entity and confirm these tabs in the inspector:

Overview — Basic information such as name, alias, and description
Attributes — Attributes, Identity Keys, and Display Column
Data — Loaded entity instances
History — Change history

The Data tab should initially show an empty-state message asking you to run a pipeline that writes data to this resource.

After creation, Name is read-only. If the system name is wrong, delete the empty entity and create it again with the correct lowercase name.

Self-check

The entity is saved in the intended collection.
Name, Alias, and Description are filled in.
Identity Keys and Display Column are set.
The inspector shows Overview, Attributes, Data, and History.

Next lesson

Next, read a dataset in a pipeline, write it to the iot_machine Entity output, and verify the result on the Data tab.