Reference

Developers can define different kinds on constraints on model attributes. The general grammar of constraints are defined in the TQL Model grammar There are two types of references

Simple Reference
Smart Reference

Simple Reference

Simple reference is defined using name and type modifier. The data associations between two models is automatically done via SID.

Sample Reference Attribute Definition

<Reference cardinality="1..1" name="reference name" type="name of model/def"/>

In this example thingCat is a reference attribute of VendorInfo. thingCat References 1 (cardinality is 1) instance of ThingCategory. The value of thingCat must be the SID of the ThingCategory instance.

Unique Constraint Violation Error

<DataModel Name="VendorInfo">
      <Sid Name="vendorId"/>
      <String Name="vendorName"/>
      <String Name="vendorCity"/>
      <Reference cardinality="1..1" name="thingCat" type="ThingCategory"/>
</DataModel>
<DataModel Name="ThingCategory">
      <Sid Name="thingCatID"/>
      <String Name="catList" cardinality="1..n"/>
</DataModel>


<!-- Let's Create few Thing Categories. -->
<Query>
  <DeleteAll>
    <ThingCategory>
      <thingCatID ne=""/>
    </ThingCategory>
  </DeleteAll>
  <Create>
    <ThingCategory>
      <catList>
        Sensors
      </catList>
    </ThingCategory>
  </Create>
  <Create>
    <ThingCategory>
      <catList>
        Actuators
      </catList>
    </ThingCategory>
  </Create>
  <Create>
    <ThingCategory>
      <catList>
        Sensors
      </catList>
      <catList>
        Actuators
      </catList>
      <catList>
        Gateways
      </catList>
    </ThingCategory>
  </Create>
</Query>


<!-- Now create VendorInfo with ThingCategory SID Value -->
<Query>
  <Create>
    <VendorInfo>
      <vendorId>
        vendorA
      </vendorId>
      <vendorName>
        Phidget
      </vendorName>
      <vendorCity>
        Calgary
      </vendorCity>
      <thingCat>
        LOBF4FOGAAAX6AAAAGEWWHEH
      </thingCat>
    </VendorInfo>
  </Create>
</Query>


<!-- Let's do a Find on VendorInfo with nested * -->
<Query>
  <Find format="all" nested="*">
    <VendorInfo>
      <vendorId ne=""/>
    </VendorInfo>
  </Find>
</Query>


<!-- Response to the Find -->
<Find Status="Success" Format="all">
    <Result>
        <VendorInfo QName="Atomiton.Sensors.VendorInfo">
            <vendorId>vendorA</vendorId>
            <thingCat Known="LOBF4FOGAAAX6AAAAGEWWHEH" Version="1" Timestamp="1492540919704" DateTime="2017-04-18 11:41:59.704" QName="Atomiton.Sensors.VendorInfo.thingCat" FName="thingCat">
                <Value QName="Atomiton.Sensors.ThingCategory">
                    <thingCatID>LOBF4FOGAAAX6AAAAGEWWHEH</thingCatID>
                    <catList Value="Sensors" Known="Sensors" Order="0x00" Version="1" Timestamp="1492540855750" DateTime="2017-04-18 11:40:55.75" QName="Atomiton.Sensors.ThingCategory.catList" FName="catList"/>
                    <catList Value="Actuators" Known="Actuators" Order="0x01" Version="1" Timestamp="1492540855751" DateTime="2017-04-18 11:40:55.751" QName="Atomiton.Sensors.ThingCategory.catList" FName="catList"/>
                    <catList Value="Gateways" Known="Gateways" Order="0x02" Version="1" Timestamp="1492540855751" DateTime="2017-04-18 11:40:55.751" QName="Atomiton.Sensors.ThingCategory.catList" FName="catList"/>
                </Value>
            </thingCat>
            <vendorCity Value="Calgary" Known="Calgary" Version="1" Timestamp="1492540919704" DateTime="2017-04-18 11:41:59.704" QName="Atomiton.Sensors.VendorInfo.vendorCity" FName="vendorCity"/>
            <vendorName Value="Phidget" Known="Phidget" Version="1" Timestamp="1492540919704" DateTime="2017-04-18 11:41:59.704" QName="Atomiton.Sensors.VendorInfo.vendorName" FName="vendorName"/>
        </VendorInfo>
    </Result>
</Find>

Smart Reference

In case of simple references the find result can automatically return the nested references (i.e. SIDs of other instances) can be automatically expanded into their referent instances.

Smart references extends automatic SID referencing to store any FIND query as a reference value. That is, instead of storing a simple referent SID it’s now possible to store a Find query as the reference value. The engine will collect and run these queries recursively and compose the result. This gives users a possibility to refer to other instance by more than just their SIDs, but any other attributes and/or conditions.

Smart References Notes:

Find queries can be defined either as reference attribute values (i.e. find query content is stored as a string reference attribute value) or defined in the model like below. usageInfo is a smart reference attribute defined to contain all data in UsageInformation model for the given day's activity.

Smart Reference Defined during Model definition

<DataModel Name="SmartMeterUsage">
      <Sid Name="Id"/>
      <String Name="dayActivityId"/>
      <Double Name="totalEnergyConsumption"/>
      <Reference Format="$ObjectFormat(xml)" Name="usageInfo" Type="SMeterUsageInformation">
        <Find>
          <UsageInformation>
            <actualUsageId>
              [:ID:]
            </actualUsageId>
          </UsageInformation>
        </Find>
      </Reference>
    </DataModel>
<DataModel Name="SMeterUsageInformation">
      <Sid Name="Id"/>
      <String Name="activityId"/>
      <String Name="actualUsageId"/>
      <DateTime Format="$SimpleDateFormat(yyyy-MM-dd'T'HH:mm:ss.SSS'Z')" Name="Timestamp"/>
      <Double Name="energy"/>
      <Double Name="load"/>
    </DataModel>


<!-- Find Query -->
<Query>
  <Find nested="*" format="order">
    <SmartMeterUsage>
      <ID ne=""/>
    </SmartMeterUsage>
  </Find>
</Query>


<!-- Find Result -->
<Find Status="Success" Format="order">
    <Result>
        <SmartMeterUsage>
            <Id>LPFSJ4C3AAAH6AAAAGU6SHHK</Id>
            <totalEnergyConsumption Value="100.0"/>
            <usageInfo Order="0x00">
                <Value>
                    <Id>LPFSJ4C3AAAX6AAAAHCPOI6Q</Id>
                    <load Value="30.0"/>
                    <Timestamp Value="2017-04-14T07:24:58.263Z"/>
                    <actualUsageId Value="LPFSJ4C3AAAH6AAAAGU6SHHK"/>
                    <activityId Value="TestActivity"/>
                    <energy Value="20.0"/>
                </Value>
                <Value>
                    <Id>LPFSJ4C4AAAH6AAAAEYSWQKW</Id>
                    <load Value="30.0"/>
                    <Timestamp Value="2017-04-14T07:24:58.265Z"/>
                    <actualUsageId Value="LPFSJ4C3AAAH6AAAAGU6SHHK"/>
                    <activityId Value="TestActivity"/>
                    <energy Value="20.0"/>
                </Value>
                <Value>
                    <Id>LPFSJ4C4AAAX6AAAAF4TIFYW</Id>
                    <load Value="30.0"/>
                    <Timestamp Value="2017-04-14T07:24:58.266Z"/>
                    <actualUsageId Value="LPFSJ4C3AAAH6AAAAGU6SHHK"/>
                    <activityId Value="TestActivity"/>
                    <energy Value="20.0"/>
                </Value>
                <Value>
                    <Id>LPFSJ4C4AABH6AAAAGAQH5K5</Id>
                    <load Value="30.0"/>
                    <Timestamp Value="2017-04-14T07:24:58.266Z"/>
                    <actualUsageId Value="LPFSJ4C3AAAH6AAAAGU6SHHK"/>
                    <activityId Value="TestActivity"/>
                    <energy Value="20.0"/>
                </Value>
            </usageInfo>
            <activityId Value="TestActivity"/>
        </SmartMeterUsage>
    </Result>
</Find>

Find result set with smart references

With format=”…”, content is delivered as “Value” attribute as a part of a structure containing requested format options. This is consistent across the board.
Smart references are *not the same* as attributes with cardinality > 1and expectations that smart reference query will return *exactly* the same result is unrealistic (it is true only without format or with format=”known”).