type_bridge.expressions.role_player

role_player

Role-player expression for type-safe relation filtering.

This module provides a type-safe wrapper for filtering role players by their attributes in relation queries.

TypeDB 3.x Variable Scoping: TypeDB uses variable bindings to create implicit equality constraints. If the same variable is used twice in a match clause, both bindings must have the same value.

Wrong approach:
    $actor has name $name;    -- $name binds to actor's name
    $target has name $name;   -- CONSTRAINT: target's name must EQUAL actor's name!

Correct approach (unique variables):
    $actor has name $actor_name;    -- $actor_name binds to actor's name
    $target has name $target_name;  -- $target_name binds to target's name (independent)

This is why expressions generate ${var_prefix}_${attr_name} patterns.

RolePlayerExpr

RolePlayerExpr(role_name, inner_expr, player_types)

Bases: Expression

Type-safe expression for filtering role players by their attributes.

Wraps an attribute expression and associates it with a specific role, ensuring type safety and proper TypeQL variable scoping.

TypeDB 3.x Note: Variable names are prefixed with the entity variable to avoid collisions. Using the same variable twice creates an implicit equality constraint.

Example

If both actor and target have 'name' attribute:

$actor has name $actor_name; $actor_name contains "Bot"; $target has name $target_name; $target_name == "Resource1";

Parameters:

Name	Type	Description	Default
role_name	str	The role name (e.g., "employee", "employer", "actor")	required
inner_expr	Expression	The attribute expression to apply (e.g., Age.gt(Age(30)))	required
player_types	tuple[type[T], ...]	Tuple of allowed entity types that can play this role	required

Example

expr = RolePlayerExpr("employee", Age.gt(Age(30)), (Person,)) expr.to_typeql("$employee") '$employee has age $employee_age; $employee_age > 30'

Initialize a role player expression.

Parameters:

Name	Type	Description	Default
role_name	str	Name of the role being filtered	required
inner_expr	Expression	Attribute expression to apply to the role player	required
player_types	tuple[type[T], ...]	Tuple of entity types allowed to play this role	required

Source code in type_bridge/expressions/role_player.py

def __init__(
    self,
    role_name: str,
    inner_expr: Expression,
    player_types: tuple[type[T], ...],
):
    """Initialize a role player expression.

    Args:
        role_name: Name of the role being filtered
        inner_expr: Attribute expression to apply to the role player
        player_types: Tuple of entity types allowed to play this role
    """
    self.role_name = role_name
    self.inner_expr = inner_expr
    self.player_types = player_types

to_ast

to_ast(var)

Generate AST patterns using role-prefixed variable names.

Delegates to the inner expression with role variable.

Source code in type_bridge/expressions/role_player.py

def to_ast(self, var: str) -> list[Pattern]:
    """Generate AST patterns using role-prefixed variable names.

    Delegates to the inner expression with role variable.
    """
    return self.inner_expr.to_ast(var)

get_attribute_types

get_attribute_types()

Get all attribute types referenced by this expression.

Delegates to the inner expression.

Returns:

Type	Description
set[type[Attribute]]	Set of attribute types used in this expression

Source code in type_bridge/expressions/role_player.py

def get_attribute_types(self) -> set[type[Attribute]]:
    """Get all attribute types referenced by this expression.

    Delegates to the inner expression.

    Returns:
        Set of attribute types used in this expression
    """
    return self.inner_expr.get_attribute_types()

__repr__

__repr__()

Return string representation for debugging.

Source code in type_bridge/expressions/role_player.py

def __repr__(self) -> str:
    """Return string representation for debugging."""
    return (
        f"RolePlayerExpr(role_name={self.role_name!r}, "
        f"inner_expr={self.inner_expr!r}, "
        f"player_types={self.player_types!r})"
    )