Best Practices for Object Set Fields

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Customer Managed Applies to customer-managed instances of Alation

Object set fields let you create links between catalog objects so that users can navigate between related assets. This topic covers a common governance use case: linking data assets to a governing document, and explains the recommended approach for setting up those links at scale.

The Governing Document Pattern

A common practice in Alation is to create a governing document: a document object in a document hub that acts as a logical anchor for a group of related data assets. For example, a document called Net Revenue might represent a business concept that spans dozens of tables and hundreds of columns across multiple data sources.

The goal is to link every asset that represents or contributes to that concept back to its governing document, so that users can navigate from any individual asset to the full context.

Object set fields are the standard way to create such links. The key question is: which side of the relationship should the object set field go on?

Scalability Limit

The practical limit is approximately 256 linked objects per object set field. Beyond this, page load performance degrades. If you add an object set field to a document and use it to link thousands of RDBMS objects to that document, you will eventually encounter this limit.

Not Recommended: Object Set Field on the Document

The diagram below shows the pattern to avoid. The object set field sits on the document and points outward to all linked assets.

        %%{init: {
  'theme': 'base',
  'themeVariables': {
    'fontFamily': 'Public Sans, Open Sans, sans-serif',
    'primaryColor': '#EFF6FF',
    'primaryTextColor': '#002E4B',
    'primaryBorderColor': '#002E4B',
    'lineColor': '#6B7280',
    'edgeLabelBackground': '#ffffff'
  }
}}%%
flowchart LR
    D["Document (Object-Set Field)"]
    R1["RDBMS Object"]
    R2["RDBMS Object"]
    Rn["..."]

    D -- "+Add" --> R1
    D -- "+Add" --> R2
    D -- "+Add" --> Rn

    

Recommended: Object Set Field on Each Asset

The recommended approach reverses the link direction. Place the object set field on the data asset template and use it to point to the governing document.

The governing document uses a back reference field to display all assets that have linked to it. The back reference is derived automatically from the many small per-asset references, so it does not reach the same scalability constraint.

        %%{init: {
  'theme': 'base',
  'themeVariables': {
    'fontFamily': 'Public Sans, Open Sans, sans-serif',
    'primaryColor': '#EFF6FF',
    'primaryTextColor': '#002E4B',
    'primaryBorderColor': '#002E4B',
    'lineColor': '#6B7280',
    'edgeLabelBackground': '#ffffff'
  }
}}%%
flowchart TB
    subgraph A["Step A: from the asset"]
        direction LR
        RA["RDBMS Object (Object-Set Field)"] -- "+Add" --> DA["Document (Back-Ref Field)"]
    end

    subgraph B["Step B: from the document"]
        direction LR
        DB["Document (Back-Ref Field)"] -- "+Add" --> RB["RDBMS Object"]
    end

    N1(["↔ Both steps create the same bidirectional link. Each asset cell stays small: scales to thousands of assets"])
    N2(["⚠ Prerequisite for Step B: at least one RDBMS object must already link to the document via Step A"])

    A --> B
    B --> N1
    N1 --> N2

    

Set Up the Recommended Pattern

A Catalog Admin or Server Admin must complete the following setup before users can create links.

1. Create the object set field. Create an object set field (for example, Governing Documents) that permits the document object type. For help, see Manage Custom Fields.

   Important

   When creating the object set field, ensure that the Backreference configuration is set to create a back reference field on the document. The back reference will appear on documents to show which assets are linked to them.

2. Add the object set field to asset templates. Add the Governing Documents object set field to the templates for each relevant asset type (for example, Table, Column, Schema). Users will then see the field on those catalog pages and can add links from there. For help, see Manage Templates.

3. Add the Backreference Fields object-defined field to the document template. Add the Backreference Fields object-defined field to the document template so that governing documents can display the full list of linked assets and so that users can add links from the document side as well.

   Note

   In the template editor, the Backreference Fields field is located under Object-Defined Fields in the field selector panel. This field is not added to new templates by default; you must add it explicitly. You can add it to the main body of the template or to a sidebar. If you want to create links from the document side, we recommend placing it in the main body for better discoverability.

Create Links: Two Starting Points

Once the setup is complete, users can create links from either side. Both approaches create the same bidirectional link.

From the Asset Side

Navigate to the catalog page of an RDBMS object, locate the Governing Documents object set field, and click the + Add button to add the governing document. This is the primary approach and works for any user with edit access to the asset.

From the Document Side

Navigate to the governing document, locate the back reference field in the document body, and click the + Add button to add the RDBMS object. This approach is useful when you’re curating the governing document directly and want to pull assets into it.

Note

The back reference field on a document becomes interactive only after at least one asset has already linked to the document via its object set field. If no assets have linked yet, start from the asset side.

For step-by-step procedures, see Create References Between Catalog Objects.