Skip to main content
Community Hub
TL;DR

Sync asset descriptions authored in Atlan back to Snowflake comments. Reference for workflow configuration, asset filtering, audit-trail behavior, and sync options.

Your AI can read this via Docs MCPcurl -fsSL "https://docs.atlan.com/install-docs-mcp" | bashConnect

Asset description reverse sync App

Syncs asset descriptions authored in Atlan back to Snowflake as COMMENT values on the corresponding objects. This reference documents app configuration, asset filtering rules, audit-table behavior, direct execution vs. offline SQL generation options, and how descriptions are mapped to Snowflake comments.

The package currently supports Snowflake as the source system and updates only description fields (user descriptions) for in-scope objects. Other metadata for those objects remains unchanged.

Prerequisites​

Before running the workflow, confirm the following conditions on both Atlan and Snowflake.

Atlan prerequisites​

  • Atlan is the only system used to manage asset descriptions for the Snowflake objects in scope. If you also use other tools or scripts to write comments directly in Snowflake, those values may be overwritten by reverse sync from Atlan.
  • View definitions in Atlan are up to date if you plan to enrich descriptions for view columns, because the workflow relies on the latest view definition when recompiling views.

Snowflake prerequisites​

The workflow runs as the role of the Snowflake user it connects with. That role needs:

  • USAGE on the warehouse the workflow uses.
  • IMPORTED PRIVILEGES on the SNOWFLAKE database, because the workflow reads object owners from SNOWFLAKE.ACCOUNT_USAGE.
  • USAGE on the databases and schemas that contain the objects in scope.
  • USAGE, CREATE TABLE, and CREATE PROCEDURE on the database and schema you configure for the audit trail. A dedicated schema keeps the workflow's tables out of your data schemas.
  • For every object in scope, including databases and schemas, the role that owns the object must be available to the workflow's user. Either the workflow's role owns the object, or the owning role is granted to the workflow's role.
warning

Ownership of a database or schema doesn't give ownership of the tables and views inside it. Each table and view keeps its own owner, and the workflow skips any object whose owner role it can't use.

If a system role such as ACCOUNTADMIN or SYSADMIN owns an object, transfer ownership of that object to another role instead of granting the system role to the workflow's role.

Objects that were created, renamed, or transferred to a new owner recently can take time to appear in SNOWFLAKE.ACCOUNT_USAGE. The workflow skips them until they do.

To check the owner of each table and view in a database:

select table_schema, table_name, table_type, table_owner
from snowflake.account_usage.tables
where table_catalog = '<yourDatabaseName>'
  and deleted is null;

To list all roles available to a user:

select replace(value, '"') as current_role
from table(flatten(input => parse_json(current_available_roles())));

To grant OWNERSHIP on an object to an existing role:

grant ownership
on <object_type> <object_name>
to role <role_name>
copy current grants;

To grant the owning role to the workflow's role:

grant role <owner_role> to role <workflow_role>;

For online (direct) mode, also make sure:

  • The user and role used for crawling the Snowflake connection can create and update objects in Snowflake, because the workflow can reuse stored credential GUIDs from that connection when Connection type is set to Existing.
  • If the stored user doesn't have enough permissions, configure Connection type as New and provide credentials for a Snowflake user that can perform the required updates.

Configuration​

This section documents the main workflow configuration fields.

Workflow name​

Specifies the display name for the workflow run. Use a unique and descriptive name so you can quickly recognize and manage this configuration in Workflow Center.

Example:

snowflake-asset-description-reverse-sync

Connection type​

Controls whether the workflow uses credentials from an existing Snowflake connection in Atlan or a new set of Snowflake credentials that you provide just for this workflow.

Use this option when:

  • You already have a Snowflake connection configured and crawled in Atlan.
  • The stored credential has permissions to update comments on the Snowflake objects in scope.

Behavior:

  • The workflow reuses the stored credential GUID from the selected Snowflake connection.
  • No additional Snowflake host or authentication details are required in this package configuration.

Mode​

Specifies whether the workflow runs directly in Snowflake or generates SQL artifacts for offline execution.

In Direct (online) mode, the workflow:

  1. Extracts in-scope assets and their updated user descriptions from the selected Snowflake connection in Atlan, based on your filters and run interval.
  2. Uses the configured Snowflake credentials (either from an existing connection or from the New connection type details) to establish a connection to Snowflake.
  3. Applies comment updates directly on the selected objects in Snowflake.

This mode is suited for environments where:

  • Atlan can connect to Snowflake from the workflow runtime.
  • You want updates to be applied immediately without manual SQL execution.

The audit table in Snowflake records each change, including the executor identity and correlation keys you can use to trace back to the original Atlan user.

Output​

Controls whether the workflow runs as a dry preview or performs actual sync operations.

  • Preview: Generates SQL files and shows the planned changes so you can validate that the sync configuration is correct before applying updates.
  • Sync: Applies description updates based on the configuration and mode you selected.

Use Preview initially whenever you change filters or scope to confirm that the workflow is targeting the right set of assets.

Filters​

The filter screen limits which assets are eligible for reverse sync. Each filterable attribute has an operator and a value; the package only considers filters where both operator and value are filled.

Connection​

Specifies the Snowflake connection whose asset descriptions you want to sync back into Snowflake. Only assets from this connection are considered.

Asset type​

Controls which asset types are included or excluded from the sync.

  • Operator: Choose either:
    • is one of: Sync only the selected asset types.
    • isn't one of: Exclude the selected asset types from the sync.
  • Asset types in scope: Select one or more asset types, such as:
    • Database
    • Schema
    • Table
    • View
    • Materialised view
    • Column

Use the combination of operator and asset types in scope to precisely target which Snowflake objects receive description updates.

Qualified name​

Filters assets based on their Atlan qualified name. Use this filter when you want to restrict the sync to a subset of assets that match or don't match specific qualified names or patterns.

  • Operator: Choose a comparison for the qualified name, for example:
    • is / isn't: Match or exclude assets whose qualified name exactly matches the value.
    • contains / doesn't contain: Match or exclude assets whose qualified name includes the value as a substring.
  • Qualified asset name: Enter the full or partial qualified name pattern you want to use, using your chosen operator.

This is useful when you know the exact qualified path of the assets you want to include or exclude, or when you want to target a family of assets that share a common qualified name prefix or fragment.

Unique identifier​

Filters assets using a unique identifier field. Use this when you rely on a specific identifier attribute to constrain scope beyond connection and type.

  • Operator: Choose either:
    • is one of: Sync only assets whose unique identifier matches one of the selected values.
    • isn't one of: Exclude assets whose unique identifier matches any of the selected values.
  • Unique identifiers: Provide one or more identifier values (or select them from the UI, depending on how your tenant is configured) that represent the assets you want to include or exclude.

Use this filter when you have a known list of identifiers that must always be in scope (or explicitly out of scope), regardless of connection, asset type, or qualified name.

Recompile views?​

Controls whether the workflow updates descriptions for columns in views.

  • Yes: The workflow recompiles view definitions to apply column-level description updates. This can cause brief unavailability for impacted views while the recompile occurs.
  • No: The workflow doesn't update descriptions for columns in views. Other object descriptions still update as usual.

Choose Yes only when you need column-level coverage for views and are comfortable with potential short-lived view unavailability.

Run interval​

Defines the time window in which userDescription was updated in Atlan for selected assets.

Available options typically include:

  • Last 24 hours
  • Last 7 days
  • Last 30 days

The workflow only considers assets whose user descriptions changed in the selected interval.

Dry run​

Use the dry run option when you want to validate configuration and scope before applying any updates to Snowflake objects. In dry run mode:

  • The workflow computes which assets are in scope for update.
  • It generates artifacts and audit entries for inspection.
  • It doesn't persist any new comments on Snowflake objects.

Run a dry run whenever you adjust filters, connection settings, or mode, and only proceed to a full sync after reviewing the results.

Skipped objects​

Before it writes any comment, the workflow checks that every object in scope reached the inventory table. It logs each object it skips, with the reason, in the call-stored-procedure step:

  • If some objects are skipped, the run continues and the skipped objects appear as warnings.
  • If every object is skipped, the run fails and the error lists each object with its reason.
Reason in the logWhat to do
owned by role <role>, which the connection user cannot useGrant <role> to the workflow's role, or transfer ownership of the object.
owned by system role <role>Transfer ownership of the object to a role the workflow's user can use.
not found in SNOWFLAKE.ACCOUNT_USAGECheck the object name. If the object is new or was renamed, run the workflow again later.
only a dropped version exists in SNOWFLAKE.ACCOUNT_USAGEThe object was dropped or re-created. Check the name, or run the workflow again later.
has no owner role in SNOWFLAKE.ACCOUNT_USAGEAssign an owner role to the object.
found with an available owner role <role>, but the inventory insert did not load itRaise a support request with the workflow run details.
type <type> is not supportedRemove that asset type from the Asset type filter.
could not look up the ownerThe text after the colon is the Snowflake error from the owner lookup. Fix the cause it names and run the workflow again.

If more than 100 objects are in scope, the log reports how many objects were skipped but doesn't name them. Narrow the filters to see which objects were skipped.

Audit trail​

The package maintains an audit trail in Snowflake for each run to help you understand what changed and when. It uses two main tables, created in the database and schema you configure for audit and temporary data:

  • tbl_atlan_reverse_sync_inventory
  • tbl_atlan_reverse_sync_audit

Inventory table​

tbl_atlan_reverse_sync_inventory stores intermediate data required during the sync operation. It's created as part of the stored procedure execution and dropped automatically once the run completes. This limits persistent footprint and keeps temporary data separate from the long-term audit log.

Audit table​

tbl_atlan_reverse_sync_audit is a persistent audit table used to record reverse sync operations across runs.

  • The workflow creates the table on the first run if it doesn't already exist.
  • Subsequent runs append new rows instead of re-creating the table.
  • The table tracks details such as object identity, old and new comments, run metadata, and keys that let you correlate entries with Atlan events.

User attribution in the audit table​

Reverse sync operations often run under a technical or service account, especially when executed by the workflow engine. To avoid confusion, it's important to distinguish:

  • The user who made the change in Atlan (the original editor of the description).
  • The principal that executed the write in Snowflake (which may be a service account).

Downloading artifacts (offline mode)​

When you run the workflow in offline mode or with Preview output, it generates a set of SQL artifacts you can download from Atlan or via the Atlan API or SDK.

The generated folders typically include:

  • create: Contains two .sql files used to create the tbl_atlan_reverse_sync_inventory and tbl_atlan_reverse_sync_audit tables.
  • loader: Contains a .sql file that loads data into the tbl_atlan_reverse_sync_inventory table.
  • procedure: Contains the stored procedure that updates comments on Snowflake objects based on the inventory table.
  • callsp: Contains a .sql file that calls the stored procedure with parameters derived from your configuration.
  • drop: Contains a .sql file that drops the tbl_atlan_reverse_sync_inventory table after the run.
  • load-online: (online sync scenarios) Contains .sql files that insert data into tbl_atlan_reverse_sync_inventory for direct-mode patterns.

You can download these files from the workflow run in the Atlan UI, or via the Atlan API or SDK from the object store. The keys typically follow the pattern:

  • <s3-prefix-from-configuration>/loader.sql
  • <s3-prefix-from-configuration>/procedure.sql

See also​