Skip to main content

Asset description reverse sync
App

The Asset description reverse sync package keeps Snowflake comments aligned with user descriptions maintained in Atlan. It takes descriptions that users update on in-scope assets in Atlan and applies those as COMMENT values on the corresponding Snowflake objects.

Use this reference when you want to understand how to configure the workflow, how filters constrain scope, how the audit tables behave, and how to choose between running the workflow directly in Snowflake or generating SQL artifacts for offline execution.

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 Snowflake user account used for updates has the necessary roles and permissions to set COMMENT values on the relevant objects (databases, schemas, tables, views, columns, and other supported object types).
  • The database and schema used to store audit log data and temporary data are available to the Snowflake role with read and write permissions, including OWNERSHIP on that database and schema.

To verify ownership of objects, you can run queries like the following in Snowflake:

select table_name, table_owner
from snowflake.account_usage.views
where table_catalog = '<yourDatabaseName>';

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;

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.

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​