template_definition

template_definition

Typed classes for Domo beast mode template definitions.

Models the /api/query/v1/functions/template/{id} API response as structured dataclasses with from_dict classmethods.

Structure

BeastModeTemplate ├── id: int # numeric template ID ├── name: str # display name ├── expression: str # SQL formula ├── legacy_id: str # calculation_xxx ID used in card definitions ├── status: str # e.g., "VALID" ├── data_type: str | None # e.g., "DECIMAL", "STRING", "LONG" ├── column_positions: list[ColumnRef] # columns referenced in the expression ├── non_aggregated_columns: list[str] # columns used without aggregation ├── locked: bool ├── hidden: bool ├── variable: bool ├── aggregated: bool ├── links: list[dict] # associated resources (cards, datasets) └── functions: list[str] # SQL functions used (e.g., "COUNT", "SUM")

BeastModeTemplate dataclass

BeastModeTemplate(
    id: int = 0,
    name: str = "",
    expression: str = "",
    legacy_id: str = "",
    status: str | None = None,
    data_type: str | None = None,
    column_positions: list[ColumnRef] = list(),
    non_aggregated_columns: list[str] = list(),
    locked: bool = False,
    hidden: bool = False,
    variable: bool = False,
    aggregated: bool = False,
    links: list[dict[str, Any]] = list(),
    functions: list[str] = list(),
    owner: int | None = None,
    archived: bool = False,
    _resolved_refs: dict[int, BeastModeTemplate] = dict(),
)

Typed representation of a beast mode template from the functions API.

Provides structured access to the beast mode's formula, column references, and metadata with convenience properties for lineage queries.

Usage

template = BeastModeTemplate.from_dict(api_response) template.referenced_columns # set[str] of source columns template.legacy_id # "calculation_xxx-xxx" for card def lookup template.to_formula() # convert to Formula for KpiDefinition

dataset_ids property

dataset_ids: set[str]

Dataset IDs this beast mode is linked to.

domo_beast_mode_refs property

domo_beast_mode_refs: list[int]

Template IDs referenced via DOMO_BEAST_MODE(nnn) in the expression.

Domo beast modes can reference other beast modes using the syntax DOMO_BEAST_MODE(template_id). This property extracts those numeric template IDs from the expression string.

Returns:

Type	Description
list[int]	List of integer template IDs referenced by this expression.

referenced_columns property

referenced_columns: set[str]

All dataset columns referenced by this beast mode.

Combines columnPositions and nonAggregatedColumns, stripping backticks from column names. Also includes columns from resolved DOMO_BEAST_MODE references.

resolved_expression property

resolved_expression: str

Expression with DOMO_BEAST_MODE refs replaced by their expressions.

After calling resolve_domo_beast_mode_refs, this returns the expression with DOMO_BEAST_MODE(nnn) replaced by the referenced beast mode's actual SQL expression. Falls back to the raw expression if not resolved.

from_dict classmethod

from_dict(obj: dict[str, Any]) -> BeastModeTemplate

Build a BeastModeTemplate from the template API response.

Parameters:

Name	Type	Description	Default
obj	dict[str, Any]	Full API response dict from /api/query/v1/functions/template/{id}	required

Source code in src/crew_dcs/classes/DomoBeastMode/template_definition.py

@classmethod
def from_dict(cls, obj: dict[str, Any]) -> BeastModeTemplate:
    """Build a BeastModeTemplate from the template API response.

    Args:
        obj: Full API response dict from /api/query/v1/functions/template/{id}
    """
    return cls(
        id=obj.get("id", 0),
        name=obj.get("name", ""),
        expression=obj.get("expression", ""),
        legacy_id=obj.get("legacyId", ""),
        status=obj.get("status"),
        data_type=obj.get("dataType"),
        column_positions=[
            ColumnRef.from_dict(cp) for cp in obj.get("columnPositions", [])
        ],
        non_aggregated_columns=obj.get("nonAggregatedColumns", []),
        locked=obj.get("locked", False),
        hidden=obj.get("hidden", False),
        variable=obj.get("variable", False),
        aggregated=obj.get("aggregated", False),
        links=obj.get("links", []),
        functions=obj.get("functions", []),
        owner=obj.get("owner"),
        archived=obj.get("archived", False),
    )

resolve_domo_beast_mode_refs async

resolve_domo_beast_mode_refs(
    auth: DomoAuth,
    *,
    context: RouteContext | None = None,
    **context_kwargs
) -> dict[int, BeastModeTemplate]

Fetch and resolve DOMO_BEAST_MODE(nnn) references in the expression.

Domo beast modes can reference other beast modes using the syntax DOMO_BEAST_MODE(template_id). This method fetches the referenced templates and stores them for use by resolved_expression and referenced_columns.

Parameters:

Name	Type	Description	Default
auth	DomoAuth	Authentication object for API requests	required
context	RouteContext | None	Optional RouteContext for request configuration	None

Returns:

Type	Description
dict[int, BeastModeTemplate]	Dict mapping template IDs to their resolved BeastModeTemplate instances.

Source code in src/crew_dcs/classes/DomoBeastMode/template_definition.py

async def resolve_domo_beast_mode_refs(
    self,
    auth: DomoAuth,
    *,
    context: RouteContext | None = None,
    **context_kwargs,
) -> dict[int, BeastModeTemplate]:
    """Fetch and resolve DOMO_BEAST_MODE(nnn) references in the expression.

    Domo beast modes can reference other beast modes using the syntax
    ``DOMO_BEAST_MODE(template_id)``. This method fetches the referenced
    templates and stores them for use by ``resolved_expression`` and
    ``referenced_columns``.

    Args:
        auth: Authentication object for API requests
        context: Optional RouteContext for request configuration

    Returns:
        Dict mapping template IDs to their resolved BeastModeTemplate instances.
    """
    from ...routes import beastmode as beastmode_routes

    context = RouteContext.build_context(context=context, **context_kwargs)

    refs = self.domo_beast_mode_refs
    if not refs:
        self._resolved_refs = {}
        return self._resolved_refs

    for template_id in refs:
        if template_id in self._resolved_refs:
            continue
        try:
            res = await beastmode_routes.get_beastmode_by_id(
                auth=auth,
                beastmode_id=str(template_id),
                include_hidden=True,
                context=context,
            )
            if res.is_success:
                self._resolved_refs[template_id] = BeastModeTemplate.from_dict(
                    res.response
                )
        except RouteError as e:
            # Best-effort: a ref that can't be fetched (deleted, no
            # permission, ...) is left out of _resolved_refs rather than
            # aborting the whole batch. Downstream consumers that need a
            # fully self-contained expression (e.g. OSI metric export)
            # must check for remaining DOMO_BEAST_MODE(...) tokens in
            # resolved_expression and treat that as a hard failure —
            # this method itself stays best-effort/logged, never silent.
            logger.warning(
                "resolve_domo_beast_mode_refs: failed to resolve "
                f"DOMO_BEAST_MODE({template_id}) referenced by beast mode "
                f"{self.id} ({self.name!r}): {e}"
            )

    return self._resolved_refs

to_formula

to_formula()

Convert to a Formula dataclass for merging into KpiDefinition.

Returns:

Type	Description
	Formula instance with id, name, formula, and column references
	populated from this template. If DOMO_BEAST_MODE refs have been
	resolved, resolved_formula will contain the human-readable
	expression with refs replaced by names.

Source code in src/crew_dcs/classes/DomoBeastMode/template_definition.py

def to_formula(self):
    """Convert to a Formula dataclass for merging into KpiDefinition.

    Returns:
        Formula instance with id, name, formula, and column references
        populated from this template. If DOMO_BEAST_MODE refs have been
        resolved, ``resolved_formula`` will contain the human-readable
        expression with refs replaced by names.
    """
    from ..DomoCard.kpi_definition import Formula

    resolved = None
    if self._resolved_refs:
        resolved = self.resolved_expression

    return Formula(
        id=self.legacy_id,
        name=self.name,
        formula=self.expression,
        resolved_formula=resolved,
        status=self.status,
        data_type=self.data_type,
        column_positions=self.column_positions,
        non_aggregated_columns=self.non_aggregated_columns,
        template_id=self.id,
        variable=self.variable,
        persisted_on_data_source=True,
        is_aggregatable=self.aggregated,
    )