Skip to main content

Linking Glossary Terms

Link glossary terms to assets and columns to provide business context and improve AI understanding.

Purpose​

Linking terms provides:

  • Business context: Technical columns linked to business terms
  • AI enhancement: Better AI understanding of your data
  • Documentation: Self-documenting data assets
  • Governance: Track which assets use which terms

Linking to Assets​

Link a term to an asset:

msh glossary link-term "Customer" --asset revenue

This links the "Customer" term to the revenue asset.

Linking to Columns​

Link a term to a specific column:

msh glossary link-term "Customer" \
  --asset revenue \
  --column customer_id

This links the "Customer" term to the customer_id column in the revenue asset.

Column Roles​

Specify the role of a column:

msh glossary link-term "Customer" \
  --asset revenue \
  --column customer_id \
  --role primary_key

Available Roles:

  • primary_key - Primary key column
  • foreign_key - Foreign key column
  • attribute - Regular attribute column

Link a term to multiple columns:

# Link to customer_id
msh glossary link-term "Customer" \
  --asset revenue \
  --column customer_id \
  --role primary_key

# Link to customer_name
msh glossary link-term "Customer" \
  --asset revenue \
  --column customer_name \
  --role attribute

Manual Linking​

Link terms manually in glossary.yaml:

terms:
  - id: term.customer
    name: Customer
    description: A customer entity
    links:
      - asset: revenue
        column: customer_id
        role: primary_key
      - asset: revenue
        column: customer_name
        role: attribute

List glossary terms to see links:

msh glossary list

Output:

Terms:
- Customer (term.customer) - A customer entity
  Linked to:
    - revenue.customer_id (primary_key)
    - revenue.customer_name (attribute)

Benefits​

AI Enhancement​

Linked terms improve AI understanding:

# AI understands "Customer" means customer_id column
msh ai explain assets/revenue.msh
# Output includes: "This asset calculates revenue per Customer..."

Documentation​

Links provide self-documenting assets:

msh glossary list
# Shows which columns are linked to which terms

Governance​

Track term usage:

# See which assets use "Customer" term
msh glossary list --json | jq '.terms[] | select(.name=="Customer") | .links'

Use Cases​

Primary Keys​

Link terms to primary key columns:

msh glossary link-term "Customer" \
  --asset revenue \
  --column customer_id \
  --role primary_key

Foreign Keys​

Link terms to foreign key columns:

msh glossary link-term "Customer" \
  --asset orders \
  --column customer_id \
  --role foreign_key

Attributes​

Link terms to attribute columns:

msh glossary link-term "Customer" \
  --asset revenue \
  --column customer_name \
  --role attribute

Best Practices​

Link terms when creating assets:

# Create asset
msh ai new --name revenue --apply

# Link terms immediately
msh glossary link-term "Customer" --asset revenue --column customer_id
msh glossary link-term "Revenue" --asset revenue --column amount

Use Consistent Terms​

Use consistent term names across assets:

# Use "Customer" consistently
msh glossary link-term "Customer" --asset revenue --column customer_id
msh glossary link-term "Customer" --asset orders --column customer_id

Document Roles​

Specify roles for better understanding:

msh glossary link-term "Customer" \
  --asset revenue \
  --column customer_id \
  --role primary_key