This document provides the YAML specification for defining semantic models. It outlines the structure and available fields for configuring your semantic layer.

​
Model Object

The Model object is the root object for defining a semantic model. It contains the following fields:

FieldRequiredDescription
nameYesUnique name for the model.
descriptionYesA human-readable description of the model.
data_source_nameNoSpecifies the name of the data source this model uses. Inherited from buster.yml if not specified.
databaseNoThe database where the model’s underlying table resides. Inherited from buster.yml if not specified.
schemaNoThe schema within the database. Inherited from buster.yml if not specified.
dimensionsNoA list of Dimension objects. Defaults to an empty list if omitted.
measuresNoA list of Measure objects. Defaults to an empty list if omitted.
metricsNoA list of Metric objects. Defaults to an empty list if omitted.
filtersNoA list of Filter objects. Defaults to an empty list if omitted.
relationshipsNoA list of Relationship objects. Defaults to an empty list if omitted.

​
Dimension Object

Dimensions represent categorical or descriptive attributes of your data.

FieldRequiredDescription
nameYesUnique name for the dimension within the model.
descriptionYesA human-readable description of the dimension.
typeYesThe raw data type from the underlying database or data warehouse (e.g., VARCHAR, INT, TIMESTAMP).
searchableNoIndicates if this dimension should be indexed for searching. Defaults to false if omitted.
optionsNoA list of predefined string values for this dimension, useful for categorical data.

​
Measure Object

Measures are aggregations performed on numeric fields.

FieldRequiredDescription
nameYesUnique name for the measure within the model.
descriptionYesA human-readable description of the measure.
typeYesThe underlying column type is defined in the database/warehouse. Supported aggregation types depend on the query engine.

​
Metric Object

Metrics are calculations or expressions derived from measures, dimensions, or other metrics, often representing key performance indicators (KPIs).

FieldRequiredDescription
nameYesUnique name for the metric within the model.
exprYesThe expression defining the metric’s calculation. Can reference measures, dimensions, and arguments.
descriptionYesA human-readable description of the metric.
argsNoA list of Argument objects to parameterize the metric’s expression. Defaults to an empty list if omitted.

​
Filter Object

Filters define reusable conditions that can be applied to queries.

FieldRequiredDescription
nameYesUnique name for the filter within the model.
exprYesThe expression defining the filter’s condition. Can reference dimensions, measures, and arguments.
descriptionYesA human-readable description of the filter.
argsNoA list of Argument objects to parameterize the filter’s expression. Defaults to an empty list if omitted.

​
Argument Object

Arguments are used to parameterize Metric and Filter expressions, allowing for dynamic input at query time.

FieldRequiredDescription
nameYesName of the argument, used in the parent expr.
typeYesThe data type of the argument. Must be one of: string, number, date, boolean.
descriptionYesA human-readable description of the argument.
defaultNoA default value for the argument if none is provided at query time.

​
Relationship Object

Relationships (aliased as entities in YAML) define how this model connects to other models, effectively specifying join conditions.

FieldRequiredDescription
nameYesThe name of the other model this relationship connects to.
source_colYesThe name of the join key column in the current model.
ref_colYesThe name of the join key column in the related model.
descriptionYesA human-readable description of the relationship.
typeNoJoin type. If provided, must be one of: LEFT, INNER, RIGHT, FULL OUTER. Defaults to LEFT.
cardinalityNoRelationship cardinality. If provided, must be one of: one-to-one, one-to-many, many-to-one, many-to-many.

​
Example

Below is an example YAML configuration illustrating the usage of these objects, presented as individual model files. This example is derived from the system’s internal test suite.

# Example: culture.yml
name: culture
description: Core model for cultural groups
dimensions:
  - name: cultureid
    description: Unique identifier for the culture
  - name: name
    description: Culture name
    options: ["Western", "Eastern"]
    searchable: false # Explicitly showing default
measures:
  - name: revenue
    description: Revenue generated by the culture
    type: sum
filters:
  - name: active_subscribed_customer
    expr: "logins.login_count > {threshold} AND subscriptions.subscription_status = 'active'"
    args:
      - name: threshold
        type: integer
        description: Minimum number of logins
    description: Customers with logins above threshold and active subscription
metrics:
  - name: popular_product_revenue
    expr: "SUM(revenue) WHERE culture_products.product_count > 5" # Assuming 'revenue' is a measure in 'culture'
    description: Revenue from cultures with popular products
relationships:
  - name: logins # Related model name
    source_col: cultureid # Key in 'logins' model
    ref_col: cultureid    # Key in 'culture' model
    type: LEFT
    cardinality: one-to-many
    description: Links to login activity
  - name: subscriptions
    source_col: cultureid # Key in 'subscriptions' model
    ref_col: cultureid    # Key in 'culture' model
    cardinality: one-to-one
    description: Links to subscription data (type defaults to LEFT)
  - name: culture_products
    source_col: cultureid # Key in 'culture_products' model
    ref_col: cultureid    # Key in 'culture' model
    cardinality: many-to-many # This implies culture_products is a junction model
    description: Links to product associations (many-to-many via junction)

# Example: logins.yml
name: logins
description: Tracks user logins by culture
dimensions:
  - name: cultureid
    description: Foreign key to culture
  - name: login_timestamp
    description: Timestamp of the login
    type: timestamp
measures:
  - name: login_count
    description: Number of logins
    type: count
relationships: # Relationships
  - name: culture
    source_col: cultureid # Key in 'culture' model
    ref_col: cultureid    # Key in 'logins' model
    cardinality: many-to-one
    description: Links back to the culture model

# Example: subscriptions.yml
name: subscriptions
description: Subscription status for cultures
dimensions:
  - name: cultureid
    description: Foreign key to culture
  - name: subscription_status
    description: Current subscription status
    options: ["active", "inactive", "pending"]
    type: string
relationships: # Relationships
  - name: culture
    source_col: cultureid # Key in 'culture' model
    ref_col: cultureid    # Key in 'subscriptions' model
    cardinality: one-to-one # Assuming one subscription record per culture
    description: Links back to the culture model

# Example: culture_products.yml
name: culture_products # Junction Model Example
description: Junction table linking cultures to products, demonstrating many-to-many.
dimensions:
  - name: cultureid
    description: Foreign key to culture
  - name: productid
    description: Foreign key to products
measures:
  - name: product_count # Example measure on a junction table
    description: Could be a count of distinct products per culture if aggregated, or just a field.
    type: count_distinct # Or other relevant aggregation if 'productid' is the target.
                       # If it's just a quantity field on the junction, it might be 'sum'.
relationships: # Relationships
  - name: culture
    source_col: cultureid # Key in 'culture' model
    ref_col: cultureid    # Key in 'culture_products' model
    cardinality: many-to-one # Many culture_products entries can map to one culture
    description: Links to the culture
  - name: products
    source_col: productid # Key in a 'products' model (not fully defined here)
    ref_col: productid   # Key in 'culture_products' model
    cardinality: many-to-one # Many culture_products entries can map to one product
    description: Links to the product