DataModels

DataModel is one kind of models (the other kinds are 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 with Primitive Types

<DataModel Name="VendorInfo">
 <Sid name="VendorSysId"/>
 <String name="vendorName"/>
 <String name="vendorTitle"/>
</DataModel>

DataModel is often used in TQL applications to represent logical entities (versus physical things that have direct interactions with the application). For example, a user, a vendor, or a ladder.

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 be created, read, update and deleted using TQL CRUD Queries.

Create Query:

Create DataModel 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 DataModel Query Results

<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:

Find DataModel Query

<Query>
  <Find format="all">
    <VendorInfo>
      <vendorName eq="Phidget"/>
    </VendorInfo>
  </Find>
</Query>

Find Query Result:

Find DataModel 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 value 1457663102004 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:

Update DataModel 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.

Update DataModel Query

<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:

Delete DataModel Query

<Query>
  <DeleteAll>
    <VendorInfo>
      <vendorName eq="Phidget"/>
    </VendorInfo>
  </DeleteAll>
</Query>

DataModel with one Complex type.

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

DataModel attribute with Array

<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

Create DataModel attribute with Array

<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.

Unique Constraint on Attribute LightNumber

<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

Unique Constraint Violation Error

<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

Unique Constraint Violation Error

<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:

Unique Constraint Violation Error

<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

Find on DataModel with Cherry picked Attributes

<Query>
  <Find>
    <SensorVendorInfo>
      <SensorVendorSysId ne=""/>
    </SensorVendorInfo>
  </Find>
</Query>

SensorVendorInfo Find Result Contains data created in VendorInfo DataModel.

Find Result of DataModel with Cherry picked Attributes

<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.

Cherry picked DataModel

<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:

Create DataModel from Cherry picked Attributes

<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.

Find VendorInfo

<Query>
  <Find>
    <VendorInfo>
      <vendorSysId ne=""/>
    </VendorInfo>
  </Find>
</Query>

Find VendorInfo Result

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

Find VendorInfo Result

<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>