Reference

Owned by Baseer Khan
Last updated: Sept 28, 2020 by Long Tran
5 min read

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(Name: "ThingCategory"):
      Sid(Name: "thingCatID")
      String(Name: "catList", cardinality: "1..n")


# Let's Create few Thing Categories.
Query: 
  DeleteAll: 
    ThingCategory: 
      thingCatID(ne: "")
  Create: 
    ThingCategory: 
      catList: "Sensors"
  Create: 
    ThingCategory: 
      catList: "Actuators"
  Create: 
    ThingCategory: 
      catList: "Sensors"
      catList: "Actuators"
      catList: "Gateways"


# Now create VendorInfo with ThingCategory SID Value
Query: 
  Create: 
    VendorInfo: 
      vendorId: "vendorA"
      vendorName: "Phidget"
      vendorCity: "Calgary"
      thingCat: "LOBF4FOGAAAX6AAAAGEWWHEH"

# Let's do a Find on VendorInfo with nested *
Query: 
  Find(format: "all", nested: "*"):
    VendorInfo: 
      vendorId(ne: "")

# Response to the Find
Find(Status: "Success", Format: "all"):
    Result: 
        VendorInfo(QName: "Atomiton.Sensors.VendorInfo"):
            vendorId: "vendorA" 
            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" 
                    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")
            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")

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: "VendorInfo"):
      Sid Name: "vendorId")
      String Name: "vendorName")
      String Name: "vendorCity")
      Reference cardinality: "1..1", name: "thingCat", type: "ThingCategory")
DataModel Name: "ThingCategory"):
      Sid Name: "thingCatID")
      String Name: "catList", cardinality: "1..n")


# Let's Create few Thing Categories.
Query: 
  DeleteAll: 
    ThingCategory: 
      thingCatID(ne: "")
  Create: 
    ThingCategory: 
      catList: "Sensors"
  Create: 
    ThingCategory: 
      catList: "Actuators"
  Create: 
    ThingCategory: 
      catList: "Sensors"
      catList: "Actuators"
      catList: "Gateways"


# Now create VendorInfo with ThingCategory SID Value
Query: 
  Create: 
    VendorInfo: 
      vendorId: "vendorA"
      vendorName: "Phidget"
      vendorCity: "Calgary"
      thingCat: "LOBF4FOGAAAX6AAAAGEWWHEH"


# Let's do a Find on VendorInfo with nested *
Query: 
  Find(format: "all", nested: "*"):
    VendorInfo: 
      vendorId(ne: "")


# Response to the Find
Find(Status: "Success", Format: "all"):
    Result: 
        VendorInfo(QName: "Atomiton.Sensors.VendorInfo"):
            vendorId: vendorA 
            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"
                    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")
            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")


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