Role playing relationships mean than an entity can have more than one join path to it and acts differently (“role-plays”) based on the join path taken.

Interface

A relationship between two entities can have a role parameter in the schema, that defines a name for that relationship.

Role names are globally unique.

When a role is used, the Honeydew engine knows which join path to construct. If there are two paths, and no role is selected then Honeydew will not know which way to go and will fail the query.

An entity that has more than one possible path to it (a circle in the entity graph pointing to it), must have roles assigned to its relationships.

Otherwise, Honeydew will not know which join path to take.

If an entity has just one possible path to it, there is no need to define a role for it - it is the only one. But if another relationship creates a multiple path situation, all relationships to that entity must be assigned a role name.

Selecting a role

Selecting a role is done with the USING qualifier on a field.

entity.field USING (role)

Example

In TPC-H example, the nation entity relations are a role play. A nation can be for a customer, or for a supplier.

Both are based on the same table, but when nation joined to supplier it means a different thing than nation joined to customer.

Possible questions might be:

  1. “count the parts sold by supplier nation and customer nation”. nation would appear twice as two different groups for the same parts.count metrics - that is the nation entity assumes two roles (supplier nation and customer nation).

    The dynamic dataset for this would include:

    • nation.n_name USING (customer_nation) - nation of a customer
    • nation.n_name USING (supplier_nation) - nation of a supplier
    • parts.count - a metric (no role playing)
  2. “how many items are bought and supplied are in the same nation”. nation would act as a conformed dimension (same nation for both metrics). but the lineitem entity that has the data of items sold assumes two roles (items sold in a nation and items bought in nation).

    The dynamic dataset for this would include:

    • nation.n_name - nation name (no role playing)
    • lineitem.count USING (supplier_nation) - a metric counting lineitems supplied from the nation
    • lineitem.count USING (customer_nation) - a metric counting lineitems bought in the nation

Role playing is very important when using time spines - see next section.