Cloud Directory Update – Support for Typed Links

Earlier this year I told you about Cloud Directory, our cloud-native directory for hierarchical data and told you how it was designed to store large amounts of strongly typed hierarchical data. Because Cloud Directory can scale to store hundreds of millions of objects, it is a great fit for many kinds of cloud and mobile applications.

In my original post I explained how each directory has one or more schemas, each of which has, in turn, one or more facets. Each facet defines the set of required and allowable attributes for an object.

Introducing Typed Links
Today we are extending the expressive power of the Cloud Directory model by adding support for typed links. You can use these links to create object-to-object relationships across hierarchies. You can define multiple types of links for each of your directories (each link type is a separate facet in one of the schemas associated with the directory). In addition to a type, each link can have a set of attributes. Typed links help to maintain referential data integrity by ensuring objects with existing relationships to other objects are not deleted inadvertently.

Suppose you have a directory of locations, factories, floor numbers, rooms, machines and sensors. Each of these can be represented as a dimension in Cloud Directory with rich metadata information within the hierarchy. You can define and use typed links to connect the objects together in various ways, creating typed links that lead to maintenance requirements, service records, warranties, and safety information, with attributes on the links to store additional information about the relationship between the source object and the destination object.

Then you can run queries that are based on the type of a link and the values of the attributes within it. For example, you could locate all sensors that have not been cleaned in the past 45 days, or all of the motors that are no longer within their warranty period. You can find all of the sensors that are on a given floor, or you can find all of the floors where sensors of a given type are located.

Using Typed Links
To use typed links you simply add one or more Typed Link facets to your schema using the CreateTypedLinkFacet function. Then you call AttachTypedLink, passing in the source and destination objects, the Typed Link facet, and the attributes for the link. Other useful functions include GetTypedLinkFacetInformation, ListIncomingTypedLinks, and ListOutgoingTypedLinks. To learn more and to see the complete list of functions, take a look at the Cloud Directory API Reference.

Just as you can do for objects, you can use Attribute Rules to constrain attribute values. You can constrain the length of strings and byte arrays, restrict strings to a specified set of values, and limit numbers to a specific range.

My colleagues shared some sample code that illustrates how to use typed links. Here are the ARNs and the name of the facet:

String appliedSchemaArn   = "arn:aws:clouddirectory:eu-west-2:XXXXXXXXXXXX:directory/AbF4qXxa80WSsLRiYhDB-Jo/schema/demo_organization/1.0";
String directoryArn       = "arn:aws:clouddirectory:eu-west-2:XXXXXXXXXXXX:directory/AbF4qXxa80WSsLRiYhDB-Jo";
String typedLinkFacetName = "FloorSensorAssociation";

The first snippet creates a typed link facet called FloorSensorAssociation with sensor_type and maintenance_date attributes, in that order (attribute names and values are part of the identity of the link, so order matters):

client.createTypedLinkFacet(new CreateTypedLinkFacetRequest()
                                .withSchemaArn(appliedSchemaArn)
                                .withFacet(
                                      new TypedLinkFacet()
                                          .withName(typedLinkFacetName)
                                          .withAttributes(toTypedLinkAttributeDefinition("sensor_type"),
                                                          toTypedLinkAttributeDefinition("maintenance_date"))
                                          .withIdentityAttributeOrder("sensor_type", "maintenance_date")));

private TypedLinkAttributeDefinition toTypedLinkAttributeDefinition(String attributeName) {
 return new TypedLinkAttributeDefinition().withName(attributeName)
 .withRequiredBehavior(RequiredAttributeBehavior.REQUIRED_ALWAYS)
 .withType(FacetAttributeType.STRING);
}

The next snippet creates a link between two objects (sourceFloor and targetSensor), with sensor_type water and maintenance_date 2017-05-24:

AttachTypedLinkResult result = 
    client.attachTypedLink(new AttachTypedLinkRequest()
                               .withDirectoryArn(directoryArn)
                               .withTypedLinkFacet(
                                   toTypedLinkFacet(appliedSchemaArn, typedLinkFacetName))
                                   .withAttributes(
                                        attributeNameAndStringValue("sensor_type", "water"),
                                        attributeNameAndStringValue("maintenance_date", "2017-05-24"))
                                   .withSourceObjectReference(sourceFloor)
                                   .withTargetObjectReference(targetSensor));

private TypedLinkSchemaAndFacetName toTypedLinkFacet(String appliedSchemaArn, String typedLinkFacetName) {
   return new TypedLinkSchemaAndFacetName()
              .withTypedLinkName(typedLinkFacetName)
              .withSchemaArn(appliedSchemaArn);
}

The final snippet enumerates all incoming typed links of sensor_type water and a maintenance_date in the range 2017-05-20 to 2017-05-24:

client.listIncomingTypedLinks(
    new ListIncomingTypedLinksRequest()
        .withFilterTypedLink(toTypedLinkFacet(appliedSchemaArn, typedLinkFacetName))
        .withDirectoryArn(directoryArn)
        .withObjectReference(targetSensor)
        .withMaxResults(10)
        .withFilterAttributeRanges(attributeRange("sensor_type", exactRange("water")),
                                   attributeRange("maintenance_date", 
                                                  range("2017-05-20", "2017-05-24"))));

private TypedLinkAttributeRange attributeRange(String attributeName, TypedAttributeValueRange range) {
   return new TypedLinkAttributeRange().withAttributeName(attributeName).withRange(range);
}

private TypedAttributeValueRange exactRange(String value) {
   return range(value, value);
}

To learn more, read about Objects and Links in the Cloud Directory Administration Guide.

Available Now
Typed links are available now and you can start using them today!

— Jeff;