# Best Practices

Source: https://userguide.qualytics.io/fields/computed-fields/deep-dive/best-practices/

Recommendations for authoring Computed Fields that stay understandable, easy to govern, and resilient to source-schema changes over time. Nothing here is enforced by the platform; treat it as a checklist you can walk before saving a new definition.

## Naming

- Use `snake_case` with a suffix that hints at the shape of the derived value: `_cast`, `_clean`, `_numeric`, `_bucket`, `_flag`.
- Prefer names that describe the derived value's meaning (`revenue_bucket`, `full_name`, `total_compensation`) rather than the transformation mechanic (`custom_expression_1`, `field_cleaned_v2`).
- Keep the name unique inside the container. Duplicates are rejected on Save.

## Choosing a Transformation Type

- Reach for **Cast** first when the only change you need is a data-type conversion. It is safer than a Custom Expression because Qualytics validates the target type up front.
- Use **Cleaned Entity Name** for repeatable business-signifier stripping (Inc., LLC, Ltd., Corp.) rather than a hand-written `REGEXP_REPLACE`. Term Settings are declarative and easier to review than a regex.
- Use **Convert Formatted Numeric** for currency amounts and other formatted-string inputs. It handles common patterns (commas, currency symbols, parentheses for negatives) without needing a Custom Expression.
- Reserve **Custom Expression** for logic that spans multiple fields, uses conditional branches, or requires a window function. Do not use it to reproduce something the other transformation types already do.

## Metadata and Discoverability

- **Description**: write one sentence that answers "what does this field represent to the business?" Not the expression, the semantics. A downstream reader searching for revenue metrics should recognize the field from the description alone.
- **Tags**: assign them at the container level so the field inherits them for cross-cutting facets like `domain:revenue-cycle`, `owner:finance-analytics`.
- **Additional Metadata**: freeform key/value pairs are the right home for facts that must travel with the field but do not fit a tag. Common patterns: `derived_from`, `business_owner`, `formula_source_of_truth`.

## Coping With Source-Field Drift

- **Avoid `SELECT *`-style logic.** In a Custom Expression, reference source fields by name. If a source field is renamed at the source, the Computed Field will surface it as a validation error rather than silently start producing null.
- **Watch the Missing status.** If a source field is dropped, the Computed Field marks its next profile as Missing. Restore the source field or edit the transformation to reference the new name.
- **Prefer expressions that tolerate nulls.** `COALESCE(field, default_value)` or `CASE WHEN field IS NULL THEN ... ELSE ... END` prevents null propagation from killing downstream aggregates.

## Reviewing Before Save

- **Let Save validate the definition.** Saving runs a quick profile that checks the transformation against the container's fields. An unknown field or a bad expression is reported on the modal and nothing is saved, which is cheaper than debugging a failed scheduled profile later.
- **Preview after Save.** The first profile that runs after Save populates the Computed Field's statistics. Open the field detail page and confirm the sample values look right before adding quality checks on top.

## Deletion and Sunsetting

- **Copy the transformation before deleting.** Deletion is irreversible: the definition and the derived value are removed together with any quality checks that targeted the field. Expected Schema checks stay and drop the field from their list.
- **Repoint or delete dependent quality checks first.** Quality checks pointing at the Computed Field are removed with the field. If teams still need those checks, repoint them or recreate the field before you delete.
- **Know what exclusion can suppress.** For a Cast, Cleaned Entity Name, or Convert Formatted Numeric field, excluding its source field also excludes the output and preserves the definition, though it stops monitoring the source field as well. A Custom Expression declares no source fields, so exclusion does not suppress it. Delete only when the Computed Field is permanently retired.

*Last updated: October 20, 2026.*