Skip to main content

Asset Import
App

The Asset Import app loads metadata for data assets from a CSV file into Atlan. It's designed to support large-scale enrichment and migration of asset metadata without manual entry.

CSV files can be provided either by uploading them directly from your local machine or by fetching them from a cloud object store. Supported object storage systems include Amazon S3, Google Cloud Storage (GCS), and Azure Data Lake Storage (ADLS).

This reference provides complete configuration details for asset imports, including input handling rules, options for updates versus creation, and behavior when working with different asset types and relationships.

You can also use the same Asset Import app to import other types of metadata, such as Glossaries, Tags and Data Products. See their respective references for details.

Access​

The Asset Import app isn't enabled by default. To use this app, contact Atlan support and request it be added to your tenant. Once enabled, asset imports can be set up and run by admins or users with workflow permissions.

Source​

This section defines how the input CSV file for asset metadata is provided and identified in Atlan.

Workflow name​

Specifies the display name for the workflow in Atlan. This name is used to identify the import job in the UI and logs. Choose a name that clearly reflects the purpose or scope of the asset import.

Example: If you're importing assets for the customer data domain, you might set:

Customer data assets import

Import metadata from​

This property defines how the CSV file containing asset metadata is provided to the workflow. The file format must match the CSV file format for assets.

There are two ways to provide the file:

  • Direct file uploads: Upload a CSV file directly from your local machine. This is useful for smaller files or ad-hoc imports. See Direct file uploads.
  • Object storage: Fetch the CSV file from a supported cloud object store (S3, GCS, or ADLS). This is recommended for larger files or recurring imports. See Object storage.

Direct file uploads​

Upload a CSV file directly from your local machine. This option is best for smaller files or ad-hoc imports that are run manually.

File size limit

Direct file uploads are limited to ~10 MB. Only one file can be uploaded per run. For larger or recurring imports, use object storage.

Object storage​

This property imports the asset CSV file from a cloud object store rather than a local upload. It's recommended for large files and for recurring imports. Supported providers are Amazon S3, Google Cloud Storage (GCS), and Azure Data Lake Storage (ADLS). When this option is selected, additional storage-specific properties such as bucket, project ID, or container become available.

Amazon S3 enables you to store and retrieve objects at scale. You can use this option when the assets CSV file is stored in an S3 bucket.

AWS access key​

The access key for your AWS account. You can find this in the AWS Management Console > IAM > Users > Security credentials tab.

  • Must have a value if you are using the access/secret key authentication method.
  • Must be blank if your setup is tenant-backed, cross-account, or role-based.

Example:

AKIAIOSFODNN7EXAMPLE

AWS secret key​

The secret key that pairs with your access key. This is generated when you create an access key in IAM. You must download it at creation time or rotate and generate a new one if lost.

  • Must have a value if you are using the access/secret key authentication method.
  • Must be blank if your setup is tenant-backed, cross-account, or role-based.

Example:

wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

AWS role ARN​

The ARN of the AWS role to use to access S3. You must set this up separately in AWS, and grant permissions for Atlan to assume this role.

  • Must have a value if you are using role-based authentication method.
  • Must be blank if your setup is tenant-backed, cross-account, or access/secret key based.

Example:

arn:aws:iam::123456789012:role/roleName

Region​

The AWS region in which your bucket is located (for example, us-east-1). You can find this in the S3 service dashboard when selecting your bucket.

  • Must have a value if you are using the access/secret key authentication method.
  • Must be blank in all other scenarios, where the region is inferred from the tenant or role.

Example:

ap-southeast-1

Bucket​

The name of the S3 bucket that contains your assets CSV file. The bucket name is listed in the S3 service dashboard.

  • Must be blank to use the tenant-backed object store's bucket.
  • Must have a value in all other scenarios.

Example:

customer-data-assets

Assets file​

This property is available only when the Direct file uploads option is selected under Import metadata from. It defines the CSV file that contains asset metadata for import into Atlan.

The asset CSV follows a structured format with columns for asset names, types, descriptions, and relationships. Each row in the file represents a single asset and its attributes, while relationships (such as lineage connections) are encoded in specific columns.

You can upload one CSV file per workflow run. The file must follow the Assets CSV format, and only CSV files are supported, formats such as JSON or Excel aren't accepted.

Duplicates cause errors

Duplicate asset entries in the same file cause errors and workflow failure.

For detailed information on the required structure and field definitions, see the Assets CSV format.

Prefix (path)​

This property is available only when the Object storage option is selected under Import metadata from. It specifies the directory or path within your selected cloud object store where the asset CSV file is located.

If left blank, the system searches from the root of the bucket or container.

  • With prefix: Only files under the specified path are processed.
  • Without prefix: System searches from the root of the storage location.
  • Format: Use forward slashes (/) as path separators.
  • Trailing slash: Not required, Atlan appends automatically if missing.

Example: If your asset file is stored in a folder called tables inside the assets directory of your bucket, set the prefix to:

assets/tables

Object key (filename)​

This property is available only when the Object storage option is selected under Import metadata from. It specifies the exact CSV file to import from your chosen cloud object store. The value entered here is combined with the optional Prefix (path) to form the complete location of the file.

The object key must include the file name and extension. Only one file can be provided per configuration. If you have multiple CSV files, the Object key (filename) property can only reference one file at a time. A new workflow run is required for each file, even if they're stored in the same prefix or folder.

  • Single file: Only one CSV file per workflow configuration
  • Multiple files: Requires separate workflow runs for each file
  • File extension: Must include the .csv extension
  • Path combination: Object key + prefix = complete file location (within the bucket)

Example: If your asset file is stored under a folder called assets/tables in your object store, you can configure:

Prefix:

assets/tables

Object key:

customer-tables.csv

Complete path: {{bucket}}/assets/tables/customer-tables.csv

Input handling​

The Input handling property defines how the workflow processes asset metadata from the CSV file when matching it with existing assets in Atlan. It controls whether new assets are created or only existing ones are updated.

Asset matching rules

When importing, assets are matched with existing objects in Atlan using the following rules:

  • Regular assets: Both qualifiedName and typeName must exactly match an existing asset.
  • Relational assets: Table, View, and MaterializedView can be treated as interchangeable if configured in the options.
  • Case sensitivity: Matching can be performed case-sensitively (default) or case-insensitively, depending on the configuration.

CSV data must align with these rules to successfully update existing assets and avoid creating new assets. Note that qualifiedName controls updates, so you can't use this app to change the qualifiedNames of existing assets.

Create full​

This option creates complete, discoverable assets from the CSV file and updates any that already exist in Atlan. With this configuration, the workflow reads each row in the CSV and either:

  • Creates a full asset if it doesn't already exist, or
  • Updates the corresponding asset if it's already present.

This option is commonly used when you intend to use the CSV input file and this app as the definitive source of these assets' metadata.

Create partial​

This option creates partial assets that are more limited in their supported capabilities. These are useful when you want to represent a placeholder for an asset that you lack full context about, but also don't want to ignore completely.

This option is useful when building lineage maps or when you need to represent external systems that aren't fully crawled by Atlan.

Update only​

This option updates only assets that already exist in Atlan. With this configuration, the workflow applies changes from the CSV file to matching assets, but doesn't create any new assets.

This option is useful when enriching or correcting existing assets with additional metadata, descriptions, or attribute values. Assets are processed in multiple stages to maintain parent–child relationships. Parent assets are created or updated first, followed by their child assets once the parent relationships exist. Lineage relationships between assets are applied last.

This option ensures you are only enriching or correcting existing assets, and avoid ever creating new ones.

Delta handling​

The Delta handling property defines how updates from the CSV are applied to existing assets in Atlan.

Full replacement​

Calculates differences between files between each successful run of the app, to support deleting assets.

Only mode that automates deletion

This is the only delta handling mode that automates deleting assets. It can only be used when all assets in the CSV are within the same connection.

Example:

  • The app is run daily.
  • Yesterday's CSV had 5 assets: A, B, C, D, and E.
  • Today's CSV has 3 assets: A, B, and X.
  • After today's run, there are 3 assets: A, B, and X.
    • X was created.
    • A and B were updated from today's file.
    • C and D were deleted.

Incremental​

Only applies what's in the latest provided CSV file to assets, and ignores any rows that no longer exist in the latest CSV.

Example:

  • The app is run daily.
  • Yesterday's CSV had 5 assets: A, B, C, D, and E.
  • Today's CSV has 3 assets: A, B, and X.
  • After today's run, there are 6 assets: A, B, C, D, E, and X.
    • X was created.
    • A and B were updated from today's file.
    • C and D were left untouched.

Options​

The Options property defines how the workflow interprets and applies data from the asset CSV file. These settings control error handling, attribute overwrites, and how multi-valued fields like tags or custom metadata are managed.

When Default is selected, the following behaviors apply:

  • Blank fields in the CSV are ignored rather than overwriting existing values.
  • An invalid value in any field causes the import to stop and fail.
  • Asset matching is performed case-sensitively.
  • Type names in the CSV must match exactly in Atlan. (Table and View aren't interchangeable.)
  • A comma (,) is expected as the field separator.
  • A maximum of 20 records are processed in each API request.
  • Custom metadata attribute values are merged with any existing values.
  • Links are updated if their URL is the same, otherwise new links are added.
Atlan tags behavior

If the atlanTags column exists in your CSV, it overwrites existing tags completely, including removing any tags from existing assets where it's empty on a given row.

Assets CSV file​

The asset CSV file defines the metadata for data assets to be imported. Each row represents one asset and its attributes. Relationships between assets are generally encoded using a TypeName@qualifiedName structure, within specific columns that represent relationships.

Required fields​

You must specify values for at least these fields, for every asset. You also need to provide values for other fields, but the specific fields vary depending on the asset type.

  • qualifiedName: Unique identifier for the asset within Atlan. Must be stable and consistent across imports.

    Can use deferred connection details

    Since the connection portion of an asset's qualifiedName is based on some generated timestamp detail, you can use a special encoding to defer these to be resolved by the app rather than hard-coding them. Use the format {{connector-type/Connection Name}} for such deferred resolution.

    Example: {{snowflake/Production}}/atlan_demo (this row creates or updates the atlan_demo asset within a Snowflake connection named Production.

  • typeName: Type of the asset. Can be any one of the asset types defined in the Full model reference.

    Example: Database (this row creates or updates a database asset)

  • name: Technical name of the asset, as crawled from the source system.

    Example: atlan_demo (creates or updates a database called "atlan_demo")

  • connectorName: The connector type for the asset (for example, snowflake, bigquery). (Full list of built-in types can be found in the Connector types and icons reference.)

    Example: snowflake (indicates this is a Snowflake asset)

Matching behavior​

When importing, assets are matched with existing objects in Atlan using the following rules:

  • Regular assets: Both qualifiedName and typeName must exactly match an existing asset.
  • Relational assets: Table, View, and MaterializedView can be treated as interchangeable if configured in the options.
  • Case sensitivity: Matching can be performed case-sensitively (default) or case-insensitively, depending on the configuration.

This may require you to change the qualifiedName values, for example, to use a different connection when migrating assets from one data tool to another.

Can't update qualifiedNames

CSV data must align with these rules to successfully update existing assets and avoid creating new assets. Note that qualifiedName controls updates, so you can't use this app to change the qualifiedNames of existing assets.

Denormalized fields​

For most assets, you also need to specify values for "denormalized" fields. Atlan uses these to quickly filter and render details about assets as part of the user interface. Denormalized fields always come in pairs, and vary by asset type:

  • ...Name: Direct name of the ancestral asset as it appears in the source system.

    Example:

    • databaseName: Name of the database as it appears in the source system, for example atlan_demo.

  • ...QualifiedName: Unique name of the ancestral asset, following Atlan's naming convention for the referenced asset type

    Example:

    • databaseQualifiedName: Unique name of the database as it's identified in Atlan, for example {{snowflake/Production}}/atlan_demo.
Deferred connection resolution

Every denormalized qualifiedName can use the special format for deferring resolution of the connection portion of the qualified name:

{connector-type/Connection Name}

For relational assets these are the denormalized fields. You can find the specific fields relevant to each asset type in the Full model reference.

  • connectionQualifiedName: Qualified name of the connection the asset belongs to.

    Example: {{snowflake/Production}} (links to the Snowflake connection, using deferred resolution based on the connector type and connection's name)

  • databaseQualifiedName: Qualified name of the database the asset belongs to (for schemas, tables, views, columns).

    Example: {{snowflake/Production}}/atlan_demo (links to the "atlan_demo" database)

  • databaseName: Database name as it appears in the source system.

    Example: atlan_demo (database name in Snowflake)

  • schemaQualifiedName: Qualified name of the schema the asset belongs to (for tables, views, columns).

    Example: {{snowflake/Production}}/atlan_demo/customer (links to the "customer" schema)

  • schemaName: Schema name as it appears in the source system.

    Example: customer (schema name in Snowflake)

  • tableQualifiedName: Qualified name of the table the asset belongs to (for columns).

    Example: {{snowflake/Production}}/atlan_demo/customer/sales

  • tableName: Table name as it appears in the source system.

    Example: sales (table name in Snowflake)

  • viewQualifiedName: Qualified name of the view the asset belongs to (for columns).

    Example: {{snowflake/Production}}/atlan_demo/customer/sales_view

  • viewName: View name as it appears in the source system.

    Example: sales_view (view name in Snowflake)

Common fields​

You can use these common fields on all assets.

  • displayName: Optional name you can give to the asset to override how it's displayed in the UI.

    Example: Sales View

  • description: Optional description of the asset from the source system. Atlan shows this as the description of the asset in the UI by default.

    Example: Schema containing customer information and demographics (describes what the schema contains)

  • userDescription: Optional user-provided description of an asset. Atlan shows this description (if present) in the UI, instead of the description field.

    Example: Schema containing customer information and demographics (describes what the schema contains)

Certificates​

  • certificateStatus: Optional certificate on the asset. Must be one of (case-sensitive):

    • VERIFIED
    • DRAFT
    • DEPRECATED
    • or empty.

  • certificateStatusMessage: Optional message to associate with the certificate. Atlan only shows this if the certificateStatus is non-empty.

    Example: Confirmed by reviewing the description and readme.

Announcements​

  • announcementType: Optional type of announcement on the asset. Must be one of (case-sensitive):

    • information
    • warning
    • issue
    • or empty.

  • announcementTitle: Optional heading line for the announcement. Atlan only shows this if the announcementType is non-empty.

    Example: Unconfirmed quality

  • announcementMessage: Optional detailed message that can be associated with the announcement. Atlan only shows this if the announcementType is non-empty.

    Example: The quality of this asset has not been validated by either automated or manual checks. Use at your own risk.

Owners​

  • ownerUsers: Optional list of individual users who are owners of the asset. Separate each username by a newline within the cell.

    Example: this assigns both "jane" and "joe" as individual owners of the asset

    jane
    joe

  • ownerGroups: Optional list of groups who are owners of the asset. Separate each group name by a newline within the cell.

    Example: this assigns both "finance" and "marketing" as group owners of the asset

    finance
    marketing

Assigned terms​

  • assignedTerms: Optional list of the business terms to assign to the asset. Separate each term by a newline within the cell, and format each as Term Name@@@Glossary Name.

    Example: this assigns the asset to 2 terms, Customer in the Concepts glossary and Revenue in the Metrics glossary

    Customer@@@Concepts
    Revenue@@@Metrics

Atlan tags​

  • atlanTags: Optional list of the tags to assign to the asset. Separate each tag by a newline within the cell, and format as one of the following:

    • Tag Name to directly assign the tag to the asset but not propagate it.

    • Tag Name>>FULL to directly assign the tag to the asset and propagate it both down the hierarchy and through lineage.

    • Tag Name>>HIERARCHY_ONLY to directly assign the tag to the asset and only propagate down the hierarchy (not through lineage).

    • Tag Name<<PROPAGATED to indicate the tag has been propagated to the asset.

      Propagated tags are ignored

      Any tag marked propagated (Tag Name<<PROPAGATED) is ignored by an import. Only those tags that are directly applied are imported, though of course any tags applied up-hierarchy or upstream that are marked to propagate are still propagated accordingly.

    For source tags (with values), you can extend the tag name portion as follows:

    • Tag Name {{connector-type/Connection Name@@sourceTagLocation??key=value}}, where:
      • connector-type is the type of the source tag (snowflake, dbt, etc)
      • Connection Name is the name of the connection for the source the tag is synced from
      • sourceTagLocation is the path within that connection where the source tag exists
      • key is an optional key for the associated value for the tag
      • value is the value for the associated tag

    Example: this associates the Confidential Atlan tag, which is synced with the CONFIDENTIAL Snowlfake tag in the DEMO database's CUSTOMER schema as part of the Production Snowflake connection. It has a value of Not Restricted in Snowflake, and the tag itself is fully-propagated in Atlan.

    Confidential {{snowflake/Production@@DEMO/CUSTOMER/CONFIDENTIAL??=Not Restricted}}>>FULL

  • links: Optional list of the links to assign to the asset. Separate each link by a newline within the cell, and format as embedded JSON.

    • typeName: set to Link
    • attributes: containing a substructure of
      • name: the name (title) to give the link
      • link: the URL of the link

    Example: this creates 2 links for the asset, one named Example and the other named Google

    {"typeName":"Link","attributes":{"name":"Example","link":"https://www.example.com"}}
    {"typeName":"Link","attributes":{"name":"Google","link":"https://www.google.com"}}

Readmes​

  • readme: Optional HTML-formatted contents to use as the README for the asset. (You can limit this to only what's inside the <body></body> HTML tags.)

    Example: this sets the README to include a heading of "Overview" with some descriptive content underneath

    <h1>Overview</h1>
    <p>
      Some descriptive content about this asset,
      including <a href="https://example.com">links</a>
      and other rich HTML content.
    </p>

Starred details​

  • starredDetails: Optional list of the users you want to star the asset for. Separate each entry by a newline within the cell, and format as embedded JSON.

    • assetStarredBy: set to the username
    • assetStarredAt: set to the (epoch-style) timestamp of when to star it for them

    Example: this ensures the asset is starred for two users, "Jane" and "Joe"

    {"assetStarredBy":"joe","assetStarredAt":1698769268966}
    {"assetStarredBy":"jane","assetStarredAt":1698769268966}

You can relate assets to each other using a TypeName@qualifiedName encoding.

Example:

  • database: on a row defining a schema, this links the schema asset to the atlan_demo database asset

    Database@{{snowflake/Production}}/atlan_demo
Full set of relationships

You can find the full set of relationships in the Full model reference. Use the name of the relationship as the name of the column in the CSV file.

Custom metadata​

You can also manage custom metadata attributes through the app. For these, use the name of the custom metadata and attribute as the name of the column in the CSV in the format Custom Metadata Name::Attribute Name.

Example:

  • Data Quality::Completeness: this column sets values for the Completeness attribute in custom metadata named Data Quality.

For any attribute that supports multiple values, separate each value by a newline within the cell.

All other attributes​

You can also manage all other attributes through the app. For these, just use the attribute's name as the name of the column in the CSV file (see the Full model reference for the list of attributes, by asset type).

  • For any attribute that supports multiple values, separate each value by a newline within the cell.

Sample CSV file​

Download a sample CSV file to understand the required structure:

📥 Download sample assets CSV
Sample file disclaimer

This sample file shows the structure and format only. It may not import as-is and is merely a template for creating your own CSV files.

See also​