## Asset Import

URL: https://docs.atlan.com/product/capabilities/discovery/references/asset-import

> Reference for importing assets into Atlan using a CSV file, including input handling, delta options, and CSV format.

<!--vale off-->

# Asset Import 

<!--vale on-->

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](https://docs.atlan.com/llms/governance/glossary/asset-import-glossaries/llms.txt), [Tags](https://docs.atlan.com/llms/governance/tags/asset-import-tags/llms.txt) and [Data Products](https://docs.atlan.com/llms/governance/data-products/asset-import-data-products/llms.txt). See their respective references for details. 

## Access 

The **Asset Import** app isn't enabled by default. To use this app, contact [Atlan support](https://docs.atlan.com/support/submit-request) 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. 

## Identify workflow

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. 

<dd>

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

```text
Customer data assets import
```

</dd>

## 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](#assets-csv-file). 

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](#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](#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.

:::info File upload limits 
Direct file uploads are limited to a maximum file size of **20 MB**, with a rate limit of **10 uploads per minute per client**, and support only one file per run. Executable file types such as `.exe`, `.bat`, `.sh`, `.ps1`, `.cmd`, `.com`, `.dll`, and `.so` are blocked. For larger or recurring imports, use [object storage](#object-storage). 
::: 

After selecting a file, use the **Validate CSV** button to run a pre-flight check before the import runs. It catches issues such as: 

- Missing required columns or values (`qualifiedName`, `typeName`, `name`). 
- Header case mismatches, for example `qualifiedname` instead of `qualifiedName`. 
- Excel scientific-notation in long IDs like `qualifiedName`. 

Errors are reported with line numbers, a clear message, and how-to-fix guidance so you can correct the file before running the workflow. To save every reported issue to a JSON file, use the **Download errors** button. This is useful for large files or for sharing the list with whoever prepares the CSV. 

### Object storage

Use this option to fetch the asset CSV file from a cloud object store such as Amazon S3, Google Cloud Storage (GCS), or Azure Data Lake Storage (ADLS). Object storage is recommended for larger files, automated pipelines, or recurring imports where the asset CSV is generated and updated outside Atlan. It also provides a more reliable and scalable alternative when the file size or access pattern makes direct uploads less suitable.

When you select Object storage, the workflow retrieves the asset CSV from a specific path or object location within your storage system. The file must be a valid CSV following the [Assets CSV format](#assets-csv-file).

You can typically get this file from the team or system that generates your asset metadata: for example, a data migration script, a reporting pipeline, or a backend service that periodically emits a CSV into your storage bucket.

For detailed information on configuring storage credentials, access methods, and required fields for each provider, see the **[Object storage configuration for apps](https://docs.atlan.com/llms/platform/packages/object-storage-configuration/llms.txt)** guide, which applies to S3, GCS, and ADLS-based imports.

## Assets file 

This property is available only when the **Direct file uploads** option is selected under [Import metadata from](#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](#assets-csv-file), and only **CSV files** are supported, formats such as JSON or Excel aren't accepted.

:::warning 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](#assets-csv-file).

## Prefix (path)

This property is available only when the **Object storage** option is selected under [Import metadata from](#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](#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. 

:::info 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](https://docs.atlan.com/llms/catalog/lineage/what-are-partial-assets/llms.txt) 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.

:::info 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.

## Control import behavior

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. 

### Default

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.

:::warning 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.
:::

### Advanced

Selecting **Advanced** provides more control over how asset imports are processed. 

#### Remove attributes, if empty 

This setting lets you remove specific attributes when the CSV field is blank. For example, if you select **Description** and leave the description field empty in the CSV, the description is cleared from the asset in Atlan.

#### Fail on errors? 

Defines how the workflow responds when encountering invalid values in the CSV file. 

- **Yes:** The workflow stops and fails when an error is found. 
- **No:** The workflow skips the invalid value, logs a warning, and continues processing. 

*Example:* If an asset contains an invalid classification, selecting **No** lets the workflow continue importing other assets. 

#### Case-sensitive match for updates 

Controls whether attempts to match assets must be done case-sensitively or case-insensitively. 

- **Yes:** Asset names must match exactly, including case.
- **No:** Asset names match regardless of case differences.

*Example:* If your CSV has `CustomerTable` but Atlan has `customertable`:

- **Yes** → existing asset won't be found, so won't be updated (a new one is created, if allowed by [Input handling](#input-handling)).
- **No** → existing asset is found and updated.

#### Table/view agnostic?

Controls whether the import must strictly adhere to the types `Table`, `View`, and `MaterialisedView` in the input CSV, or let these be matched interchangeably.

- **Yes:** `Table`, `View`, and `MaterialisedView` types can be matched interchangeably.
- **No:** Each type must match exactly as specified in the CSV.

*Example:* If enabled, a CSV row with type `Table` and name `Customer` but in Atlan there exists only a `View` with the name `Customer`:

- **Yes** → existing `View` is found and updated.
- **No** → existing `View` won't be matched, so won't be updated (a new `Table` is created, if allowed by [Input handling](#input-handling)).

#### Field separator 

Specifies the character used to separate fields in the CSV file. 

- Default is `,` (comma).
- Other common options include `;` (semicolon) or `|` (pipe), depending on your CSV.

*Example:* If your CSV uses semicolons, set the field separator to `;`. 

#### Batch size 

Defines the maximum number of rows to process in a single API request. 

- Default: 20 records. 
- Increasing this value can improve performance but may risk hitting API limits. 

*Example:* If you set batch size to 50, each request processes 50 asset rows. 

#### Custom metadata handling 

Controls how custom metadata attributes are applied when multiple values exist. 

- **Ignore:** Custom metadata in the CSV is ignored. 
- **Merge:** Merges new metadata attributes from the CSV with existing attributes in Atlan (attribute-level merge, not value concatenation). 
- **Overwrite:** Replaces all existing metadata attributes with those from the CSV. 

*Example:* If an asset already has `Data Quality` custom metadata with attribute `completeness`=`80` and the CSV provides attribute `Data Quality::accuracy`=`90`:

- **Ignore:** → asset keeps only its existing attribute: `completeness`=`80`.
- **Merge** → asset keeps both attributes: `completeness`=`80` and `accuracy`=`90`.
- **Overwrite** → asset ends with only `accuracy`=`90` (completeness is empty).

#### Atlan tag association handling 

Controls how Atlan tag associations from the CSV are applied. 

- **Ignore:** Tags in the CSV are ignored. 
- **Append:** Adds tags from the CSV to existing tags. 
- **Replace:** Replaces all existing tags with those from the CSV. 
- **Remove:** Removes all tags from the asset. 

*Example:* If an asset already has tag `PII` and the CSV lists `Sensitive`: 

- **Ignore** → existing `PII` only
- **Append** → `PII`, `Sensitive`
- **Replace** → `Sensitive` only
- **Remove** → no tags remain

#### Linked resource idempotency 

Defines how related resources (links) are handled when they already exist.

- **URL:** Identifies unique links by their URL.
- **Name:** Identifies unique links by their name.

*Example:* If an asset already has a link named `Additional info` with a URL `https://example.com/addl-info`, and the CSV specifies a `link` value with the name `Additional info` and a URL `https://example.com/some-other-info`:

- **URL** → asset has two links: both named `Additional info` but each with a different URL.
- **Name** → asset has one link named `Additional info` with the URL `https://example.com/some-other-info`.

## 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.

 :::info 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](https://docs.atlan.com/llms/platform/types/llms.txt).

 *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](https://docs.atlan.com/llms/platform/types/llms.txt).)

 *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.

:::warning 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`.

:::info 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](https://docs.atlan.com/llms/platform/types/llms.txt).

- **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@@@Business Graph 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<>FULL
 ```

#### Links

- **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

 ```

# Overview

Some descriptive content about this asset, including links and other rich HTML content.

 ```

#### 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}
 ```

### Related assets

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
 ```

:::info Full set of relationships
You can find the full set of relationships in the [Full model reference](https://docs.atlan.com/llms/platform/types/schema/llms.txt). 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](https://docs.atlan.com/llms/platform/types/schema/llms.txt) 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.

<!--vale off-->

<!--vale on-->

:::warning 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

- [Import Assets from S3](https://docs.atlan.com/product/capabilities/discovery/how-tos/import-assets-from-s3)
- [Asset Import for glossaries](https://docs.atlan.com/llms/governance/glossary/asset-import-glossaries/llms.txt)
- [Asset Import for tags](https://docs.atlan.com/llms/governance/tags/asset-import-tags/llms.txt)
- [Asset Import for data products](https://docs.atlan.com/llms/governance/data-products/asset-import-data-products/llms.txt)

---