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

  • Validate before saving. The modal validates the transformation against the container's field schema. Catching an unknown field or bad expression during authoring is cheaper than debugging a failed profile.
  • 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.
  • 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.
  • Prefer exclusion for temporary suppression. Excluding a source field also excludes the Computed Field's output but preserves the definition, so restoration is straightforward. Delete only when the Computed Field is permanently retired.