Skip to main content

Relational Assets Builder
App

The Relational Assets Builder app creates or updates connections, databases, schemas, tables, views, materialized views, and columns from a structured CSV file.

This reference provides complete configuration guidance for the Relational Assets Builder app, including how to prepare the CSV file, how the workflow interprets relational metadata, and how to control behaviors such as updates, deletions, and attribute handling.

Access​

The app isn't enabled by default. Contact Atlan support if you don't see Relational Assets Builder in the Apps Marketplace. Only admins or users with workflow execution permissions can configure and run it.

Source​

This section defines how the input CSV file is identified.

Workflow name​

Specifies the display name for the workflow. Choose a descriptive name to identify runs in Workflow Center.

Example:

finance-relational-assets-builder

Import metadata from​

This property defines how the CSV file containing relational assets is provided. The file format must match the CSV file format.

Upload a CSV file directly from your local machine. This option is intended for smaller or ad-hoc imports that are run manually. When you choose Direct file uploads, the workflow accepts only a single file per run, and the file must be in CSV format, other formats such as Excel, TSV, JSON, or XML aren't supported. The uploaded file must also follow the required CSV file format and include all necessary required fields.

If the CSV is missing required attributes, the workflow fails.

File size limit

Direct file uploads are limited to ~10 MB. For larger or recurring imports, use object storage.

Assets file​

Available only when Direct file uploads is selected. The CSV must follow the CSV file format. Upload one file per run; formats such as Excel or JSON aren't supported.

Semantics​

This section defines how the workflow interprets each row in the CSV and how it determines whether to create new assets, update existing ones, or remove assets that no longer appear. These settings control the overall behavior of the import and how Atlan reconciles the CSV with the metadata already present in your tenant.

Input handling​

This setting determines how the workflow processes each row in the CSV and whether new assets are created or only existing ones are updated. It controls how Atlan reconciles the CSV file with metadata already present in your tenant.

  • Create (full) and update: Atlan creates a fully discoverable asset when the row doesn't match an existing asset, and updates the asset when a match is found. Use this option when you are onboarding new metadata into Atlan and also want to keep existing assets synchronized with your source system.

  • Create (partial) and update: Atlan creates a partial asset when no match exists, allowing it to appear in lineage without being fully represented in the catalog. Matching assets are updated normally. This mode is ideal when you want lineage completeness without committing to full discovery of every upstream object.

  • Update only: Atlan updates assets that already exist and skips creating new ones. Any row that doesn't match an existing asset is ignored. This option is useful when your intention is to enrich or maintain catalog metadata (such as owners, tags, or READMEs) without creating new assets from the CSV. Even when creation is skipped, related artifacts like READMEs and links are still applied.

Delta handling​

Delta handling defines how the workflow treats assets that no longer appear in the latest CSV file. This setting determines whether Atlan removes assets that have disappeared or simply updates the ones that are present.

When Full replacement is selected, the workflow compares the latest CSV with the previous successful run and removes assets that no longer appear in the latest CSV file. This mode is used when the CSV is intended to represent the complete and authoritative set of assets for a connection.

Selecting this option reveals two additional properties:

  • Removal type: Determines how missing assets are removed.

    • Archive (recoverable): Soft-deletes assets, allowing them to be restored later.
    • Purge (can't be recovered): Permanently deletes assets from Atlan.

  • Reload which assets: Determines how the workflow reloads assets that remain in the CSV.

    • All assets: Reprocesses every asset in the file, even if unchanged.
    • Changed assets only: Updates only the assets whose values differ from the previous run.

Options​

The Options section controls how strictly the workflow validates the CSV file and how it interprets certain values during processing. These settings let you adjust error-handling behavior, define how blank fields are treated, which field separator the file uses, and manage performance characteristics such as batch size.

Remove attributes, if empty​

This option lets you choose which attributes get cleared when their corresponding cells are left blank in the CSV file. When enabled, the workflow displays a list of selectable properties that can be cleared. Any attribute you select here is removed from the asset if the CSV provides an empty value for that column.

Attributes that aren't selected in this list ignore blank values and retain whatever is already stored in Atlan.

The only exception is atlanTags, which is always fully replaced, regardless of whether it's included in this option.

Fail on errors​

This setting controls how the workflow responds when it encounters invalid or incomplete values in the CSV file.

  • Yes: The workflow fails overall when it detects an error in any row. Selecting Yes ensures strict validation and awareness that any problems were found. Use this option when data quality is critical and you want the entire run to fail if even one row contains issues such as missing required fields, invalid data types, or malformed JSON.
  • No: The workflow logs the error, skips the invalid value, and continues processing the remaining rows. Selecting No lets the import complete even when individual rows contain issues. This mode is useful when the CSV may include occasional bad records, when you are iterating during testing, or when partial success is preferred over a failed run.

Field separator​

This setting defines the character used to separate columns in your CSV file. The workflow expects the separator you specify here to match the actual delimiter used in the uploaded file.

The default separator is a comma (,), which is used by most standard CSV generators. You can change this to a semicolon (;) or another supported delimiter if your source system exports CSVs using a different format or if your data contains embedded commas. For example, if your file uses commas, set the separator value to ,; if your file uses semicolons, set the separator value to ;.

Batch size​

Batch size controls how many rows from the CSV file are processed in a single API request. A larger batch size can improve performance by reducing the number of requests required for large files, especially during full onboarding runs. However, setting the value too high may increase the chance of throttling or timeouts in environments with strict rate limits.

Lower batch sizes process fewer rows at a time and may run more slowly, but they provide greater stability and isolation of problems.

Adjust this value based on the size of your CSV and how aggressively you want the workflow to process updates.

Custom metadata handling​

Controls how custom metadata (CM) attributes from the CSV are applied to existing assets.

  • Ignore: Custom metadata values in the CSV are skipped. Existing CM on the asset remains unchanged.
  • 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​

Determines how the workflow updates Atlan tags listed in the CSV.

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

CSV file format​

The CSV file format defines the complete structure of the relational assets you want to create or update through the workflow. Each row represents a single asset, such as a database, schema, table, view, materialized view, or column, along with its attributes. The workflow reads the file top-to-bottom and uses the values in each row to determine how assets are matched, created, or updated.

Column order doesn't matter, but every column name must match the expected field names exactly. The file must follow the required format described in this section so the workflow can interpret hierarchy, ownership, certification, tags, announcements, and custom metadata correctly.

Required fields​

Every row in the CSV must include a minimum set of fields so the workflow can correctly identify the asset, place it in the proper hierarchy, and determine how it gets created or updated.

Required fields vary by type

Requirements depend on the value of typeName.

  • typeName: Specifies the kind of asset represented in the row.
    Must be one of:
    Connection, Database, Schema, Table, View, MaterialisedView, Column.

  • connectionName: The name of the connection that all assets in the row belong to.
    Required for every row, regardless of asset type.

  • connectorType: The connector used by the connection, expressed as the lowercase identifier
    (see Connector Types).

  • databaseName: Required for Database assets and for any asset contained within a database.
    Represents the technical name of the database.

  • schemaName: Required for Schema assets and for any asset contained within a schema.
    Identifies the schema that holds tables, views, or materialized views.

  • entityName: Required for tables, views, and materialized views (and anything below them).
    Represents the name of the table or view.

  • columnName: Required only when typeName is Column.
    Identifies the name of the specific column inside an entity.

  • dataType: Required only when typeName is Column. Identifies the data type of the column. You can specify this as a conceptual type (like string) or a full SQL type (like NVARCHAR(255) or DECIMAL(5,2)).

Matching behavior​

The workflow uses specific fields in each row to determine whether the asset already exists in Atlan. This matching process ensures that updates are applied to the correct asset and that new assets are created only when necessary.

Assets are matched strictly on their identity within the relational hierarchy using the following fields:

  • typeName
  • connectionName
  • connectorType
  • Relevant hierarchy fields (databaseName, schemaName, entityName, columnName), depending on the asset type

For example, a column is matched using all hierarchy fields from connection → database → schema → table → column, while a schema is matched using only connection → database → schema.

If a matching asset is found, the workflow updates it according to the selected Input handling settings. If no match exists:

  • The asset is created (fully or as a partial asset) when using Create (full) and update or Create (partial) and update.
  • The row is skipped entirely when using Update only.

Precise matching ensures that updates apply only to the intended assets and avoids accidental duplication within the catalog.

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

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 sample relational assets CSV

See also​