Horizon Iceberg REST Catalog operations in ACCESS_HISTORY¶

The ACCESS_HISTORY view contains records for successful operations performed against the Iceberg REST Catalog (IRC) APIs in Snowflake Horizon Catalog. These records are generated when external query engines (such as Spark, Trino, DuckDB, or PyIceberg) call the Horizon IRC APIs against Snowflake-managed Apache Iceberg™ tables. They complement the existing records that ACCESS_HISTORY generates for SQL statements executed inside Snowflake.

You can identify IRC-sourced records by filtering on the event_source column:

SELECT *
FROM SNOWFLAKE.ACCOUNT_USAGE.ACCESS_HISTORY
WHERE event_source = 'horizon_irc';

Records are retained for 365 days, the same as other rows in the view.

Coverage¶

All Horizon IRC catalog operations on Snowflake-managed Iceberg tables are captured, including loadTable, updateTable, createTable, dropTable, and others. As a result, the view records the following kinds of activity that external engines perform through the IRC APIs:

• Reads (for example, loadTable and metadata fetches).
• DML operations (append, overwrite, delete, truncate).
• DDL operations (CREATE, ALTER, DROP, RENAME).

For more information about the Horizon IRC APIs, see Access Apache Iceberg™ tables with an external engine through Snowflake Horizon Catalog.

Columns used for Horizon IRC events¶

The following table describes the columns in the ACCESS_HISTORY view that identify and describe Horizon IRC events.

additional_properties for horizon_irc events¶

For records where event_source = 'horizon_irc', the additional_properties column is a JSON object that contains the irc_event_type property. The value of irc_event_type identifies the type of Iceberg operation the external engine performed through the IRC API (for example, LoadTable, CreateTable, or UpdateTable).

For UpdateTable events, the object also includes the specific Iceberg operation (for example, append, overwrite, delete, or truncate) along with the parentSnapshotId and snapshotId fields for the affected table.

The following examples show the shape of additional_properties for each event type.

A LoadTable event (a read or metadata fetch):

{
  "irc_event_type": "LoadTable"
}

A CreateTable event (a table created through the IRC API):

{
  "irc_event_type": "CreateTable"
}

An UpdateTable event (for example, an append, overwrite, delete, or truncate):

{
  "irc_event_type": "UpdateTable",
  "operation": "append",
  "parentSnapshotId": 6642918349264338485,
  "snapshotId": 2245239255680098558
}

Sample query: IRC events for a specific table¶

The following query returns Horizon IRC audit events for a specific Iceberg table over the last 90 days. Reads land in direct_objects_accessed, and all writes (DML and DDL) land in object_modified_by_ddl, so a single LATERAL FLATTEN over the concatenation of both covers every operation.

SELECT DISTINCT
  h.query_id,
  h.query_start_time,
  h.user_name,
  h.direct_objects_accessed,
  h.objects_modified,
  h.object_modified_by_ddl,
  h.additional_properties
FROM SNOWFLAKE.ACCOUNT_USAGE.ACCESS_HISTORY h,
LATERAL FLATTEN(input =>
  ARRAY_CAT(
    NVL(h.DIRECT_OBJECTS_ACCESSED, ARRAY_CONSTRUCT()),
    ARRAY_CONSTRUCT(h.OBJECT_MODIFIED_BY_DDL)
  )
) f
WHERE h.QUERY_START_TIME >= DATEADD('day', -90, CURRENT_TIMESTAMP())
  AND h.EVENT_SOURCE = 'horizon_irc'
  AND f.VALUE:objectName::STRING = '<fully_qualified_table_name>'
ORDER BY h.QUERY_START_TIME DESC;

Usage notes¶

• Only successful IRC operations are recorded. Failed IRC API calls are not logged.
• The user_name for IRC records is the Snowflake user that authenticated the IRC client (typically a service account configured with a programmatic access token).
• Latency, truncation, and other behaviors are the same as for other rows in the view. For details, see the ACCESS_HISTORY usage notes.