Data Models
Data Models are an easy-to-use way to replicate a data structure to multiple places in your namespace. Suppose you have an asset definition you want to standardize everywhere it appears. A data model stores that definition once and applies it wherever you need it.
A data model defines a small, self-contained sub-namespace. You version it and instantiate it across your namespace, so every place that uses it shares the same structure. A data model can also define the data source of each tag and field. For example, a tag in the model can take its value from a calculation that reads from other nodes of the model. When the standard evolves, you publish a new version of the model. You can then upgrade the instances to the new version.
Two Ways to Create a Data Model
You can start a data model in two ways:
-
Create it from an existing namespace node: the fastest way when you already have a structure you want to standardize. The node becomes the first instance of the model.
-
Start from a blank model: define the structure directly in the data model.
If a node already has the structure of a published model, you can also attach the node to the model.
Create a Data Model From an Existing Node
When you create a model from a node, you turn a structure that you already built into a reusable model.
HiveMQ publishes the model immediately as version v1.
The selected node and its child nodes become the first instance of the model.
You can then add more instances under other nodes.
You can create a model from a Folder or a Tag.
To create a model from a node, follow these steps:
-
In the namespace tree, select the node that you want to base the model on, for example, the
welding-cellfolder. -
Next to the node, click + to open the Add Node Type menu.
-
Under Data Model Actions, click Create / Attach.
A dialog opens. The dialog shows only the steps that apply to the selected node.
-
If the selected node matches an existing model, select Create a new data model and click Continue. For more information, see Attach an Existing Node to a Data Model.
-
In the Create Data Model From Node step, review the preview of the selected node and its child nodes.
-
Under Data model name, enter a name for the model. The field starts with the name of the selected node.
-
If the tags in the selected node use different brokers, click Continue and select a broker.
-
If the model cannot include all data sources, click Continue and review the data sources.
-
Click Create Data Model.
HiveMQ creates the model and converts the selected node in one operation. The message Data Model Created confirms the result. The details panel shows the new instance.
What Happens to the Selected Node
When the selected node becomes an instance, the nodes keep their data:
-
The instance has the same name as the selected node.
-
All nodes keep their stored history and their metadata.
-
All MQTT topics stay the same.
-
All nodes keep their activation state. If the tags are active, the instance is active. If the tags are inactive, the instance is inactive.
-
The nodes inside the instance inherit the traffic origin of the instance node.
Each tag in the model takes the History Settings of the tag that it comes from.
After the conversion, the nodes follow the model like the nodes of any other instance. To change the structure, create a new draft, publish the draft as a new version, and upgrade the instance. For more information, see Update or Upgrade a Model Instance.
Select a Broker for the Instance
A model instance uses one broker. If the tags in the selected node use different brokers, the dialog shows the Select a broker step. HiveMQ assigns the broker that you select to all tags in the instance.
For each broker, the step shows how many tags use the broker and how many tags change to the broker. HiveMQ preselects the broker that most tags use and shows the label Recommended. If two or more brokers have the highest number of tags, HiveMQ preselects no broker.
| A tag that changes to a different broker receives no data until the traffic of the tag reaches the selected broker. |
Data Sources in a Model From an Existing Node
When you create a model from a node, HiveMQ copies the data source of each tag and field in the selected node. A calculation, an expression, or a link becomes part of the model only if all of its inputs are inside the selected node.
If a data source reads from a node outside the selected node, the dialog shows an additional step. The title of the step shows the number of affected data sources, for example, 1 data source is not included in the model. For each affected node, the step shows the node name and the data source type.
The affected nodes behave as follows:
-
The selected node keeps the data sources. In the instance, you can still edit these data sources.
-
In new instances of the model, each affected node reads its value from MQTT instead of computing it.
To include the data sources in the model, close the dialog. Then create the model from a higher-level node that also contains the inputs of the data sources.
To find a node in the namespace tree, click the node name in the dialog. The dialog closes, and HiveMQ does not create the model.
In the following example, the line_temp_avg tag inside welding-cell has a calculation that reads from the temperature tag of line-1.
The temperature tag of line-1 is outside the welding-cell node.
Nodes That Cannot Become an Instance
HiveMQ checks the selected node and its child nodes when the dialog opens. If HiveMQ cannot convert the node, the dialog shows the error The selected node cannot be used to create a data model with the reason. In this case, the only action in the dialog is Close. To find a node that the error names, click the node name.
The following reasons are the most common:
-
The selected node contains a data model instance.
-
The selected node contains a node type that a data model cannot contain.
-
The name or the MQTT topic level of a node contains text in
{{and}}. A data model reads this text as a variable. -
Some tags are active, and other tags are inactive. To continue, activate or deactivate the selected node and all of its child nodes.
If HiveMQ cannot complete the check, the dialog shows the error The selected node could not be checked. To repeat the check, click Try Again.
Start a Data Model From a Blank State
To build a model without an existing node, create a new data model and define its structure directly. Give the model a Data Model Name and Version, then use Add Root Node to build the node tree that represents the structure you want to standardize. The platform keeps your work as a Draft until you are ready to use it.
The Create Data Model page has the following fields:
| Field | Description |
|---|---|
Data Model Name |
Required. A name for the model. For example, |
Version |
Required. The version of the model, such as |
Status |
The lifecycle state of the model. A new blank model or an edited model begins as a Draft. |
Description |
Optional context describing the model and its purpose. |
Nodes |
The structure of the model as a tree. You can save a draft without nodes. To publish the version, the tree needs at least one node. |
Use Add Root Node, Remove, and Deselect All to adjust the structure, and click a node in the tree to view and edit its details. To save your progress, click Save as Draft.
A root node of a model can be a folder or a tag. A field cannot be a root node of a model.
Each tag in the model has its own History Settings. The settings are the same as the History Settings of a tag in the namespace. A new tag in the model starts with the default limits: a Quantity of one element and a Data Volume of 10 KB. To adjust the limits or turn off history for a tag, select the tag in the model tree. Every instance of the model inherits the History Settings of the model version that you instantiate. For more information about each limit, see Configure History.
Define Variables in a Model
A model can define a placeholder instead of a fixed value.
Each instance of the model then supplies its own value for the placeholder.
To define a placeholder, open the details of a node in the model.
Click the variable icon next to the Node Name or MQTT Topic Level field.
HiveMQ inserts the placeholder {{VAR_NAME}} into the field.
Replace VAR_NAME with a name of your choice.
For example, a model with the topic level {{cell_id}} produces a different topic level in every instance.
Each placeholder becomes a required variable of the model version. When you instantiate the model, you provide a value for each variable. HiveMQ replaces the placeholder with that value wherever the placeholder appears.
A model that you create from an existing node has generated variables on its root node.
For example, a model that you create from the welding-cell node has the variables welding-cell Name and welding-cell Topic Level.
The first instance uses the name and the MQTT topic level of the selected node as the values.
If the selected node has no MQTT topic level, HiveMQ generates only the name variable.
In a variable name, HiveMQ replaces the characters {, }, ., [, and ] of the node name with _.
|
Two nodes under the same parent cannot share an MQTT topic level. HiveMQ checks this rule after it replaces the placeholders with your values. If the check fails, HiveMQ rejects the whole operation and does not create or change any nodes. HiveMQ rejects the operation in two cases:
To place the same model twice under one parent, give each instance a variable value that produces a distinct topic level. |
Define Data Sources in a Model
Like tags and fields in the namespace, each tag and field in a model has a data source. By default, a node reads its value from MQTT. To compute the value of a node from other nodes of the model, give the node a calculation, an expression, or a link. Every instance of the model receives the same data sources. You do not need to configure the calculations of each instance manually.
To set the data source of a node, follow these steps:
-
In the model tree, select the tag or field.
-
In the node details, click the Data Sources tab.
-
Under Select Data Source, click MQTT, Calculation, Expression, or Link.
-
Configure the data source as described in the following table.
-
To save a new model, click Save as Draft. For an existing draft, click Save.
The following example shows draft version v2 of the welding-cell model.
The temperature_avg tag uses the expression SMA(temperature). The expression computes the moving average of the last 25 temperature values.
| Source | Configuration |
|---|---|
MQTT |
The node reads its value from the MQTT topic that its topic levels define. The node needs no further configuration. |
Calculation |
Under Select a Formula, select a function. The form shows one input slot for each parameter of the function, labeled with the parameter name. An empty input slot shows Input for this variable is missing and the Select a node… list. From the list, select the node that supplies the value. After you select a node, the input slot shows the full path of the node in the model. To clear the input slot, click the remove icon. For a windowed parameter, set the number of values under Window. The default window size is the last 100 values. |
Expression |
In the Expression field, enter the formula. Each variable in the formula becomes an input slot. An empty input slot shows Input for this variable is missing and the Select a node… list. From the list, select the node that supplies the value. After you select a node, the input slot shows the full path of the node in the model. To clear the input slot, click the remove icon. To compute over the stored history of an input, select the Windowed check box. Then, set the number of values under Window. The default window size is the last 100 values. |
Link |
Under Reads from, select the node that supplies the values. The node mirrors every value that the selected node receives. |
For calculation functions, see Functions. For expression syntax, see Expression Language.
The Select a node… list shows the tags and fields of the model with their full path in the model. The list includes only nodes with a data type that the calculation or expression accepts.
You can also drag a tag or field from the model tree onto an input slot. The following rules apply to inputs:
-
A node cannot read from itself.
-
A data source cannot use the same node for two inputs.
|
All inputs of a data source in a model must be nodes in the same model. A calculation, an expression, or a link in a model cannot read from a node outside the model. |
When you save the draft, HiveMQ checks the data sources of the model. HiveMQ does not save the draft in the following cases:
-
A data source reads from a node that is not part of the model version.
-
The data sources form a cycle. For example, tag
areads from tagb, and tagbreads from taga. -
A tag and its fields have more than one data source. The same rule applies in the namespace. For more information, see Data Sources.
-
An expression contains a syntax error.
-
The data type of an input or of the node does not match the calculation or the expression.
Remove a Node That Supplies a Data Source
You cannot remove a node from the model while a data source in the model reads from the node. When you click Remove, the This node is still being read from dialog lists each data source that reads from the node. For each data source, the dialog shows the type of the data source and the inputs that the removal affects.
To remove the node, use one of the following options:
-
Remove the data sources that read from the node.
-
Select a different input for each of the data sources.
-
Remove a higher-level node that contains both the data sources and their inputs.
To find a node in the model tree, click the node name in the dialog.
Version and Publish a Data Model
A data model moves through a simple lifecycle.
While you create or edit a model, the version has the Draft status.
For a new model, click Save as Draft to save your progress.
For an existing draft, click Save.
When the model is ready, you publish it as a version.
A version needs at least one node before you can publish it.
For a version without nodes, the Publish button is disabled and shows the tooltip Add at least one node before publishing.
If you create a model from an existing node, HiveMQ publishes version v1 immediately.
A published version is immutable. After you publish a version, you cannot change its structure. To change a model, create a new draft, make your adjustments, and publish it again as a new version. Existing instances continue to reference the version you created them from, so publishing a new version never alters structures already in use.
Each model has its own list of versions, which you can reach from the Data Models area.
The version list shows every version of the model:
| Column | Description |
|---|---|
Version Name |
The version identifier, such as |
Created |
The date you created the version. |
Published |
The date and time of publication, if the version is published. |
Status |
The lifecycle state of the version: Draft or Published. |
Actions |
Actions available for the version, such as View. |
To start a new version, click Create Draft.
Reuse a Data Model in the Namespace
After you publish a data model, you apply it from the Add Node Type menu of a parent node. You can add an instance at any level of the namespace. However, a field cannot hold an instance.
-
In the namespace tree, select the parent node, such as
line-1undermachining. -
Next to the parent node, click + to open the Add Node Type menu.
-
Under Data Model Actions, click Instantiate.
-
In the Select Data Model dialog, select the model and version, such as
welding-cellatv1. -
Click Next.
-
In the instance form, enter an Instance Name, such as
Welding Cell 1, and an optional description. -
Under Required Variables, enter a value for each variable, such as
1forcell.If the model defines no required variables, the form shows This model has no required variables.
-
Click Instantiate Model.
| Your values must produce an MQTT topic level that no other node under the parent node uses. If the topic level already exists, HiveMQ rejects the instantiation and creates no nodes. For more information about the two cases HiveMQ checks, see Define Variables in a Model. |
The platform adds the model’s predefined structure at that location: the same welding-cell structure, now standardized under machining, without a manual rebuild.
An instance that you create with Instantiate starts inactive.
In this example, the nodes of Welding Cell 1 appear under machining/line-1 with the structure of the selected model version.
The broker stores history, runs calculations and expressions, and reports deviations only after you activate the instance.
For more information about the menu, see Add Data Model Nodes.
Find an Instance in the Namespace Tree
An instance has no row of its own in the namespace tree. Instead, a frame surrounds the root nodes of the instance and their child nodes. A data model badge with a cube icon appears at the top right of the frame. The frame has a dotted line. While you hover over the data model badge or while the instance is selected, the line is solid.
To see the model and the version of an instance, hover over the data model badge. To select an instance, click the data model badge. The details panel then shows the instance node.
The namespace tree does not show the name of an instance. To see the name, select the instance. In the namespace path of a node, the cube icon indicates the instance.
Run the Calculations and Expressions of an Instance
When you create a model instance, HiveMQ adds the calculations, expressions, and links of the model version to the instance. Each input reads from the instance node that matches the input node of the model.
A broker runs each calculation and expression of the instance. To assign the broker, HiveMQ looks for a traffic origin on the input nodes and their parent nodes. If HiveMQ finds no traffic origin, no broker runs the calculation or expression. In this case, the General tab of the instance node shows the warning Cannot assign a broker with the number of affected calculations and expressions. The Traffic Origin field of the instance node shows Missing.
In the following example, the Welding Cell 2 instance under acme contains the temperature_avg expression.
Neither the instance node nor its parent nodes have a traffic origin.
To run the calculations and expressions of an instance without a traffic origin, follow these steps:
-
In the namespace tree, click the data model badge of the instance.
-
In the panel header, click Edit.
-
Under Traffic Origin, select the broker that carries the traffic of the instance.
-
Click Save.
-
In the panel header, click Activate.
-
Review the affected nodes in the confirmation dialog.
-
In the dialog, click Activate.
| You can also set the traffic origin on a parent node of the instance. |
When a traffic origin becomes available, HiveMQ assigns a broker to each calculation and expression automatically. You activate the instance as a unit. When you activate the instance, the broker runs its calculations and expressions. For more information, see Activate and Deactivate Nodes.
Attach an Existing Node to a Data Model
If a node already has the structure of a published model, you can attach the node to the model. The node and its child nodes become an instance of the model. You do not need to rebuild the nodes. For the effect on the nodes, see What Happens to the Selected Node.
To attach a node to a data model, follow these steps:
-
In the namespace tree, select the node that you want to attach.
-
Next to the node, click + to open the Add Node Type menu.
-
Under Data Model Actions, click Create / Attach.
If the selected node matches at least one model, the dialog shows the title The selected node matches an existing data model. If no model matches, the dialog opens with the Create Data Model From Node step. For more information, see When a Node Matches a Data Model.
-
In the dialog, select the model that you want to attach the node to.
The dialog shows one entry for each model that matches, with the matched version. HiveMQ preselects the first entry.
-
If the tags in the selected node use different brokers, click Continue and select a broker.
-
If the selected node keeps data sources that the model does not include, click Continue and review the data sources.
-
Click Attach to Data Model.
The message Attached to Data Model confirms the result. The details panel shows the new instance.
When a Node Matches a Data Model
The selected node must match a published version of the model exactly. The selected node and its child nodes must have the same nodes as the version. The model must have exactly one root node. HiveMQ compares the selected node with the root node.
HiveMQ compares the following properties:
-
The name, type, and subtype of each node
-
The MQTT topic level of each folder and tag
-
The data type of each tag and field
-
The serialization format and the History Settings of each tag
-
The selector of each field
HiveMQ does not compare descriptions. The order of the nodes under a parent node has no effect on the match.
A variable in the model matches any value. If a variable appears more than once, the variable must have the same value in each place. HiveMQ takes the values of the variables from the names and the MQTT topic levels of the nodes. A model that you create from an existing node has variables for the name and the MQTT topic level of its root node. As a result, a node with a different name and a different MQTT topic level can match that model.
The data sources of the nodes must also match the data sources of the model. Two data sources match if they have the same type, the same inputs, and the same configuration. One exception applies to a node without a data source in the model. The node can keep a data source that reads from outside the selected node. You can still edit this data source in the instance. In the other instances of the model, the node reads its value from MQTT.
For each model, the dialog offers the newest published version that the selected node matches. If the selected node does not match a newer version, the entry in the dialog shows the newer version. After you attach the node, you can upgrade the instance to the newer version. For more information, see Update or Upgrade a Model Instance.
The checks in Nodes That Cannot Become an Instance also apply when you attach a node.
Update or Upgrade a Model Instance
A model instance references the model version that you created the instance from. To open the form that changes the instance, follow these steps:
-
In the namespace tree, click the data model badge of the instance.
-
In the panel header, click Edit.
The form shows the model, the version, the Instance Name, the description, the Traffic Origin, and the value of each variable. From the form, you have two options:
- Update the instance
-
Change the name, the description, the traffic origin, or the value of a variable, then click Save. The instance keeps its current version.
- Upgrade the instance
-
Under Version, select a newer version. Click Upgrade Instance. The list shows only published versions that are newer than the current version. You cannot return an instance to an earlier version.
An upgrade applies the structure of the new version to the instance. The form marks each variable that the new version adds with the label New. You must enter a value for each new variable before you submit the form.
| The topic level check also applies to updates and upgrades. If a variable value produces the topic level of an existing sibling node, HiveMQ rejects the operation and leaves the instance unchanged. For more information, see Define Variables in a Model. |
An upgrade also applies the data sources of the new version. HiveMQ replaces each calculation, expression, or link that the new version adds or changes. Data sources that the new version does not change stay as they are. If the instance is active, new calculations and expressions start when the upgrade completes.
HiveMQ rejects an upgrade that removes a node if a calculation or expression that remains after the upgrade reads from the node. For example, you add a calculation to a tag of the instance in the namespace. If the calculation reads from a tag that the new version removes, the upgrade fails.
The nodes inside an instance follow the model. The namespace offers no edit action for a single node inside an instance, and no option to add a node under an instance. The following exceptions apply:
-
You can set the traffic origin on the instance node. The nodes inside the instance inherit the traffic origin of the instance node.
-
If the model defines no data source for a tag or field, you can add a data source to the node in the namespace. An upgrade keeps that data source. However, if the new version defines a data source for the same node, the upgrade replaces your data source.
The data sources that the model defines are read-only in the namespace. For these nodes, the Data Sources tab shows the message This data source is defined by a data model. Change it in the data model and upgrade this instance.
To change the structure or the data sources of an instance, edit the model, publish the change as a new version, and upgrade the instance. To edit the nodes independently of the model, detach the instance from its data model.
Detach an Instance From Its Data Model
When you detach an instance, its nodes change to regular folders and tags. All nodes keep their data and history. You can edit the nodes like any other node in the namespace. However, you can no longer upgrade the nodes to a new model version.
To detach an instance, follow these steps:
-
In the namespace tree, click the data model badge of the instance.
-
In the panel header, click Detach from Model.
-
In the confirmation dialog, click Detach.
The Detach from Model button does not appear while the edit form of the instance is open.
The detach operation has the following effects:
-
HiveMQ removes the instance node. The root nodes of the instance move directly under the parent node of the instance.
-
All MQTT topics stay the same.
-
All nodes keep their activation state.
-
Each root node without its own traffic origin takes the traffic origin of the instance. The same broker runs the calculations and expressions as before.
-
The data sources stay on the nodes. You can edit the data sources that the model defined.
-
The model, its versions, and its other instances do not change.
After the operation, HiveMQ selects the parent node of the former instance.
You cannot undo a detach operation directly. If a root node of the former instance still matches a published version of the model, you can attach the node again.