Data model is one kind of models (along with ThingModels and AppModels). Therefore it has all the properties of Models (Lifecycle of models, Model Attributes, Unique and Constraints).
A DataModel is defined with a Name and any number of Model Attributes. DataModels do not have Actions.
Example of a DataModel:
A DataModel definition with three simple a\Attributes:
<DataModel Name="VendorInfo"> <Sid name="VendorSysId"/> <String name="vendorName"/> <String name="vendorTitle"/> </DataModel>
DataModels by default contain an Attribute of type SystemId (or Sid). If the Sid name is not defined, _____?
The purpose of DataModel is to store just enough data that may be required to complete IoT Application logic. DataModels are not meant for general purpose large volume of transnational data.
- DataModel can contain any number of Unique Constrains that are defined on a collection of attributes.
DataModel can be created, read, update and deleted using TQL CRUD Queries.
Create Query:
<Query> <Create> <VendorInfo> <vendorName>Phidget</vendorName> <vendorTitle>Sensor Provider</vendorTitle> </VendorInfo> </Create> </Query>
Create Query Result:
Note that VendorSysId of type Sid is automatically generated without specifying the value in Create Query Statement.
<Create Status="Success"> <VendorInfo> <VendorSysId>KNTJ5MYXAAAAUAABA7EIY2FH</VendorSysId> <vendorName Status="Success+Created:1:1457715589911;" Value="Phidget"/> <vendorTitle Status="Success+Created:1:1457715589914;" Value="Sensor Provider"/> </VendorInfo> </Create>
Find Query:
<Query> <Find format="all"> <VendorInfo> <vendorName eq="Phidget"/> </VendorInfo> </Find> </Query>
Find Query Result:
<Find Status="Success" Format="all"> <Result> <VendorInfo QName="SimpleModel.MyModels.VendorInfo"> <VendorSysId>KNRX3TBUAAAAUAABA4LIWHP2</VendorSysId> <vendorTitle Value="Sensor Company" Known="Sensor Company" Version="1" Timestamp="1457663102018" DateTime="2016-03-10 18:25:02.018" QName="SimpleModel.MyModels.VendorInfo.vendorTitle" FName="vendorTitle"/> <vendorName Value="Phidget" Known="Phidget" Version="1" Timestamp="1457663102004" DateTime="2016-03-10 18:25:02.004" QName="SimpleModel.MyModels.VendorInfo.vendorName" FName="vendorName"/> </VendorInfo> </Result> </Find>
Automatically Generated System Attributes
TQLEngine automatically generates attributes as part of every attribute that make up the DataModel Definition. System attributes can Read (Find) using
Format="all" modified on <Find> Query.
System Attribute Name | Description |
---|---|
Value | The value of the attribute is stored in "Value". This is specified by user at time of create query |
Known | Applicable to ThingFacet/AppFacet - this is the value that is set within the Action. Known can not be set using Create / Update TQL Query by the user. |
Version | Version number of the attribute. This number is automatically incremented each time the value changes. |
Timestamp | Unix epoch time at the time (in millisecond) of the attribute creation. For example: Timestamp value1457663102004 is same as Fri, 11 Mar 2016 02:25:02 GMT |
Datetime | Formatted data time value of the attribute creation. For example:2016-03-10 18:25:02.004 |
QName | Fully qualified name of the attribute. <NamSpace>.<Domain>.<ModelName>.<AttributeName>. For example SimpleModel.MyModels.VendorInfo.vendorName given that VendorInfo is defined within Namespace - SimpleModel, with Domain as MyModels and DataModel Name as VendorInfo |
FName | Given name of the attribute name. |
Update Query:
<Query> <Find format="version"> <VendorInfo> <vendorName eq="Phidget"/> </VendorInfo> </Find> <SetResponseData> <Key>Message.Value.Find.Result.VendorInfo.vendorName</Key> <Value>Phidget Inc</Value> </SetResponseData> <Update> <From>Result</From> <Include>$Response.Message.Value.Find</Include> </Update> </Query>
Update Query Result:
Note that the Version number is incremented automatically if the update is successful.
<Find Status="Success" Format="version"> <Result> <VendorInfo> <VendorSysId>KNTMS6F7AAAAUAABA7SVACBP</VendorSysId> <vendorTitle Value="Sensor Provider" Version="1"/> <vendorName>Phidget Inc</vendorName> </VendorInfo> </Result> </Find> <Update Status="Success" Format="version"> <VendorInfo> <VendorSysId>KNTMS6F7AAAAUAABA7SVACBP</VendorSysId> <vendorName Status="Success=Updated:2:1457718402256;" Value="Phidget Inc" Version="2"/> <vendorTitle Status="Success_NoAction:1:1457718393024;" Value="Sensor Provider" Version="1"/> </VendorInfo> </Update>
Delete Query:
<Query> <DeleteAll> <VendorInfo> <vendorName eq="Phidget"/> </VendorInfo> </DeleteAll> </Query>
DataModel with one Complex type.
<Def Name="PostalAddress"> <String Name="Street"/> <String Name="City"/> <String Name="Zipcode"/> </Def> <DataModel Name="VendorInfo"> <Sid name="VendorSysId"/> <String name="vendorName"/> <String name="vendorTitle"/> <PostalAddress name="VendorAddress"/> </DataModel>
DataModel with one Attribute that is of Array defined via Cardinality.
- Arrays are defined using Cardinality with value : "MinValue..MaxValue"
- Where MinValue >=0
- MaxValue is any integer m > 0
<Def Name="PostalAddress"> <String Name="Street"/> <String Name="City"/> <String Name="Zipcode"/> </Def> <DataModel Name="VendorInfo"> <Sid name="VendorSysId"/> <String name="vendorName"/> <String name="vendorTitle"/> <PostalAddress name="VendorAddress"/> <String Name="DeviceTypes" Cardinality="0..m"/> </DataModel>
Create Data Model with Array Attribute
<Query> <Create> <VendorInfo> <vendorName>Phidget</vendorName> <vendorTitle>Sensor Provider</vendorTitle> <vendorAddress> <Street>123 TQL Way</Street> <City>Sunnyvale</City> <Zipcode>91234</Zipcode> </vendorAddress> <DeviceTypes>Sensors</DeviceTypes> <DeviceTypes>Actuators</DeviceTypes> </VendorInfo> </Create> </Query>
Unique Constraints on DataModel
Unique Constraint defined Data Identity definition using list of attributes. Once defined the TQLEngine ensures that a combination of attribute values are unique across all objects.
In this example let's define unique constraint on VendorName.
<DataModel Name="VendorInfo"> <Sid name="VendorSysId"/> <String name="VendorName"/> <String name="VendorTitle"/> <PostalAddress name="VendorAddress"/> <String Name="DeviceTypes" Cardinality="0..m"/> <Unique Name="UniqueVendorName" Value="VendorName"/> </DataModel>
If you try to create VendorInfo with same VendorName, the Create TQL Query Fails with Unique Constraint Violation
<Create Status="Failure"> <VendorInfo> <VendorSysId>chag3vw7tcet7dvg2athubjwl2gvth73</VendorSysId> <VendorName Status="Failure!UpdateConflict:Create:Record exists:integrity constraint violation: unique constraint or index violation; SYS_PK_10098 table: TR;" Value="Phidget"/> <VendorTitle Status="Failure!UpdateConflict:Create:Record exists:integrity constraint violation: unique constraint or index violation; SYS_PK_10098 table: TR;" Value="Sensor Provider"/> <VendorAddress> <Street Status="Failure!UpdateConflict:Create:Record exists:integrity constraint violation: unique constraint or index violation; SYS_PK_10098 table: TR;" Value="123 TQL Way"/> <City Status="Failure!UpdateConflict:Create:Record exists:integrity constraint violation: unique constraint or index violation; SYS_PK_10098 table: TR;" Value="Sunnyvale"/> <Zipcode Status="Failure!UpdateConflict:Create:Record exists:integrity constraint violation: unique constraint or index violation; SYS_PK_10098 table: TR;" Value="91234"/> </VendorAddress> </VendorInfo> </Create>
DataModel by picking Attributes from other defined DataModel
We famously call such DataModel as "Cherry Picked DataModel". Attributes are Cherry picked from some other defined model.
In this example SensorVendorInfo contains SensorVendorSysId, SensorVendorName defined and available in VendorInfo
<DataModel Name="VendorInfo"> <Sid name="VendorSysId"/> <String name="VendorName"/> <String name="VendorTitle"/> <PostalAddress name="VendorAddress"/> <String Name="DeviceTypes" Cardinality="0..m"/> <Unique Name="UniqueVendorName" Value="VendorName"/> </DataModel> <DataModel name="SensorVendorInfo"> <Attribute name="SensorVendorSysId" value="VendorInfo.VendorSysId"/> <Attribute name="SensorVendorName" value="VendorInfo.VendorName"/> </DataModel>
Once VendorInfo Data is created using Create TQL Query. The SensorVendorInfo will automatically have the Data as well.
Note that Data can be create in opposite direction as well i.e. Once created in SensorVendorInfo the common attributes will be available in VendorInfo as well.
Create VendorInfo Data:
<Query> <Create> <VendorInfo> <vendorName>Phidget</vendorName> <vendorTitle>Sensor Provider</vendorTitle> <vendorAddress> <Street>123 TQL Way</Street> <City>Sunnyvale</City> <Zipcode>91234</Zipcode> </vendorAddress> <DeviceTypes>Sensors</DeviceTypes> <DeviceTypes>Actuators</DeviceTypes> </VendorInfo> </Create> </Query>
Query SensorVendorInfo DataModel
<Query> <Find> <SensorVendorInfo> <SensorVendorSysId ne=""/> </SensorVendorInfo> </Find> </Query>
SensorVendorInfo Find Result Contains data created in VendorInfo DataModel.
<Find Status="Success"> <Result> <SensorVendorInfo> <SensorVendorSysId>chag3vw7tcet7dvg2athubjwl2gvth73</SensorVendorSysId> <SensorVendorName>Phidget</SensorVendorName> </SensorVendorInfo> </Result> </Find>
DataModel by picking Attributes from other defined DataModel + newly defined Attributes
DataModel can contain both cherry picked attributes as well as new attributes. Here SensorVendorInfo contains SensorTypes as new attribute of type string.
<DataModel Name="VendorInfo"> <Sid name="VendorSysId"/> <String name="VendorName"/> <String name="VendorTitle"/> <PostalAddress name="VendorAddress"/> <String Name="DeviceTypes" Cardinality="0..m"/> <Unique Name="UniqueVendorName" Value="VendorName"/> </DataModel> <DataModel name="SensorVendorInfo"> <Attribute name="SensorVendorSysId" value="VendorInfo.VendorSysId"/> <Attribute name="SensorVendorName" value="VendorInfo.VendorName"/> <String Name="SensorTypes Cardinality="0..m"/> </DataModel>
Let's create SensorVendorInfo now using Create TQL Query:
<Query> <Create> <SensorVendorInfo> <SensorVendorName>Phidget</SensorVendorName> <SensorVendorTitle>Sensor Provider</SensorVendorTitle> <SensorTypes>Temperature</SensorTypes> <SensorTypes>Light</SensorTypes> </SensorVendorInfo> </Create> </Query>
Let's do a Find on VendorInfo. We get the VendorInfo and VendorTitle data back.
<Query> <Find> <VendorInfo> <vendorSysId ne=""/> </VendorInfo> </Find> </Query>
Find VendorInfo Result
<Find Status="Success"> <Result> <VendorInfo> <VendorSysId>KNTR2FJXAAAAUAABA5OUP375</VendorSysId> <VendorName>Phidget</VendorName> </VendorInfo> </Result> </Find>
Selective Cherry picking using Constraint
In some cases we may want to selective pick attributes. For example, We only want Vendors with Sensor DeviceType. This can be achieved using Constraint.
In this case only Sensor DeviceTypes will be populated in SensorVendorInfo
<DataModel name="SensorVendorInfo"> <Attribute name="SensorVendorSysId" value="VendorInfo.VendorSysId"/> <Attribute name="SensorVendorName" value="VendorInfo.VendorName"/> <String Name="SensorTypes" Cardinality="0..m"/> <Constraint target="VendorInfo.DeviceTypes" eq="lit.Sensor"/> </DataModel>