2.6.1 Target Entities

A Target Entity defines a data structure that becomes a node type in the knowledge graph. Each Target Entity has a title (up to 55 characters), an automatically generated slug (a URL-safe identifier), an optional description, and a flat list of properties. Every Target Entity also needs a business key (a unique identifier that distinguishes individual records) before it can be built.

Data enters a Target Entity through a Data Import Configuration, which connects the entity to a Data Source and maps source columns to the entity's properties. You can combine data from several source entities with Join Rules.

Define the Target Entity and its Relationships before importing any data, because DCH pre-calculates the relationships in the staging layer from what you import. A single Build operation then imports the data into staging and processes it into the knowledge graph.

To create a Target Entity, open the Model section, choose Add new › Target Entity, give it a title and (optionally) a description, add its properties, define a business key, and save. To open an existing entity, double-click it in the list (or its node on the canvas): its details open in a panel on the right, with Properties, Configuration and Log tabs and an Actions menu.

Properties

Properties are the attributes of a Target Entity. A property is defined by:

• Title: the property name (up to 55 characters). It must be unique within the entity, and some names are reserved for internal use.
• Expression (optional): a formula that derives the property's value from other properties. See Expressions.
• Business key: a flag marking the property as the entity's unique identifier (see Business Key). A business-key property is shown with a key icon.

Properties are name-based. DCH stores all values as strings, so properties do not carry a data type.

You can add properties one at a time with Add New, or use Bulk add properties to paste a newline-separated list where each line becomes a new property. Duplicate names are ignored.

Business Key

A business key uniquely identifies each record in a Target Entity. Every Target Entity must have exactly one business-key property before it can be used. There are two ways to define it:

• Use a single property: mark an existing property as the business key from its three-dots menu (Set as business key). The property is then shown with a key icon.
• Build a composite business key: when no single property is unique on its own, use Build a business key to create a new derived property whose expression combines several properties (for example `firstName` + `lastName` + `dateOfBirth`). This produces a single business-key property from multiple inputs.

Because only one business key is allowed, Build a business key is unavailable while another property is already marked as the business key; remove the existing key first (Remove business key).

note

A composite business key is not several business-key properties. It is one derived property whose expression concatenates the others, so the built value is what makes each record unique.

Expressions

Expressions derive a value from a Target Entity's properties. You use them in two places: building composite business keys, and transforming data in property mappings.

Expressions are evaluated by the Expression Worker, a separate service that must be running for expressions to work. It processes the whole column of data at once, and every result is returned as text.

Two rules underpin the syntax:

• Reference a property by wrapping its name in backticks: `first_name`.
• Write literal text in double quotes ("_"). Inside a function's arguments, use single quotes (.str.replace('-', '')).

Combine values

Join properties and literal text with +:

`first_name` + " " + `last_name`     # join two properties with a space
`order_id` + "_" + `product_id`      # a composite business key

Transform values

Because the worker is pandas-based, you can call string and value methods on a property:

`name`.str.upper()                                            # uppercase
`name`.str.lower()                                            # lowercase
`code`.str.replace('-', '')                                   # remove every "-"
`code`.str.slice(stop=4)                                      # keep the first 4 characters
`tags`.str.split(';').str[0]                                  # the part before the first ";"
`amount`.round(2)                                             # round a number
`ordered_at`.astype('datetime64[ns]').dt.strftime('%Y-%m-%d') # reformat a date

Good to know

• Every result is text. When you combine text with a number, the number becomes text, so `name` + `count` yields Order5.
• Take substrings with .str.slice(...), not bracket syntax like `name`[:4].
• .str.replace(...) matches literal text, not regular expressions.
• Literal text may contain only standard ASCII characters: for example § is not allowed.
• A referenced property must exist. Only the property names are checked when you save; a mistake in a function or operator only fails when the expression runs.

Data Import Configuration

A Data Import Configuration connects a Target Entity to a Data Source and defines how source columns fill the entity's properties.

A configuration has a name, an optional description, a selected Data Source and source configuration, a primary source entity, its property mappings, and any join rules. To create one, open the Target Entity, choose Add a data import configuration, name it, and pick the Data Source and primary source entity.

Property Mapping

Property mappings connect a source column to a target property. Two mapping types are stored:

• Manual mapping: map a source property directly to a target property.
• Expression mapping: map an expression to a target property, transforming the source data before it is stored.

Auto-map is a convenience action that fills in manual mappings automatically by matching source and target property names exactly. Any mappings it creates are ordinary manual mappings that you can still edit or delete. You can remove individual mappings, or clear all mappings at once.

Import options

When the configuration's data is imported into the staging layer, you choose how it is written. Rows are matched against the entity's existing staging data on the business key:

• Import mode
  • Insert: add new rows only. If a business key already exists it is left unchanged; a duplicate business key in the source causes an error.
  • Update: update existing rows only. Rows whose business key already exists are updated; new business keys are not added, and nothing is imported if the entity is empty or no business key matches.
  • Preserving merge: insert new rows and update existing ones, and keep rows whose business key is no longer in the source (they are not deleted).
• Clear: clear the entity's staging data before importing.
• Distinct: filter out duplicate rows before importing (all columns are compared).

The import runs as a data intake job; the application links to it so you can follow its progress in the Queue.

Data Preview

On a Target Entity, Preview data shows the entity's staging rows, the data that has been imported into it. It is available only after data has been imported. To preview the source data before it is imported, use the Data Source instead.

Join Rules

Join Rules integrate multiple source entities into one Target Entity, so a single entity can draw data from several related sources. A join is an equi-join between two source entities:

• Source A and its join property
• Source B and its join property

Rows are combined where Source A.property equals Source B.property. After you define a join, the additional source entity's columns become available in the property mappings. You can remove join rules individually or clear them all at once.

Actions

All major actions for a Target Entity are available from the Actions menu in its detail panel:

• Bulk add properties: add several properties at once.
• Build a business key: create a composite business key from an expression.
• Add a data import configuration: connect the entity to a Data Source.
• Preview data: view the entity's rows in the staging layer.
• Delete target entity: remove the entity (references are checked first).

Delete a Target Entity

To delete a Target Entity, open it and choose Delete target entity, then confirm. Before deleting, you can open Preview data to review what the entity currently holds. Deletion is checked against existing references (such as Relationships and Data Import Configurations) so that dependent parts of the Model are not silently broken.