Monitor dynamic tables¶
You need the MONITOR or OWNERSHIP privilege on a dynamic table to view its metadata.
Choose a monitoring approach¶
Snowflake provides several monitoring surfaces. Use the following table to choose the right one for your situation.
| Approach | Best for | Data retention | Setup effort |
|---|---|---|---|
| SHOW DYNAMIC TABLES | Quick status checks, viewing refresh mode and warehouse | Current snapshot | None |
| INFORMATION_SCHEMA.DYNAMIC_TABLES() | Fleet-level health, lag metrics, last refresh outcome | 7 days | None |
| INFORMATION_SCHEMA.DYNAMIC_TABLE_REFRESH_HISTORY() | Per-refresh diagnostics: state, error, duration, trigger | 7 days | None |
| DYNAMIC_TABLE_REFRESH_HISTORY Account Usage view | Historical trend analysis beyond 7 days | 365 days | None |
| INFORMATION_SCHEMA.DYNAMIC_TABLE_GRAPH_HISTORY() | Pipeline dependency snapshots and topology changes | 7 days | None |
| Event table + alerts | Automated failure notifications | Configurable | Medium |
| Pipeline spans | Pipeline-level tracing and root cause analysis | Configurable | Medium |
For quick, ad-hoc checks, start with SHOW DYNAMIC TABLES or the DYNAMIC_TABLES table function. For automated alerting on refresh failures, set up an event table alert. For historical analysis beyond 7 days, use the Account Usage view.
Check refresh status¶
Check status with SHOW DYNAMIC TABLES¶
SHOW DYNAMIC TABLES returns the current state of your dynamic tables, including refresh mode, warehouse, scheduling
state, and last data timestamp. It is the only source for the refresh_mode, refresh_mode_reason, and warehouse
columns.
Note
SHOW DYNAMIC TABLES uses the scheduling state values RUNNING and SUSPENDED. The DYNAMIC_TABLE_GRAPH_HISTORY function uses ACTIVE and SUSPENDED instead. Both labels refer to the same operational state.
Check fleet health with the DYNAMIC_ TABLES function¶
The DYNAMIC_TABLES function returns lag metrics and the last refresh outcome for all dynamic tables in your account. Use it to identify tables that aren’t meeting their freshness targets.
A time_within_target_lag_ratio below 0.90 means the dynamic table isn’t meeting its freshness target most of
the time. Investigate the refresh history and consider adjusting the target lag or warehouse size.
View per-refresh history¶
The DYNAMIC_TABLE_REFRESH_HISTORY function returns one row per refresh, including the outcome, error details, duration, and trigger. Use it to investigate specific failures or track refresh trends.
To filter for only failed refreshes, pass ERROR_ONLY => TRUE:
Important
The DYNAMIC_TABLE_REFRESH_HISTORY table function retains data for 7 days. For trend analysis or investigating failures that occurred more than 7 days ago, query the DYNAMIC_TABLE_REFRESH_HISTORY Account Usage view, which retains data for 365 days.
Monitor pipeline health with DYNAMIC_ TABLE_ GRAPH_ HISTORY¶
The DYNAMIC_TABLE_GRAPH_HISTORY function returns the dependency graph of your dynamic tables, including upstream inputs, scheduling state, and target lag. Use it to understand your pipeline topology and detect configuration changes over time.
Each row represents a snapshot of a dynamic table’s properties. When you change a property (for example, the target
lag), a new row appears with an updated valid_from timestamp and the previous row gets a valid_to value.
To view the full dependency tree for a pipeline, query all dynamic tables that list a given table in their inputs
array:
View the pipeline graph in Snowsight¶
In Snowsight, the lineage graph visualizes upstream and downstream dependencies:
- Sign in to Snowsight.
- Select Transformation » Dynamic tables.
- Select your dynamic table. The Graph view is displayed by default.
- Select any dynamic table in the graph to view its lag metrics and configuration in the Details pane.
If a refresh failed with an UPSTREAM_FAILED status, the graph highlights which upstream dynamic table caused the failure.
Dynamic tables in ACCESS_ HISTORY¶
Dynamic table refresh operations are recorded in the ACCESS_HISTORY view:
- Refresh reads: The base tables read during a refresh appear in the
base_objects_accessedfield. - Refresh writes: The dynamic table being refreshed appears in
object_modified_by_ddlas a DDL ALTER operation withdynamicTableAction = 'REFRESH'. - User queries: SELECT queries against a dynamic table are recorded as standard table access.
Set up alerts with the event table¶
When a dynamic table refreshes, Snowflake can record a refresh.status event in the
active event table. You can create an alert that monitors
the event table and sends a notification when a refresh fails.
Note
Logging events for dynamic tables incurs costs. See Costs of telemetry data collection.
Set the event severity level¶
You must set the LOG_EVENT_LEVEL parameter before events are captured. If you don’t set it, no events are recorded.
Events are captured at the following levels:
ERROR: Refresh failure events only.WARN: Refresh failures and upstream failure events.INFO: All refresh events, including successes.
Set the level on the account, database, schema, or a specific dynamic table. For example, run
ALTER DYNAMIC TABLE dt_orders SET LOG_EVENT_LEVEL = WARN to capture WARN and ERROR events for a
specific table, or ALTER DATABASE mydb SET LOG_EVENT_LEVEL = INFO to capture all events for every
supported object in a database.
Important
Setting LOG_EVENT_LEVEL at the database, schema, or account level affects all object types that support event logging (dynamic tables, stored procedures, UDFs, tasks), not just dynamic tables.
Query the event table¶
After you set the severity level, query the event table to see refresh events. Filter on
resource_attributes:"snow.executable.type" = 'DYNAMIC_TABLE' to isolate dynamic table events.
To query for upstream failures instead, change the filter to value:state = 'UPSTREAM_FAILURE'. (The event table uses UPSTREAM_FAILURE; the DYNAMIC_TABLE_REFRESH_HISTORY function uses UPSTREAM_FAILED.)
Create an alert on refresh failures¶
An alert on new data triggers when new rows matching a condition are inserted into the event table. The following
example sends a Slack notification when any dynamic table in mydb fails to refresh.
Note
To create an alert on new data, you need a role with the required privileges to query the event table.
- For the default event table (SNOWFLAKE.TELEMETRY.EVENTS), see Event table default roles.
- For a custom event table, see Event table access control.
To create an alert that fires when dynamic table refreshes fail, use the Snowflake alerts feature with a condition
query against the event table. Filter on resource_attributes:"snow.executable.type" = 'DYNAMIC_TABLE' and
record:"severity_text" = 'ERROR' to detect failures, then send a notification (for example, through a Slack integration).
For alert creation syntax, scheduling options, and notification integration setup, see Setting up alerts.
Note
The timestamp column in the event table stores values in UTC. If you use a scheduled alert with a timestamp filter
instead of an alert on new data, convert the current timestamp to UTC:
Event table column reference¶
When a dynamic table refreshes, a row with the following values is inserted into the event table.
Key columns¶
| Column | Data type | Description |
|---|---|---|
timestamp | TIMESTAMP_NTZ | The UTC timestamp when the event was created. |
observed_timestamp | TIMESTAMP_NTZ | Currently the same as timestamp. |
resource_attributes | OBJECT | Attributes that identify the dynamic table. See Key-value pairs in resource_attributes. |
record_type | STRING | EVENT for dynamic table refreshes. |
record | OBJECT | Details about the refresh status. See Key-value pairs in record. |
value | VARIANT | The refresh state and, for failures, the error message. See Key-value pairs in value. |
Key-value pairs in resource_attributes¶
| Attribute | Type | Description | Example |
|---|---|---|---|
snow.database.name | VARCHAR | Database containing the dynamic table. | MY_DB |
snow.schema.name | VARCHAR | Schema containing the dynamic table. | MY_SCHEMA |
snow.executable.name | VARCHAR | Name of the dynamic table. | DT_ORDERS |
snow.executable.type | VARCHAR | Object type. Always DYNAMIC_TABLE for these events. | DYNAMIC_TABLE |
snow.query.id | VARCHAR | Query ID of the refresh. | 01ba7614-0107-e56c-0000-a995024f304a |
snow.warehouse.name | VARCHAR | Warehouse used for the refresh. | TRANSFORM_WH |
snow.owner.name | VARCHAR | Role with OWNERSHIP on the dynamic table. | DATA_ADMIN |
snow.owner.type | VARCHAR | The type of role that owns the object, for example | ROLE |
snow.database.id | INTEGER | Internal ID of the database. | 12345 |
snow.schema.id | INTEGER | Internal ID of the schema. | 12345 |
snow.executable.id | INTEGER | Internal ID of the dynamic table. | 12345 |
snow.owner.id | INTEGER | Internal ID of the owner role. | 12345 |
snow.warehouse.id | INTEGER | Internal ID of the warehouse. | 12345 |
Key-value pairs in record¶
| Key | Type | Description | Example |
|---|---|---|---|
name | VARCHAR | Event name. Always refresh.status for dynamic table refreshes. | refresh.status |
severity_text | VARCHAR | INFO (refresh succeeded), ERROR (refresh failed), or WARN (upstream dynamic table failed). | ERROR |
Key-value pairs in value¶
| Key | Type | Description | Example |
|---|---|---|---|
state | VARCHAR | SUCCEEDED, FAILED, or UPSTREAM_FAILURE. | FAILED |
message | VARCHAR | Error message when state is FAILED. NULL otherwise. | SQL compilation error: Object does not exist. |
Trace pipelines with spans¶
In addition to events, Snowflake can record pipeline spans for dynamic table refreshes. Events record individual refresh outcomes. Spans add pipeline-level context: correlated trace IDs, skip reasons, and dependency topology.
Spans capture states for which events are not emitted, including SKIPPED refreshes
due to upstream skips or scheduler load shedding.
Note
Recording spans for dynamic tables incurs costs. See Costs of telemetry data collection.
Enable pipeline spans¶
Set the TRACE_LEVEL parameter to ALWAYS at the schema or database level, for example
ALTER SCHEMA mydb.myschema SET TRACE_LEVEL = 'ALWAYS'.
Query span data¶
Filter for rows where record_type = 'SPAN' and record:"name" = 'table_refresh':
Span attributes (record_attributes)¶
| Attribute | Type | Description |
|---|---|---|
snow.dynamic_table.state | STRING | SUCCEEDED, FAILED, or SKIPPED. |
snow.dynamic_table.state_reason | STRING | Why the refresh was skipped or failed. NULL on success. Values: QUERY_FAILURE, UPSTREAM_FAILURE, UPSTREAM_SKIP, NOT_EFFECTIVE_TICK_TO_REFRESH. |
snow.dynamic_table.data_timestamp | STRING | The transactional timestamp when the refresh was evaluated. All data in base tables that arrived before this timestamp is included in the dynamic table. |
Correlate spans across a pipeline¶
When a refresh cycle includes multiple dynamic tables, all spans share the same trace:"trace_id". Each span also
includes a record:"links" array that lists the span_id of each upstream dependency.
To retrieve all spans from a single refresh cycle, use the trace:"trace_id" value from the span query output:
In this example, DT_ORDERS and DT_CUSTOMERS succeeded, DT_ENRICHED failed due to a query error, and DT_SUMMARY was automatically skipped
because its upstream dependency failed. The UPSTREAM_LINKS column shows each dynamic table’s direct dependencies
by span_id.
Trace the root cause of a failure¶
When a downstream dynamic table is skipped or fails, trace its upstream dependencies through the span links to find the root cause:
Use the query_id to investigate the failed query further with
GET_QUERY_OPERATOR_STATS or
the query history.
Dynamic table pipeline spans follow the OpenTelemetry data model. You can export them from the event table into OpenTelemetry-compatible tools for visualization.
Monitor dynamic tables in Snowsight¶
- Sign in to Snowsight.
- Select Catalog » Database Explorer.
- Select a database and schema, then select the Dynamic Tables tab.
- Select a dynamic table to view its details:
- Table Details: Scheduling state, last refresh status, current and target lag, refresh mode, tags, and privileges.
- Columns: Column names and types.
- Data Preview: Up to 100 rows of data.
- Graph: The pipeline dependency graph for this dynamic table.
- Refresh History: Per-refresh status, duration, lag metrics, and rows changed.
- Sign in to Snowsight.
- Select Transformation » Dynamic tables.
- View the scheduling state and last refresh status for all dynamic tables. Filter by database or schema to narrow results.
- Select a dynamic table and go to the Refresh History tab to see per-refresh details including status, duration, and lag.
What’s next¶
- To troubleshoot skipped or failed refreshes, see Troubleshoot dynamic table refresh issues.
- To look up specific error codes from failed refreshes, see Error code reference for dynamic tables.
- To diagnose slow refreshes and optimize performance, see Optimize queries for incremental refresh.
- To understand how target lag affects refresh scheduling, see Set the target lag for a dynamic table.
- To manage costs, see Understanding costs for dynamic tables.