Semantic Models
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:
Field | Required | Description |
---|---|---|
name | Yes | Unique name for the model. |
description | Yes | A human-readable description of the model. |
data_source_name | No | Specifies the name of the data source this model uses. Inherited from buster.yml if not specified. |
database | No | The database where the model’s underlying table resides. Inherited from buster.yml if not specified. |
schema | No | The schema within the database. Inherited from buster.yml if not specified. |
dimensions | No | A list of Dimension objects. Defaults to an empty list if omitted. |
measures | No | A list of Measure objects. Defaults to an empty list if omitted. |
metrics | No | A list of Metric objects. Defaults to an empty list if omitted. |
filters | No | A list of Filter objects. Defaults to an empty list if omitted. |
relationships | No | A list of Relationship objects. Defaults to an empty list if omitted. |
Dimension
Object
Dimensions represent categorical or descriptive attributes of your data.
Field | Required | Description |
---|---|---|
name | Yes | Unique name for the dimension within the model. |
description | Yes | A human-readable description of the dimension. |
type | Yes | The raw data type from the underlying database or data warehouse (e.g., VARCHAR , INT , TIMESTAMP ). |
searchable | No | Indicates if this dimension should be indexed for searching. Defaults to false if omitted. |
options | No | A list of predefined string values for this dimension, useful for categorical data. |
Measure
Object
Measures are aggregations performed on numeric fields.
Field | Required | Description |
---|---|---|
name | Yes | Unique name for the measure within the model. |
description | Yes | A human-readable description of the measure. |
type | Yes | The 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).
Field | Required | Description |
---|---|---|
name | Yes | Unique name for the metric within the model. |
expr | Yes | The expression defining the metric’s calculation. Can reference measures, dimensions, and arguments. |
description | Yes | A human-readable description of the metric. |
args | No | A 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.
Field | Required | Description |
---|---|---|
name | Yes | Unique name for the filter within the model. |
expr | Yes | The expression defining the filter’s condition. Can reference dimensions, measures, and arguments. |
description | Yes | A human-readable description of the filter. |
args | No | A 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.
Field | Required | Description |
---|---|---|
name | Yes | Name of the argument, used in the parent expr . |
type | Yes | The data type of the argument. Must be one of: string , number , date , boolean . |
description | Yes | A human-readable description of the argument. |
default | No | A 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.
Field | Required | Description |
---|---|---|
name | Yes | The name of the other model this relationship connects to. |
source_col | Yes | The name of the join key column in the current model. |
ref_col | Yes | The name of the join key column in the related model. |
description | Yes | A human-readable description of the relationship. |
type | No | Join type. If provided, must be one of: LEFT , INNER , RIGHT , FULL OUTER . Defaults to LEFT . |
cardinality | No | Relationship 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.