Skip to main content

Managing Glossary Terms

Create and manage business terms, metrics, dimensions, and policies in your glossary.

Creating Terms​

Using CLI​

Create a new term:

msh glossary add-term "Customer" --description "A customer entity"

Create term with explicit ID:

msh glossary add-term "Customer" \
  --id "term.customer" \
  --description "A customer entity"

Manual Creation​

Create terms in glossary.yaml:

terms:
  - id: term.customer
    name: Customer
    description: A customer entity
  
  - id: term.revenue
    name: Revenue
    description: Total revenue amount

Or in msh.yaml:

glossary:
  terms:
    - id: term.customer
      name: Customer
      description: A customer entity

Term Types​

Terms​

Business concepts:

terms:
  - id: term.customer
    name: Customer
    description: A customer entity
    type: entity

Metrics​

Calculated measures:

metrics:
  - id: metric.monthly_revenue
    name: Monthly Revenue
    description: Total revenue per month
    formula: SUM(amount)
    unit: USD

Dimensions​

Categorization attributes:

dimensions:
  - id: dim.region
    name: Region
    description: Geographic region
    values: [North, South, East, West]

Policies​

Rules and constraints:

policies:
  - name: No PII in public assets
    rule: PII columns cannot be in public schema
    pii_columns: [email, ssn, phone]
    applies_to: [public.*]

Listing Terms​

List all glossary terms:

msh glossary list

Output:

Glossary Terms: 5

Terms:
- Customer (term.customer) - A customer entity
- Revenue (term.revenue) - Total revenue amount
- Order (term.order) - An order entity

Metrics:
- Monthly Revenue (metric.monthly_revenue) - Total revenue per month

Dimensions:
- Region (dim.region) - Geographic region

Policies:
- No PII in public assets

JSON Output​

Get JSON output:

msh glossary list --json

Exporting Glossary​

Export glossary as JSON:

# Print to stdout
msh glossary export

# Save to file
msh glossary export --path glossary.json

Use Cases:

  • AI consumption
  • External tools
  • Documentation generation

Term Structure​

Basic Term​

terms:
  - id: term.customer
    name: Customer
    description: A customer entity

Term with Metadata​

terms:
  - id: term.customer
    name: Customer
    description: A customer entity
    type: entity
    owner: data-team
    tags: [core, business]

Metric​

metrics:
  - id: metric.monthly_revenue
    name: Monthly Revenue
    description: Total revenue per month
    formula: SUM(amount)
    unit: USD
    aggregation: sum

Dimension​

dimensions:
  - id: dim.region
    name: Region
    description: Geographic region
    values: [North, South, East, West]
    type: categorical

Policy​

policies:
  - name: No PII in public assets
    rule: PII columns cannot be in public schema
    pii_columns: [email, ssn, phone]
    applies_to: [public.*]
    enforcement: strict

Best Practices​

Naming Conventions​

  • Terms: Use business-friendly names (e.g., "Customer", "Revenue")
  • IDs: Use prefixes (e.g., term., metric., dim.)
  • Descriptions: Be clear and concise

Organization​

  • Group related terms: Use tags or categories
  • Document formulas: Include formulas for metrics
  • Define values: List possible values for dimensions

Maintenance​

  • Keep updated: Update glossary as business evolves
  • Link terms: Link terms to assets and columns
  • Review policies: Regularly review and update policies