Skip to main content

​
Overview

Globals allow you to define reusable objects (entities, dimensions, measures, descriptions, and more) in a centralized location and reference them across multiple specifications. This reduces duplication, ensures consistency, and makes maintenance easier.

​
Key Benefits

  • Single Source of Truth: Define common objects once in the globals/ directory
  • Inheritance Support: Use inherits_from to extend global definitions
  • Template Variables: Reference global values in semantic views and workflows
  • On-Demand Loading: Files are loaded only when needed with intelligent caching
  • Reduced Duplication: Avoid repeating the same dimension/entity/measure definitions

​
Project Structure

Place your globals file in the globals/ directory at your project root: 
your-project/
├── config.yml
├── globals/
│   └── semantics.yml          # Global definitions
├── semantics/
│   ├── topics/
│   │   └── sales.topic.yml
│   └── views/
│       ├── orders.view.yml    # Can inherit from globals
│       └── customers.view.yml
└── semantics.yml              # Can inherit from globals

​
Defining Globals

Create a globals/semantics.yml file with reusable objects:
globals/semantics.yml
# Reusable entities (defined as object/map with keys)
entities:
  customer:
    name: customer
    type: primary
    description: Primary customer entity
    key: customer_id
  
  order:
    name: order
    type: primary
    description: Order entity
    key: order_id

# Reusable dimensions (defined as object/map with keys)
dimensions:
  customer_id:
    name: customer_id
    type: number
    description: Unique customer identifier
    expr: customer_id
  
  user_id:
    name: user_id
    type: number
    description: Unique user identifier
    expr: user_id
  
  email:
    name: email
    type: string
    description: Email address
    expr: email
  
  timestamp:
    name: timestamp
    type: datetime
    description: Timestamp of the event or record
    expr: timestamp

# Reusable measures (defined as object/map with keys)
measures:
  total_sales:
    name: total_sales
    type: sum
    description: Total sales amount
    expr: amount
    
  total_orders:
    name: total_orders
    type: count
    description: Total number of orders

# Reusable descriptions
descriptions:
  shipping_address: "Shipping address for the order"
  order_status: "Current status of the order"

# Global table names
tables:
  users: "users"
  orders: "orders"
  customers: "customers"

​
Using Globals

​
Inheritance in Semantic Views

Use inherits_from to inherit properties from global definitions:
semantics/views/orders.view.yml
name: orders
description: Customer orders
datasource: local
table: "{{globals.semantics.tables.orders}}.csv"

entities:
  - name: customer
    inherits_from: globals.semantics.entities.customer
    # Inherits: type=primary, description, key (from "customer" entity in globals)

dimensions:
  - inherits_from: globals.semantics.dimensions.customer_id
    # Inherits all properties from global definition (customer_id dimension)
  
  - name: order_status
    type: string
    description: "{{globals.semantics.descriptions.order_status}}"
    expr: status

measures:
  - inherits_from: globals.semantics.measures.total_orders
    # Inherits from "total_orders" measure in globals

​
Inheritance in semantics.yml

The semantics.yml file supports inheritance to avoid repeating dimension properties across multiple target mappings:
semantics.yml
dimensions:
  # Inherit common properties, specify unique targets
  - name: id_user
    inherits_from: globals.semantics.dimensions.user_id
    targets:
      - primary_database.dbt_prod_core.dim_users.id_user
      - primary_database.dbt_prod_core.fct_user_events.id_user
    # Inherits: type=number, description="Unique user identifier" (from "user_id" dimension)
  
  - name: another_user_id
    inherits_from: globals.semantics.dimensions.user_id
    targets:
      - primary_database.dbt_prod_core.dim_customers.user_id
    # Inherits: type=number, description="Unique user identifier" (from "user_id" dimension)
  
  # Regular dimension without inheritance
  - name: email
    inherits_from: globals.semantics.dimensions.email
    targets:
      - primary_database.dbt_prod_core.dim_users.email
      - primary_database.dbt_prod_core.fct_typeform_leads.email

​
Template Variables

Reference global values using template syntax:
semantics/views/users.view.yml
name: users
table: "{{globals.semantics.tables.users}}.csv"
description: "{{globals.semantics.descriptions.user_entity}}"

dimensions:
  - name: user_email
    type: string
    description: "{{globals.semantics.descriptions.email}}"
    expr: email

​
Workflow Variables

Pass global values to workflow tasks:
workflows/sales-report.workflow.yml
variables:
  orders_table:
    description: The name of the orders table
    type: string
    default: "{{globals.semantics.tables.orders}}"

tasks:
  - name: query_sales
    type: semantic_query
    topic: sales
    dimensions:
      - orders.order_id
    variables:
      orders_table: "{{orders_table}}"

​
Reference Syntax

Global references use dot-notation: globals.<file>.<path>
  • File: semantics (name of the file in globals/ without .yml extension)
  • Path: Dot-separated path to the object within the file
The path navigates through the YAML structure using object paths, not the name property. For semantic objects like entities, dimensions, and measures that are defined as objects/maps, use the key: <type>.<key>. For simple key-value pairs like descriptions and tables, the path is just <section>.<key>. Examples:
  • globals.semantics.entities.customer - Entity with key “customer”
  • globals.semantics.dimensions.customer_id - Dimension with key “customer_id”
  • globals.semantics.measures.total_sales - Measure with key “total_sales”
  • globals.semantics.descriptions.shipping_address - Description value
  • globals.semantics.tables.users - Table name value

​
Property Merging

When using inherits_from, child properties override parent properties: 
# globals/semantics.yml
dimensions:
  customer_id:
    name: customer_id
    type: number
    description: Unique customer identifier
    expr: customer_id

# semantics/views/orders.view.yml
dimensions:
  - name: customer_id
    inherits_from: globals.semantics.dimensions.customer_id
    description: Customer who placed the order  # Overrides global description
    # type and expr are inherited from "customer_id" dimension in globals

​
See Also