Edit

Share via

Digital twin builder (preview) in Real-Time Intelligence tutorial part 3: Build the ontology

In this part of the tutorial, you build a digital twin ontology that models the bus and bus stop data. You create a digital twin builder (preview) item, and define entities for the buses and stops. Then, you map the data from the Tutorial lakehouse to the entities, and define relationships between the entities to further contextualize the data.

Important

This feature is in preview.

Create new digital twin builder item in Fabric

  1. Go to your Fabric workspace.

  2. Select New item.

  3. Search for the Digital Twin Builder (preview) item, and select it.

    Screenshot of Digital Twin Builder item.

  4. Enter BusModel as the name for your item and select Create.

  5. Wait for your digital twin builder item to be created. Once your digital twin builder item is ready, it opens to the semantic canvas.

In the semantic canvas, you can add entities and relationships to define an ontology.

About entities and relationships

In digital twin builder (preview), an entity is a category that defines a concept within a ___domain-specific ontology. The entity definition serves as a blueprint for individual entity instances of that entity, and specifies common characteristics shared across all instances within that category. Here you define two entities for the sample scenario: Bus and Stop.

After you create an entity, you can map data to it to hydrate the entity with data from various source systems. You can add both time series and non-time series properties to an entity. When mapping both types of property to an entity, you must map at least one non-time series property before you can map time series properties. Then, link the non-time series and time series data together by matching a non-time series property from the entity with a column from the time series data. The values in the time series column must exactly match data that's mapped to the entity property.

After your entities are defined and mapped, you can create relationships between them to define how they're related to each other. In this tutorial, a Bus goesTo a Stop.

Add Bus entity

First, create a new entity for the bus.

  1. In the semantic canvas of digital twin builder (preview), select Add entity.

    Screenshot of Add entity button.

  2. Leave the Generic system type selected, and enter Bus for the entity name. Select Add entity.

  3. The Bus entity is created and becomes visible on the canvas.

    Screenshot of Bus entity.

Map non-timeseries bus data

Next, map some non-timeseries data to the Bus entity. These fields are static properties that identify a bus and its visit to a certain stop.

  1. In the Entity configuration pane, switch to the Mappings tab and select Add data.

    Screenshot of adding a data mapping.

  2. Open Select lakehouse table to select a data source for your mapping. Select your tutorial workspace, the Tutorial lakehouse, and the bus_data_processed table.

    Screenshot of the bus data source.

    Optionally, wait for the data preview to load. Select Choose data source to confirm.

  3. For the Property type, leave the default selection of Non-timeseries properties.

  4. Under Unique Id, select the edit icon (shaped like a pencil) to choose a unique ID out of one or more columns from your source data. Digital twin builder uses this field to uniquely identify each row of ingested data.

    Select TripId as the unique ID column.

    Screenshot of the bus unique ID.

  5. Under Mapped properties, select the edit icon to choose which properties from your source data to map to the bus entity.

    The Map properties page lets you select a column from your source data on the left side, and map it to a new property on your entity on the right side. By default, selecting a column name from the source data on the left side fills in the right side automatically with a matching name for the entity property, but you can enter a new name for the property on the right side if you want the entity property to be named something different than what it's called in the source data.

    The page loads with a DisplayName property for the entity, which is unmapped to any column in the source data. Leave the DisplayName property unmapped as it is, and select Add entity property to add new properties to the mapping.

    Screenshot of the unmapped display name and adding an entity property.

    Map the following entity properties:

    • Select TripId from the dropdown menu in the left column, and edit the box across from it in the right column to read TripId_static. This action creates a property on the bus entity named TripId_static, which gets its value from the TripId property in the source data.
    • Select StopCode from the dropdown menu in the left column, and edit the box across from it in the right column to read StopCode_static. This action creates a property on the bus entity named StopCode_static, which gets its value from the StopCode property in the source data.

    Check the box to acknowledge that properties can't be renamed or removed, and select Apply.

    Screenshot of the mapped non-timeseries bus properties.

  6. Save the mapping.

    Screenshot of saving the bus non-time series mapping.

  7. Switch to the Scheduling tab and select Run now to apply the mapping.

    Screenshot of running the bus mapping.

    The page confirms that the flow is queued.

  8. Check the status of your mapping job in the Manage operations tab. Wait for the status to say Completed before proceeding to the next section (the operation might take several minutes to begin running from the queue, and several more minutes to complete once it starts, so you might need to refresh the content a few times).

    Screenshot of the Manage operations button from the bus entity.

    Screenshot of the Manage operations tab with the bus entity mapping.

Map time series bus data

Next, map some time series data to the Bus entity. These properties are streamed into the data source from the Eventstream sample data, and they contain information about the bus's ___location and movements.

  1. Go back to the Configure view and reselect the Bus entity. In the Entity configuration pane, reopen the Mappings tab. Select Add data to add a new mapping.

    Screenshot of adding a new bus mapping.

  2. Open Select lakehouse table to select a data source for your mapping. Again, select your tutorial workspace, the Tutorial lakehouse, and the bus_data_processed table. Select Choose data source.

  3. This time, switch the Property type to Timeseries properties.

  4. Under Mapped Properties, select the edit icon.

    The page loads with a Timestamp property for the entity, which is unmapped to any column in the source data. Timestamp requires a mapping, so select ActualTime from the corresponding dropdown menu on the left side. Then, select Add entity property to add new properties to the mapping.

    Map the following properties. When you select these property names from the source columns on the left side, leave the default matching names that populate on the right side.

    • ScheduleTime
    • BusLine
    • StationNumber
    • StopCode
    • BusState
    • TimeToNextStation
    • TripId

    Screenshot of the mapped time series bus properties.

  5. Check the box to acknowledge that properties can't be renamed or removed, and select Apply.

  6. Next, link your time series data to this entity. This process requires you to select an entity property and a matching column from your time series data table. The column selected from the time series data must exactly match data that is mapped to the selected entity property. This process ensures correct contextualization of your entity and time series data.

    Under Link with entity property, select the edit icon.

    For Choose entity property, select TripId_Static from the dropdown menu. For Select column from timeseries data..., select TripId. Select Apply.

  7. Make sure Incremental mapping is enabled and Save the mapping. Confirm when prompted.

    Screenshot of saving the bus time series mapping.

  8. Switch to the Scheduling tab and select Run now under the new time series mapping to apply it.

Add Stop entity

Next, create a second entity to represent a bus stop.

  1. In the semantic canvas, select Add entity.

  2. Leave the Generic system type selected, and enter Stop for the entity name. Select Add entity.

  3. After a few minutes, the Stop entity is now visible on the canvas.

    Screenshot of Stop entity.

Map non-timeseries stop data

Next, map some non-timeseries data to the Stop entity. The stop data doesn't contain any time series data, only static data about the bus stops and their locations. Later, when you link the Stop and Bus entities together, this data is used to enrich the bus fact data with dimensional data.

  1. In the Entity configuration pane, open the Mappings tab and select Add data.

  2. Open Select lakehouse table to select a data source for your mapping. Select your tutorial workspace, the Tutorial lakehouse, and the stops_data table.

    Select Choose data source.

  3. For the Property type, leave the default selection of Non-timeseries properties.

  4. For the Unique Id, select Stop_Code.

  5. For Mapped properties, map Stop_Name from the source data to the DisplayName property on the right side.

    Then, add the following new properties to the mapping. When you select these property names from the source columns on the left side, leave the default matching names that populate on the right side.

    • Stop_Code
    • Road_Name
    • Borough
    • Borough_ID
    • Suggested_Locality
    • Locality_ID
    • Latitude
    • Longitude

    Check the box to acknowledge that properties can't be renamed or removed, and select Apply.

    Screenshot of the mapped non-timeseries stop properties.

  6. Save the mapping.

    Screenshot of saving the stop mapping.

  7. Switch to the Scheduling tab and select Run now to apply the mapping.

Define relationship

Next, create a relationship to represent that a Bus goesTo a Stop.

  1. In the semantic canvas, highlight the Bus entity and select Add relationship.

    Screenshot of adding a relationship.

  2. In the Relationship configuration pane, enter the following information:

    • First entity: Bus
      • Property to join: StopCode_static
    • Second entity: Stop
      • Property to join: Stop_Code
    • Relationship name: Enter goesTo
    • Select relationship type: Many Stop per Bus (1:N)

    Select Create.

    Screenshot of the relationship configuration.

  3. In the Scheduling section that appears, select Run now to apply the relationship.

Now your Bus and Stop entities are visible in the canvas with a relationship between them. Together, these elements form the ontology for the tutorial scenario.

Screenshot of the ontology.

Verify mapping completion

As a final step, confirm that all your data mappings ran successfully. Each mapping might take several minutes to run.

  1. From the menu ribbon, select Manage operations.

    Screenshot of selecting Manage operations.

  2. View the details of the mapping operations, and confirm that they all completed successfully.

    Screenshot of four completed operations.

  3. If any of the operations failed, check the box next to its name and select Run now to rerun it.

Wait for all mappings to complete before you move on to the next part of the tutorial. In the next part, you project the ontology that you mapped to an eventhouse, to support further data analysis and visualization.

Next step

Tutorial part 4: Project data to Eventhouse