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.

​
Setting Roles in a Domain

The simplest way to work with role played relationships is by using a domain.

A domain allows to choose roles in two ways:

  1. Set a default role to use: when there are multiple paths to an entity but only one is relevant within a business context, a domain can choose the one to always take.
  2. Set an alias for an entity with a role: when there are multiple paths to an entity that are all relevant in specific roles, a domain can provide aliases for entity under a role.

Domains are the recommended way to configure roles.

​
Ad-Hoc Role Playing

Ad-hoc role playing allows to choose a role dynamically within an expression.

Ad-hoc role playing is an advanced feature for cases where more flexibility is required than what a domain can offer.

​
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.

Was this page helpful?

Time MetricsTime Spines