Skip to content

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.