Skip to main content

About audit events

Important

This feature is only available for Private instance and Single Tenant instance installations.

Audit events allow administrators to monitor the actions performed by all the users in the data.world application through the UI or while using API. The audit log reporting functionality enhances the accountability of actions in the application. Administrators can track the actions taken by users in the application and find the root cause of issues by identifying the resources on which the action was performed and who performed the action.

Event types that are tracked include:

  • Resource creation

  • Resource deletion

  • Metadata edits

  • Suggest changeevents, such as change suggested, change rejected, change accepted, suggestion cancelled.

Audit events are captured for the following resources:

  • All metadata catalog resources including but not limited to:

    • Collections

    • Database resources such as tables and columns

    • Analysis resources such as dashboards

    • Business glossary items

    • All custom resources defined in your metadata profile

  • Datasets (Note that events are not captured for adding or removing files from datasets)

  • Projects (Note that events are not captured for adding or removing Project Files, Project queries, Project Insights)

The audit events information is stored in two tables.

  • audit_events

  • audit_events_with_changes

How can you use the audit events data?

  • Reconstruct the chronology of changes to catalog resources within your catalog. This can be useful for determining how often resources are added, removed, or updated in the catalog. Additionally, the audit event data can be used to rollback changes to a previous value in cases an undesirable change was applied.

  • You can also use the events data to understand how often, when, and by whom changes to catalog resources are suggested, what changes are proposed, and whether those suggestions are approved, rejected, or cancelled.

How can you get access to audit events?

data.world can deliver the Audit Events information to you in two ways:

  • A special dataset (baseplatformdata dataset) with the two audit events tables (audit_events, audit_events_with_changes) is automatically added to all single tenant and private instance installations.

  • Additionally, customers on single tenant and private instance installations can request the base platform data to be delivered to your Snowflake account using Private Marketplace Listing.

Important

To be able to use this feature, your Snowflake account must be setup as Consumer of listings.

audit_events table

This table captures all parent events, for example, when the resource was created, updated, or deleted.

Table 1.

Column

Description

AGENTID

The user responsible for triggering the event.

ENVIRONMENT

The data.world environment where the event occurred.

EVENT_DATE_UTC

The date when the event was generated.

EVENT_TIMESTAMP_UTC

The timestamp when the event was generated.

EVENT_TYPE

The type of event, for example, resource.create, resource.delete, suggestion.create.

ID

Unique identifier for the event.

ORG

The data.world organization to which this event applies.

PREDICATES

An array of predicates to which this event applies.

SITEID

Unique data.world site ID associated with this event.

SOURCE

Whether the event was generated by interacting with the UI or via the API. Note that changes made through the base layer are not captured.

SUGGESTION_APPROVER

The organization who can approve the suggested changes.

SUGGESTION_COMPLETEDBY

The principal who approved or rejected the suggested change.

SUGGESTION_ID

Unique identifier for the suggestion object.

SUGGESTION_REQUESTOR

The principal requesting that a change should be considered.

TARGET_RESOURCE

The resource IRI of the resource impacted by this event.

TYPE_IRIS

An array of associated semantic types for the target resource, that is, https://dwec.data.world/v0/Catalog



Useful queries

  • Count of all resources created on a specified date.

    Sample query

    SELECT COUNT(audit_events.id) AS new_resources_cnt  
FROM audit_events 
WHERE audit_events.event_type = 'resource.create'    
AND audit_events.event_date_utc = DATE_PARSE('2023-04-11', 'yyyy-MM-dd')

  • Find all activities for a particular target resource ordered from newest to oldest (UTC timestamp).

    Sample query

    SELECT *
FROM audit_events
WHERE audit_events.target_resource = '{some target resource URI}'
ORDER BY audit_events.event_timestamp_utc DESC

  • Find suggestion requester, approvers, and target resources for all suggestions that occurred on a particular date and ordered by resource and requester.

    Sample query

    SELECT 
    audit_events.suggestion_requestor
    ,audit_events.suggestion_approver
    ,audit_events.target_resource
FROM audit_events
WHERE 
    audit_events.event_type = 'suggestion.create'
    AND audit_events.event_date_utc = DATE_PARSE('2023-04-07','yyyy-MM-dd')
ORDER BY audit_events.target_resource, audit_events.suggestion_requestor

audit_events_with_changes table

This table captures how often, when, and by whom changes to catalog resources are suggested, what changes are proposed, and whether those suggestions are approved, rejected, or cancelled.

Table 2.

Column

Description

ACTION

The action performed in an event. For example, add, remove, etc.

AGENTID

The user responsible for triggering the event.

CHANGESET_DATE_UTC

Date of the event in the format yyyy-mm-dd

CHANGESET_EVENT_ID

The event ID for the detailed child event.

CHANGESET_PREDICATE

The target predicate or context for the change or event.

CHANGESET_TIMESTAMP_UTC

Timestamp of the event in the format yyyy-mm-dd HH:MM:SS

CHANGE_SEQUENCE_NO

Sequence order in which the child events were generated for a given parent event.

CHANGE_TYPE

The type of the child event. For example, changeset.applied, suggestion.propose, suggestion.reject, etc.

CURRENT_VALUE

The value of the Updated field prior to applying the change event.

DATA_TYPE

The data type of the field that was modified.

ENVIRONMENT

The data.world environment where the event occurred.

EVENT_DATE_UTC

The date when the parent event was generated.

EVENT_ID

The unique identifier for the parent event.

EVENT_TIMESTAMP_UTC

The timestamp when the parent event was generated.

EVENT_TYPE

The type of the parent event. For example, resource.create, resource.delete, suggestion.create, etc.

FIELD_TYPE

The type of the field that was modified, that is, literal or uri

LANGUAGE

When provided, describes the language tag associated with the field being updated. For example, en=english, sp=spanish, etc.

ORG

The data.world organization to which this event applies.

PREDICATES

For a given parent ID, an array of predicates to which this event applies.

SITEID

Unique data.world site ID associated with this event.

SOURCE

Whether the event was generated by interacting with the UI or via the API.

TARGET_RESOURCE

The resource IRI of the resource impacted by this event.

TYPE_IRIS

An array of associated semantic types for the target resource, i.e. https://dwec.data.world/v0/Catalog

VALUE

The value of the Updated field after the event was generated.



Useful queries

  • Find all change details for a particular target resource ordered from newest to oldest and by change sequence. Note that the change sequence captures the order in which an action occurs (for example, add or remove some value)

    Sample query

    SELECT * 
FROM audit_events_with_changes ac
WHERE ac.target_resource = '{some target resource URI}'
ORDER BY ac.changeset_timestamp_utc DESC, ac.change_sequence_no ASC

  • Find the proposed suggestions details for a particular date and ordered by target resource.

    Sample query

    SELECT *
FROM audit_events_with_changes ac
WHERE 
    ac.event_type = 'suggestion.create'
    AND ac.change_type = 'propose'
    AND ac.event_date_utc = DATE_PARSE('2023-04-12','yyyy-MM-dd')
ORDER BY ac.target_resource

  • Find approved suggestions details for a particular target resource and predicate, ordered by timestamp descending and change sequence ascending.

    Sample query

    SELECT 
    *
FROM audit_events_with_changes ac
WHERE 
    ac.event_type = 'suggestion.approve'
    AND ac.change_type = 'approve'
    AND ac.changeset_predicate = '{some predicate URI}'
    AND ac.target_resource = '{some resource URI}'
ORDER BY ac.changeset_timestamp_utc DESC, ac.change_sequence_no ASC
In this section: