The pair parameter supports a special kind of aggregate query called a
dual role query. To illustrate when it is needed, let’s first look at a dual role
object query, which
doesn’t require the “pair” functionality.
As an object query, this is rather straightforward and can be specified as follows:
But suppose we want to group the results based on a field belonging to one of the roles: for example, we want to group by the Department of the Kanata participant. When the Kanata participant is the sender, we want to group by
Sender.MessageAddress.Person.Department. When the Kanata participant is the receiver, we want to group by
InternalRecipients.MessageAddress.Person.Department. But we can only group on one field at each level—we can’t group on a participant’s
role (“the Kanata participant”), which is defined by two different link paths.
.../Message/_aggregate?pair=Sender,InternalRecipients
&q=
_pair.first.Person.Office:Kanata AND
_pair.
second.Person.Department:Support
&f=
_pair.first.Person.Department
•
|
When the pair parameter is used, the system field _pair can be used in the query and/or fields parameters. The _pair system field must be followed by the subfield first or second, and the remainder of the expression must be valid based on the pair fields’ table. In this example, since the pair fields are links to the Participant table, the remainder of the expression must be valid for Participant objects.
|
•
|
The subfield name (first or second) is used for binding purposes: the _pair field expression is actually applied to both pair fields. That is, the query is executed twice with the roles of the pair fields reversed. In the first execution, the query expression is first evaluated using Sender in the first role and Recipients in the second role:
|
In this execution, the sender(s) are bound to
_pair.first and the internal recipients are bound to
_pair.second. Because the grouping parameter groups by
_pair.first.Person.Department, this means that if the expression selects a message, the sender’s department is used to choose the message’s group. In other words:
Here, _pair.first is bound to
Recipients and
_pair.second is bound to
Sender. Consequently, if the expression selects a message, it is recipient’s department that is used to choose the message’s group. In other words:
Note that using a _pair field in a metric parameter may produce unexpected results. If the same object participates in both roles, it included twice in each metric computation. In general, the objects selected by the two pair field parameters should be mutually exclusive.