Dimensions and measures form the foundation of your semantic layer, defining the fields that can be used for filtering, grouping, and aggregation.

​
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.

dimensions:
  - name: order_date          # Required - dimension name
    description: Date ordered # Required - description
    type: date                # Optional - data type (string by default)
    searchable: true          # Optional - whether dimension can be searched (false by default)
    options: ["A", "B", "C"]  # Optional - list of allowed values

​
Required Fields

  • name: The field name, typically matching a column name in your database. It should represent a specific attribute of the model’s entity.
  • description: A clear explanation of what the dimension represents. This is mandatory.

​
Optional Fields

  • type: The data type of the dimension. Defining the correct type (e.g., date, timestamp, boolean, string) is crucial for proper handling and analysis.
  • searchable: Whether this dimension can be used in search queries. Defaults to false.
  • options: A list of allowed values for this dimension, useful for categorical data.

Dimension vs. Filter: While a boolean dimension (e.g., is_active) can be used for filtering, its primary purpose is to describe an attribute of the entity (e.g., the user is active). A dedicated Filter, on the other hand, defines a specific condition or subset (e.g., active_users_last_30_days). If a boolean concept represents a core attribute, define it as a dimension. If it represents a common filtering condition, especially one involving logic beyond a single column, define it as a Filter. See Defining Filters.

​
Measures

Measures are quantitative fields that can be aggregated, such as quantities or amounts.

measures:
  - name: amount            # Required - measure name
    description: Order amount in USD  # Required - description
    type: number            # Optional - data type (inferred if omitted)

​
Required Fields

  • name: The field name, typically matching a column name in your database
  • description: A clear explanation of what the measure represents. This is mandatory.

​
Optional Fields

  • type: The data type of the measure

​
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

models:
  - name: orders
    description: Customer orders
    dimensions:
      - name: id
        description: Unique order identifier
        type: string
      - name: order_date
        description: Date the order was placed
        type: date
        searchable: true
      - name: status
        description: Current order status
        options: ["pending", "shipped", "delivered", "cancelled"]
    measures:
      - name: amount
        description: Order amount in USD
        type: number
      - name: quantity
        description: Number of items ordered
        type: integer

​
Next Steps

Now that you’ve defined dimensions and measures, you can:

  1. Create metrics for business calculations
  2. Establish relationships between models