Link Path Comparison Functions

DQL can compare the values defined by two distinct link paths. For example, suppose we want to see if a message sender’s department is the same as, overlaps with, is a superset of, or is completely different than the department of the message’s recipients. To compare two link paths, DQL provides link path comparison functions, which take two link paths as parameters. The following functions are available:

Function	Meaning
EQUALS(X,Y)	The sets X and Y are either both empty or contain exactly the same values.
INTERSECTS(X,Y)	The sets X and Y are either both empty or contain at least one value in common.
CONTAINS(X,Y)	The set X contains all of the members of set Y. Either both sets must be empty or both most be non-empty.
DISJOINT(X,Y)	Neither set X nor Y are empty and they contain no common member. Same as NOT INTERSECTS.

 

In the summary above, X and Y are link paths that resolve to the same scalar or link field. For example:

EQUALS(Sender.Person.Department,InternalRecipients.Person.Department)

This clause returns true if all of a message’s internal recipients are in the same Department as the message’s sender. Since empty sets are considered equal, this clause selects messages for which both Sender.Person.Department and InternalRecipients.Person.Department are null. Since a link path is null when any field in the path is null, Sender.Person.Department is null if any of Sender, Sender.Person, or Sender.Person.Department is null. To return true only for non-null sets, add a second clause that selects non-null values for one of the link paths. Example:

EQUALS(Sender.Person.Department,InternalRecipients.Person.Department) AND
Sender.Person.Deparment=*

Note that X=* is shorthand for NOT X IS NULL.

The links paths passed to a comparison function can include WHERE filters to reduce the set of values used for comparison. For example:

CONTAINS(Sender.Person.Department,InternalRecipients.Person.WHERE(Office:aliso).Department)

CONTAINS performs an overlap comparison, testing whether the first parameter produces a value set that contains the values produced by the second parameter. This clause above selects a message if at least one internal recipient whose Office contains the term aliso is in the same department as the message’s sender. As in the previous example, another clause can be added to skip messages where both link paths are null.

INTERSECT is a more general case of CONTAINS that returns true when any value is shared between the sets produced by the link paths.

The DISJOINT function does not select objects in which both link paths are null. Both link paths must produce a non-empty set and both must have no values in common for the function to return true.

With all of the link path comparison functions, the terminal field in each link path can be a link field, though it must be the same link field. For example:

EQUALS(Sender.Person,InternalRecipients.Person) AND NOT Sender.Person IS NULL

This query returns true if Sender.Person is not null and is exactly the same person(s) as InternalRecipients.Person. In other words, someone sent a message to himself only.