Entity design — name · Identity · Display · attribute types

An entity is an abstraction of one kind of real-world object. This lesson creates a single entity in the builder and fills in the schema metadata so the next lesson's dataset mapping picks up where you stop. The example is the smallest entity in the IoT scenario — IOT_Machine.

Prerequisites

• One collection of your own. (If you don't have one, take 5 minutes on the Analyst Path lesson 02 Create a collection step.)
• At least one dataset inside that collection. It's used in the lesson 03 mapping step. The dataset doesn't have to be clean — knowing its column names and types is enough.

Enter the builder from the left sidebar via ONTOLOGY → Modeling. Coming in via the collection context auto-applies the collection_id.

Placing one entity on a blank canvas

1. With the builder canvas blank, press the top + Entity button, or drag a predefined template like Person from the left template panel onto the canvas.
2. The right inspector (the attribute panel) opens. This lesson proceeds with manual creation, not from a template.

At this point, the canvas has one anonymous node and the inspector is empty. Fill the five areas below from top to bottom.

1. Basics — name, alias, description

• Name — The system name. Uppercase Latin + a domain prefix is recommended (e.g. IOT_Machine). This name is exposed verbatim as the :Label in Cypher queries, so avoid Korean characters, spaces, and hyphens.
• Alias — The label users see. Used as the primary title in the inspector, on the node label, and in global search. Use natural English (e.g. CNC machine).
• Description — A one- to two-line natural-language description. The AI button in the inspector can auto-generate it, but one line in your own words will save your future self in 6 months (e.g. "The per-CNC entity in the factory, identified by machine_id.").
• Collection — Required. Auto-filled when you entered via a collection context. If empty, save returns 422.

2. Schema — define attributes

In the schema area, add the entity's attributes one row at a time. At this point, keep what columns the dataset has in mind and match 1:1. The IOT_Machine example:

These six attribute types cover the first pass:

• Text — String. IDs, codes, free text. (e.g. machine_id)
• Integer — Whole number. Counts. (e.g. sensor_count)
• Float — Decimal. Ratios, scores. (e.g. latest_health_score)
• Boolean — True/false. Flags.
• Date — Date only.
• Timestamp — Date + time. Time series, event timestamps.

If your domain needs a more precise type (e.g. Decimal), the Entities manual covers the extended types. See the Related reference block at the bottom of this page.

3. Identity Keys — uniquely identifying an instance

The Identity Key checkbox next to a schema row locks that column as the unique identifier. The IOT_Machine example checks only machine_id.

• Multiple columns can be checked (composite key). Example: (supplier_id, contract_period).
• If empty, the builder shows a warning, and the Entity node in any pipeline using this entity will fail payload validation at runtime. This lesson always checks at least one row before moving on.

4. Display Column — the primary UI label

In the same schema area, the Display Column dropdown picks one column from the schema as the primary label. For IOT_Machine, the identifier itself serves as the label, so machine_id is the natural choice. When there's a human-readable column (e.g. name, customer_name), that one is usually more natural.

Once this single row is filled, clicking a node in the Graph explorer shows that instance's label instead of "anonymous node 1234".

5. Save — and self-check

The top of the canvas Save button (or Ctrl/Cmd + S) registers the entity into the collection. Confirm these four things in the inspector at once:

• The node label shows the alias (e.g. CNC machine).
• The system name shows as the subtitle (e.g. IOT_Machine).
• At least one row is checked as an Identity Key.
• A single column is set as the Display Column.

After saving, if another worker in the same collection saves the same entity within a short interval, the inspector shows a Self-overwrite warning — pause once more to confirm intent.

Self-check

• One entity is saved inside your collection.
• All three of name, alias, description are filled.
• At least one row is checked as an Identity Key and one column is set as the Display Column.
• You picked at least two of the six attribute types that match your domain.

Next lesson

The next lesson maps this entity's attributes to the columns of your dataset 1:1. Once mapping completes, the backend sink fills the graph database with instances automatically, and the first nodes start appearing in the Graph explorer.