Dimensions and Measures
Define fields and their properties in your semantic layer
Introduction to Dimensions and Measures
Dimensions and measures are the fundamental building blocks of your semantic models. They define the fields available for analysis, describing your data and enabling calculations.
- Dimensions are descriptive attributes (like product category, date, or user ID) used for grouping and filtering.
- Measures are quantifiable values (like sales amount, quantity, or cost) used for aggregations and calculations.
Here’s the basic structure for defining them within a model:
Dimensions
Dimensions represent the descriptive attributes or characteristics of your data. They are typically non-numeric or categorical fields used to slice, dice, group, and filter data. Think of them as the “who, what, where, when, why” of your analysis. Examples include dates, user IDs, product categories, geographical locations, or status flags.
Field | Required | Description |
---|---|---|
name | Yes | Unique name for the dimension within the model. Typically matches a column name. |
description | Yes | A human-readable description of the dimension. This is mandatory. |
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. |
Measures
Measures are quantitative fields that can be aggregated, such as quantities or amounts.
Field | Required | Description |
---|---|---|
name | Yes | Unique name for the measure within the model. Typically matches a column name. |
description | Yes | A human-readable description of the measure. This is mandatory. |
type | Yes | The underlying column type as defined in the database/warehouse. Supported aggregation types depend on the query engine. |
Best Practices
Descriptive Names
Use clear, business-oriented names that convey meaning.
Add Descriptions
Include detailed descriptions to help Buster understand the context.
Set Data Types
Explicitly setting types ensures proper handling of values.
Include Units
Mention units of measurement in descriptions (e.g., “in USD”, “in days”).
Example
Let’s illustrate these concepts with a practical example using our standardized orders
semantic model. This model represents data about customer orders.
Dissecting the Example:
dimensions
:order_id
: This is a classic dimension. While it might be numeric or a string, its primary purpose is identification, not calculation. You use it to find specific orders.customer_id
: This is a classic dimension. While it might be numeric or a string, its primary purpose is identification, not calculation. You use it to find specific orders.order_date
: Dates are dimensions because they provide context (when something happened). You use them to filter (“orders this week”) or group (“revenue by month”). Making itsearchable: true
optimizes queries that filter by this date.status
: This is categorical text. It describes the state of an order. You use it to group (“count of orders by status”) or filter (“show only ‘shipped’ orders”). Theoptions
list helps ensure data consistency and can populate UI elements.
measures
:amount
: This is a core measure. It’s a numeric value representing how much. You’ll typically perform mathematical operations on it, likeSUM(amount)
for total revenue orAVG(amount)
for average order value. The description clarifies the unit (USD).item_count
: Similar toamount
, this is a numeric value representing how many. It’s meant for aggregation likeSUM(item_count)
to find the total number of items sold.
This structure clearly separates the descriptive attributes (dimensions) used for context and filtering from the quantifiable values (measures) used for calculations and aggregations.
Next Steps
Now that you’ve defined dimensions and measures, you can:
- Create metrics for business calculations
- Establish relationships between models