> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://help.sigmacomputing.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.sigmacomputing.com/_mcp/server. # Audit changes to Sigma tables (Beta) > View Sigma table audit logs. See data and schema changes over time with details about what each edit changed, who made it, and when it occurred. > **Note** > > This documentation describes one or more public beta features that are in development. Beta features are subject to quick, iterative changes; therefore the current user experience in the Sigma service can differ from the information provided in this page. > > This page should not be considered official published documentation until Sigma removes this notice and the beta flag on the corresponding feature(s) in the Sigma service. For the full beta feature disclaimer, see [Beta features](/docs/sigma-product-releases#beta-features). Reference the Sigma table audit logs to see who made specific data and schema edits, when the edits occurred, and what they changed. Sigma table audit logs are append-only tables Sigma creates in your data platform. You can view an audit log and add it to a workbook the same way you would any other table in the connection. Each entry in the audit log records details about an individual data or schema change that was attempted or committed. This document explains how to create, view, and interpret the audit log for a specific Sigma table. For information about enabling audit logging for Sigma tables, see [Configure audit logging for Sigma tables](/docs/configure-audit-logging-for-sigma-tables). ## Requirements To create an audit log for a specific Sigma table: * Audit logging must be enabled on the connection containing the Sigma table. See [Configure audit logging for Sigma tables](/docs/configure-audit-logging-for-sigma-tables). * The Sigma table must have write access enabled. See [Enable write access on a connection table](/docs/enable-write-access-connection-tables). To view an existing audit log for a specific Sigma table: * On a non-OAuth connection, you must be granted **Can use** or **Can use & annotate** access on the audit log itself. See [Configure access for organization-wide Sigma tables](/docs/configure-data-access-for-org-wide-sigma-tables#grant-user-access-to-sigma-table-audit-logs-in-sigma). * On an OAuth connection, you must be granted relevant access to the audit log schema and table itself in your data platform. See [Configure access for organization-wide Sigma tables](/docs/configure-data-access-for-org-wide-sigma-tables#oauth-connection). ## Considerations and limitations * If audit logging on the connection or write access on the Sigma table are disabled after an audit log is created, Sigma stops recording new entries, but you can still view the audit log. * Sigma tables are standard database tables that external systems can also write to. An audit log records only the edits applied through Sigma. Changes made directly in your data platform aren't captured. * When an admin edits a Sigma table while impersonating a user, the audit log attributes the edit to the impersonated user, not to the admin who performed it. Impersonation itself is recorded in your organization's audit log, which identifies both the impersonated user and the impersonating admin. For more information, see [Impersonate users](/docs/impersonate-users) and [Access and explore audit logs](/docs/access-and-explore-audit-logs). ## How Sigma table audit logs work Sigma creates and manages each audit log as a standard database table in the Sigma table's connection. As Sigma applies each edit to the Sigma table, it writes corresponding entries to the audit log, capturing each state the edit reaches (i.e., attempted, committed, or errored). Every entry records the user who made the edit, when it occurred, and what changed. The following sections cover key behaviors of Sigma table audit logs: * [Data retention](#data-retention) * [Incremental edit history](#incremental-edit-history) * [Audit log integrity](#audit-log-integrity) ### Data retention Sigma table audit logs have no retention period and are append-only, so Sigma never overwrites or deletes an existing entry. Because the data is stored in your data platform, you have full control over how long data in an audit log is preserved. The audit log does, however, reference materialized tables used for bulk edit actions (single actions that insert, update, or delete multiple rows in a Sigma table), and Sigma retains these materialized tables for 30 days. When Sigma deletes a materialized table at the end of the retention period, audit log entries continue to reference it (existing entries are never changed), but its data can no longer be retrieved. To retain the materialized tables for extended periods, copy or export them to another location. For more information about materialized tables for bulk edit actions, see [Create actions that modify Sigma table data](/docs/create-actions-that-modify-sigma-table-data). ### Incremental edit history The audit log records details about individual edits, with each entry capturing new values written by the edit, not the values it replaced. An audit log therefore represents a history of edits instead of a point-in-time snapshots of a Sigma table. > **Tip** > > To determine previous values, reference the `EDIT` column in earlier row-based entries with matching `primaryKey` values (identifying the affected Sigma table rows) and relevant column names in `updates`. For bulk edit actions, you can query the materialized table during its 30 day retention period to retrieve the row-level edits. ### Audit log integrity Audit logs are critical for maintaining Sigma table editability. If Sigma is unable to write to an audit log, edits to the Sigma table fail until the audit log is restored. Within Sigma, audit logs are protected from edits that could compromise their integrity and leave Sigma tables uneditable. In your data platform, however, Sigma cannot prevent direct modifications to audit log tables. To maintain audit log integrity and ensure Sigma tables remain editable, avoid making the following changes outside of Sigma: * Rename an audit log table * Delete an audit log table * Delete or alter an audit log's columns * Moving an audit log's table > **Warning** > > Sigma's protection against making an audit log writable applies only to the connection that manages it. If you create a second connection to the same underlying database, Sigma cannot recognize the table as an audit log, and it won't prevent write access from being enabled on it. An audit log made writable this way carries the same risk as one modified directly in your data platform: the audit log's integrity can be compromised, and the corresponding Sigma table can lose editability. ## Open or create an audit log While viewing a Sigma table in the data catalog, you can check the **Access** tab to determine whether or not a corresponding audit log exists. From there, you can open the audit log or create one if it doesn't yet exist. > **Tip** > > If you know the audit log exists, you can browse to it directly in the data catalog, without going through the Sigma table. Open the audit log schema and select the audit log table. If you don't know the audit log table name, see [Audit log table naming](#audit-log-table-naming). > > *This path to an audit log is only possible if the audit log schema is available in the data catalog. For example, if the connection's audit log schema is the same as its write schema, you aren't able to browse the data catalog for audit logs because the write schema is excluded from the data catalog.* 1. Use one of the following methods to open a Sigma table in the data catalog: * From **Home**: 1. Go to the **Connections** page and select the relevant connection. 2. In the data catalog, locate and select the Sigma table you want to view. * From a workbook: 1. Select the Sigma table. 2. Go to the **Properties** panel. 3. In the **Data source** section, click the down arrow (![](https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Icons/caret.svg)) next to the Sigma table's name, then select **View table** in the menu. 2. Select the **Access** tab. 3. In the **Audit log** section, follow the guidance based on the button you see: * **View audit log**: Indicates an audit log exists. Click to open it in the data catalog. * **Create audit log**: Indicates that Sigma table audit logging is enabled on the connection but an audit log has not been created for the Sigma table. Click to create one and open it in the data catalog. * **Create audit log** (disabled): Indicates that Sigma table audit logging isn't enabled on the connection. Contact an admin to enable it. * No button: Indicates that the Sigma table does not have write access enabled. Contact an admin to enable it. ## Interpret a Sigma table audit log A Sigma table audit log is a raw database table, and interpreting it can require knowing its naming pattern, available columns, and the values those columns can contain. The following sections cover the information you may need to interpret a Sigma table audit log: * [Audit log table naming](#audit-log-table-naming) * [Audit log entry columns](#audit-log-entry-columns) * [Audit log status entries](#audit-log-status-entries) * [Audit log edit types](#audit-log-edit-types) ### Audit log table naming Sigma uses the following table naming pattern when creating audit logs. ``` SIG_AUDIT_LOG__ ``` Data platforms have identifier limits that can require Sigma to trim the audit log name. If the full name exceeds the limit, Sigma preserves the `SIG_AUDIT_LOG_` prefix and the UUID. Together, these values reserve 51 characters, so your connection's identifier limit determines how much of the Sigma table name is included in the audit log name. | Connection | Identifier limit | Sigma table name truncated at | | ---------- | ---------------- | ----------------------------- | | Snowflake | 128 characters | 77 characters | | Databricks | 128 characters | 77 characters | | PostgreSQL | 63 characters | 12 characters | ### Audit log entry columns Every audit log entry provides details across the following eight non-nullable columns. | Column | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | ID1 | Unique identifier for the edit. All entries for the same edit share this value. | | STATUS1 | The state the edit reached when Sigma created this entry. See [Audit log status entries](#audit-log-status-entries). | | STATUS_AT_UTC | When the edit reached the state recorded in `STATUS`, in UTC. | | USER_EMAIL | Email address of the person who made the edit. If the edit was made while impersonating another user, this records the impersonated user's email address. | | CREATED_AT_UTC | When Sigma created this entry, in UTC. | | ACTION | Whether the edit changed data or schema. Values are `DATA_CHANGE` and `SCHEMA_CHANGE`. | | EDIT_NAME | The operation the edit performed. See [Audit log edit types](#audit-log-edit-types). | | EDIT | The edit itself, as JSON. For a bulk edit action backed by a materialized table, this contains the name of that table instead. | 1 An edit that reaches multiple states appears as multiple entries sharing an `ID` but differing by `STATUS`. Togeter, `ID` and `STATUS` form the table's primary key. ### Audit log status entries Sigma writes one entry per state an edit reaches, so most edits appear twice: first as `ATTEMPTED`, then as `COMMITTED` or `ERRORED`. | Status | Description | | --------- | ----------------------------------------------------------- | | ATTEMPTED | Sigma is processing the edit to the Sigma table. | | COMMITTED | Sigma applied the edit and your data platform confirmed it. | | ERRORED | The edit failed. The Sigma table is unchanged. | An edit can commit or fail without Sigma receiving confirmation. When that happens, the audit log contains the `ATTEMPTED` entry with no corresponding `COMMITTED` or `ERRORED` entry. ### Audit log edit types The `EDIT_NAME` column identifies the operation an edit performed, and the `EDIT` column holds its specifics as JSON. For data changes, the source key also indicates where the affected rows came from: `updatesSource` and `rows` for rows specified in Sigma, and `updatesTableSource` and `tableSource` for rows read from a source table. | Edit name | Action | Description | | -------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------- | | create_table | SCHEMA_CHANGE | Created the Sigma table with the columns and primary key defined in `EDIT`. | | add_columns_if_not_exists | SCHEMA_CHANGE | Added the columns defined in `EDIT`. Existing columns were unchanged. | | change_column_type | SCHEMA_CHANGE | Changed the column to a different data type. Column name and new data type both defined in `EDIT`. | | change_column_name | SCHEMA_CHANGE | Renamed the column. Previous and new column names defined in `EDIT`. | | drop_columns | SCHEMA_CHANGE | Dropped the columns defined in `EDIT` from the Sigma table. | | change_table_name | SCHEMA_CHANGE | Renamed the Sigma table to the name provided in `EDIT`. | | set_primary_key | SCHEMA_CHANGE | Composed the Sigma table's primary key from the columns defined in `EDIT`, dropping any preexisting primary key. | | insert_on_duplicate_ignore | DATA_CHANGE | Inserted the rows defined in `EDIT`, skipping any row that matched and existing primary key. | | insert_on_duplicate_update | DATA_CHANGE | Inserted the rows defined in `EDIT`, updating any row that matched and existing primary key. | | update | DATA_CHANGE | Updated existing rows defined in `EDIT` that match a primary key. Rows without a match were unchanged. | | delete | DATA_CHANGE | Deleted the rows identified in `EDIT`. | ## Analyze audit log data in a workbook Add an audit log to a workbook to view and analyze its data. Use one of the following methods: * [Add an audit log to an existing workbook](#add-an-audit-log-to-an-existing-workbook) * [Explore an audit log from the data catalog](#explore-an-audit-log-from-the-data-catalog) ### Add an audit log to an existing workbook 1. Open the draft of an existing workbook you want to update. 2. In the **Add element** bar, select **Data** > **Table**. 3. In the **Select source** modal, locate and select the audit log table. 4. Filter, sort, or visualize the table to analyze the data. ### Explore an audit log from the data catalog 1. Open the audit log in the data catalog. See [Open or create an audit log](#open-or-create-an-audit-log). 2. Click **Explore** to open the audit log in an exploration. 3. Filter, sort, or visualize the table to analyze the data. ## Related resources * [Sigma tables overview](/docs/sigma-tables-overview) * [Configure audit logging for Sigma tables](/docs/configure-audit-logging-for-sigma-tables) * [Configure access for organization-wide Sigma tables](/docs/configure-data-access-for-org-wide-sigma-tables) * [Edit a Sigma table's data or schema](/docs/edit-sigma-tables) * [View input table audit history](/docs/view-input-table-audit-history) * [Impersonate users](/docs/impersonate-users) * [Access and explore audit logs](/docs/access-and-explore-audit-logs)