Validate content in a data model (Beta)

Validate content to prevent cases where deleting a column or element causes errors in documents that rely on the data model. Instead of manually replacing and updating columns and elements in affected documents, you can validate content in the data model and prevent these errors.

Breaking changes prevented by validating content

When certain breaking changes are made to a data model, the Publish option indicates that the model contains changes that break the structure of the model in the time since it was last published. When you click Publish, you are prompted to validate the content of your data model.

When comparing the changes made to a data model with the latest published version, the following changes might require validating content:

• Delete an element.
• Delete a column, including the following cases:
  • Delete a column and add it back from the Source columns list.
  • Delete a calculated column and remake it, even if you use the same name.
• In some cases, changing the source of the data model or an element.

Some changes can cause data to be unavailable to downstream elements that depend on the data in the data model, but cannot be fixed by performing content validation:

• Deleting a metric on an element

• Deleting a relationship between elements

• Deleting a column that is available in a relationship

• Making a change to data in your data platform, such as:

  • Performing a CREATE OR REPLACE operation on a table or view.
  • Deleting a column in a table or view.

Other changes that you make to your data model do not require performing content validation. For example, renaming a column or disabling an element as a source. In those cases, the data remains available to any elements using it downstream.

If a column is unavailable and not repaired through content validation, you might see errors such as "Invalid Query: Column...", "Unknown Column [Element name/ABCdefGH1i]", or "Column "[Element name/ABCdefGH1i]" does not exist".

Requirements

• You must be assigned an account type with the Create, edit, and publish datasets permissions enabled.
• You must be the data model owner or be granted Can edit access to the data model.

📘

To ensure that documents that depend on the data model do not break, content validation can make changes to documents that the user publishing the data model cannot access.

Considerations when validating content

When you validate the content in your data model, consider the following:

• Content validation jobs can take some time to run. If you perform content validation when other jobs are running in your organization, such as a large volume of scheduled exports, the job can be slower. Review the progress at any time in the job history. See Review content validation job results for a data model.
• Content validation does not make changes within a data model. If you delete a column from an element that is used by child elements in the same data model, you must map the column for each affected element. If you map the column for only the parent element, other elements in the data model remain broken.
• Content validation does not update related columns. If you remove a column that is used in a relationship in your data model, even if you validate content, the related column will be unavailable downstream after publishing changes.
• The list of documents that use the elements with breaking changes as a source are shown even if the documents do not use any deleted columns.

Some documents are not updated by content validation:

• Explorations are not updated by content validation. Instead, a user is prompted to update sources the next time they open the exploration for editing.
• An unpublished draft of a workbook that uses the data model is not updated by content validation if the published version of a workbook does not use the data model. Instead, a user in the draft is prompted to update sources the next time they open the draft.
• An unpublished draft of an embedded workbook is not updated by content validation. As a result, users that edit embedded workbooks that depend on a data model that required validating content might experience invalid columns or errored elements.

Validate the content in your data model

If you make breaking changes in your data model, validate the content to reduce the likelihood that your changes will cause errors in workbooks and data models that use the data model elements downstream.

1. When editing a data model, the Publish button displays a warning icon () and indicates that you have breaking changes. Click Publish to start validating content.

   💡

   You can also click the down arrow () next to Publish and select Validate content.

   The Content validation modal appears, listing deleted columns and deleted elements. Sigma attempts to map possible replacement columns for the deleted columns based on name.

   

   Top documents that use the affected elements as a source and that were viewed in the last 60 days are listed under Downstream lineage, helping you assess the impact of failing to validate content.

   The list of affected documents is not exhaustive, and might list documents that do not use affected columns. To view an exhaustive list, review the lineage of the data model. Content validation updates all affected documents, even those not listed.

2. In the Content validation modal, perform the following steps for every element with breaking changes:

   • If you deleted a column:

     1. For each deleted column in the Deleted columns list, review the suggested replacement columns.

     2. If the column mapping lists None, review the column list for other columns of the same data type in the element that might map to the deleted column.

        

     3. If a relevant replacement column exists, select it. Otherwise, leave the default None. If you map the column to None, any elements that use the column downstream display an error after the data model is published.

        

     4. (Optional) If you want to replace the element with the deleted column(s), select Edit () and choose a replacement element. All columns appear as deleted columns. If needed, map any unmapped columns. You can turn on the Hide mapped columns toggle to see only the columns without a replacement.

   • If you deleted an element:

     1. In the Element section, review the name of the deleted element to confirm which element you are mapping to a replacement. By default, the element is mapped to "Do not replace downstream".

        

     2. Select Do not replace downstream to review a drop-down list of other elements in the data model.

     3. If a relevant replacement element exists, select it. Otherwise, leave the default Do not replace downstream. If you do not replace the deleted element in content validation, any elements that use the deleted element as a source display an error after the data model is published.

     

3. After performing content validation for every affected element in your data model, select Publish changes.

   🚩

   You can choose Publish without validation, but any mappings that you performed to validate content in the data model are not applied. If any deleted columns or elements are used in documents downstream of the data model, elements display "Object Does Not Exist: Data model element not found" and prompt the user to add a source, or display "Invalid Argument: Missing element".

After publishing changes, the content validation job starts to update affected documents. For long-running jobs, documents might show errors for affected columns or elements until the content validation job runs for the document. You can view the status of the job in your data model. Click the down arrow () next to Publish and select Content validation job history.

Users with edit access to workbooks and data models that use the data model as a source are prompted to sync the draft to the latest published version. For more details, see Sync a draft with the latest published version.

Updates performed by content validation

After you publish changes, the following happens:

1. The latest published version of any documents that use the relevant elements in the data model are updated. Documents are updated sequentially.

2. If a user is viewing a draft of the document, they are prompted to sync the draft to the latest published version. For more details, see Sync a draft with the latest published version

   📘

   Not all drafts can be updated by content validation. For details, see Considerations when validating content.

3. After all documents are updated, the job is complete.

flowchart LR
    A --> B[Content validation job starts]
    B --> C[Published versions of downstream documents updated]
    C --> D{User viewing draft?}
    D -->|Yes| E[Prompt to sync draft with published version]
    D -->|No| F[Validation complete]
    E --> F

Review content validation job results for a data model

1. While editing a data model, open the publish menu, then select Content validation job history.

   The Content validation job history modal opens.

2. Review the history of content validation jobs performed for the data model. Jobs are listed by start time.

3. Select a job to review the following information:

   • The status of the job. For example, Pending.
   • The user that triggered the content validation job.
   • When the job started and when it was completed.
   • The list of updated documents, status, and when the job was started and completed for each document.