This document describes how to configure and schedule dataset and workbook materializations to improve the speed and performance of your reports. 

Workbook Materialization is currently in Beta and available by request only. The feature is subject to quick, iterative changes, and the latest product version may differ from the content of this document. To enable Workbook Materialization in your Sigma organization, contact your Sigma Account Executive or submit a request via Support.



  • Write access must be enabled on your dataset’s connection.
  • You must be an organization Admin or be assigned a custom account type with materialize permissions.


Materializations allows you to write datasets and workbook elements back to your warehouse as tables which can reduce compute costs. Materialization enhances query performance by allowing your data warehouse to avoid recomputing the dataset when it's used by an element or a in descendant Sigma analysis. 

Materializations are stored in your warehouse and saved in scratch workspace schema automatically managed by Sigma. Sigma's query compiler automatically and transparently uses the latest materialization.

Schedule Materialization

A materialization is created through the act of scheduling a materialization. The materialization schedule can impact the data freshness for datasets and all downstream documents. Long running queries that do not display in Sigma can still be materialized.

Create a Dataset Materialization Schedule

  1. Open the dataset you would like to materialize.
  2. Click on the Materialization tab.

    company apps

  3. Click Create Schedule to open the Materialization Schedule modal.
  4. Set the schedule for when you would like your dataset to materialize.

    company apps

  5. Click Save

Edit a Materialization Schedule

  1. Open the dataset.
  2. Click on the Materialization Tab.
  3. Click the ••• icon next to Run Now.
  4. Click Edit Schedule to open the Materialization Schedule.

    company apps

  5. Select a new schedule.

    company apps

  6. Click Save.

Run a Scheduled Materialization 

Follow the instructions below to manually run a scheduled materialization. 

  1. Open the dataset.
  2. Go to your dataset’s Materialization tab.
  3. Click the Run Now button in the schedule header.

Delete a Materialization Schedule (and Materialized Tables)

When a materialization schedule is deleted, Sigma will automatically remove the materialized table from your warehouse. It can take up to 24 hours for the table to be deleted.

  1. Open the dataset.
  2. Click the Edit button in the top right corner of your screen.
  3. Go to your dataset’s Materialization tab.
  4. Click the ••• icon next to the Run Now button in the schedule header.
  5. Click Remove Schedule.

Pause Scheduled Materializations

By default, Sigma pauses scheduled materializations that have not been used for 60 days.

To change this behavior, follow these steps:

  1. Navigate to the Materializations section in the Administration panel.
  2. At the top of the Materialization page, change your options to reflect your business requirements:
    Select this option if you never want to stop materializations.
    If materialized table ...
    Retain this option of you wan to pause materializations that are not in use. 
    The default setting is 60 days; adjust as necessary.
    Pause schedule for materializations

Create Materializations in Workbooks

 Workbook materialization is similar to datasets, with the following differences:

  • It allows you to materialize any workbook element (table, visualization, pivot) that can be used as a data source for another element.
  • Materializations are used when viewing and editing a workbook. Datasets don't use the materialization in edit mode.
  • Workbook materialization offers a smarter refresh when published. Publishing a document only refreshes the materialization if necessary. For example, if the materialized element hasn't changed, materialization doesn't run. Datasets always refresh the materialization on publish.
  • It offers support for different levels of reference. Grouping levels can be independently materialized. Datasets only materialize at one grouping level.
  • It pushes status changes. The workbook viewer is notified of Materialization activity in a new "alerts" center (to be integrated with in-app notifications) and toasts.

Follow the instructions below to materialize a workbook element.

  1. Select the element menu from the top-right corner of the element you want to materialize.
  2. Select Schedule materialization.

    company apps

  3. In the Materializations Schedules section, set a schedule to materialize data elements. 

    A materialization can only have one schedule, but a schedule can have multiple materializations.

    company apps

  4. If an element contains multiple grouping levels, select a grouping level to materialize. To materialize multiple grouping levels, select Add Element and add the element for each additional grouping level.

    company apps

    It's often unnecessary and potentially costly to materialize the most granular level of an element (indicated in the UI as All source columns).

  5. Click Save Schedules.

    When you publish edits to a workbook, the materialization is initiated.

  6. To verify the success of your materialization, you will see a check marks on the element’s menu. 

    company apps

    The lineage view also indicates that a materialization exists for the element and is available for query optimizations.

    company apps

View Complete Materialization List

A complete list of your organization's materialization schedules can be found in your Admin Portal. 

  1. Go to the Admin Portal.
  2. Click Materializations in the left panel to open the Materialization page.
  3. You can search Materializations and click the Document name to open the workbook. 
    In the Status column, you can verify if a materialization was successful.
    Last Refresh 

    company apps

View Materialization Logs and Statistics

Logs and statistics for each of your organization's materialization runs can be found in the Usage Dashboard within the Admin Portal. 

  1. Go to the Admin Portal.
  2. Click Usage in the left panel and then select the Materialization tab.
  3. From here you can browse statistics about all your organization's materialization runs as well as logs for each run in the table called Materialization Log.

View Materialized Tables in your Warehouse

To schedule materializations, you must enable write access on your connection. All materialized tables automatically write to the specified schema.

These tables are visible in your cloud data warehouse. However, they're not intended to be used as source tables for other applications. To access this data from other applications, see Sigma’s Dataset Warehouse Views feature.

Don't make changes to the materialized tables directly in your database. This can result in unexpected results or query failures.

View Materialized Tables in Sigma

If materialization exists on a dataset, the materialization status will appear on the dataset header information popup. To view these details:

  1. Click on the information icon in the dataset header. This opens the dataset information popup.
  2. To view additional details, hover over the materialization status.

Admins can view the status and history of materializations from a dataset’s Materialization tab at any time.

Materialized tables aren't displayed in Sigma’s connection browser. To use a table for further analysis, build that analysis on top of the associated dataset.

Troubleshooting Q&A

Question: My materialized Dataset is suddenly showing a “materialization disabled” error. Why?
Answer: A dataset’s materialization schedule can become disabled if the dataset or any underlying Datasets have been altered such that they no longer support materialization.

To learn more, check out materialization limitations.
To explore upstream sources, visit your Dataset’s Lineage tab.
To explore joined sources, visit your Dataset’s Links tab.

Question: My scheduled materialization is failing. Why? How can I fix it?
Answer: Materialization can fail for a number of reasons. Admin users can view logs for each materialization run inside the Usage Dashboard. Explicit error messages will appear in there. 

We recommend checking the dataset for new column errors or materialization limitations. The source of failed materialization can also lie in errors within your dataset’s Lineage and Links.

When a materialization fails, the dataset uses the last successful materialization.


  • Materialization isn't available for datasets that use parameters or system functions. These datasets are expected to return different values when their parameters change. Materialized tables, on the other hand, always return the same value - the fixed output of the dataset at the time the materialization was run. As a result, using the materialized versions of datasets that use parameters or system functions would produce unexpected results.
  • Materialization is incompatible with row-level security. The materialization will error if row-level security (user attributes) functions are referenced.
  • Datasets referencing other datasets, by means of duplication or joins, can typically be materialized. However, this isn't true if any underlying dataset(s) cannot be materialized.

Was this page helpful?
Yes No