Audit changes to Sigma tables (Beta)

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.

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.
• The Sigma table must have write access enabled. See Enable write access on a connection table.

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.
• 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.

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 and 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
• Incremental edit history
• 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.

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.

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

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.

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 () 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 entry columns
• Audit log status entries
• Audit log edit types

Audit log table naming

Sigma uses the following table naming pattern when creating audit logs.

SIG_AUDIT_LOG_<SIGMA_TABLE_NAME>_<UUID>

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.

Audit log entry columns

Every audit log entry provides details across the following eight non-nullable columns.

1An 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.

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.

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
• 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.
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
• Configure audit logging for Sigma tables
• Configure access for organization-wide Sigma tables
• Edit a Sigma table’s data or schema
• View input table audit history
• Impersonate users
• Access and explore audit logs