Syntax

Overview

Cubes and views are defined in YAML files. Understanding the syntax conventions helps you write correct and maintainable definitions.

File Structure

Cubes File

cubes:
  - name: orders
    sql_table: public.orders

    measures:
      - name: count
        type: count

    dimensions:
      - name: id
        type: number
        sql: id
        primary_key: true

Views File

views:
  - name: orders_overview
    cubes:
      - join_path: orders
        includes:
          - count
          - status

Naming Conventions

Cube and View Names

Use snake_case
Be descriptive: user_orders, not uo
Use plural for collections: orders, users

cubes:
  - name: orders           # Good
  - name: user_activity    # Good
  - name: Orders           # Bad - use lowercase
  - name: userOrders       # Bad - use snake_case

Member Names

Use snake_case
Be descriptive but concise

measures:
  - name: count                    # Good
  - name: total_revenue            # Good
  - name: average_order_value      # Good
  - name: aov                      # Bad - unclear abbreviation

SQL Expressions

Inline SQL

dimensions:
  - name: full_name
    type: string
    sql: "CONCAT(first_name, ' ', last_name)"

Multi-line SQL

Use YAML block scalar for complex SQL:

cubes:
  - name: orders
    sql: >
      SELECT
        o.*,
        u.name as user_name
      FROM orders o
      LEFT JOIN users u ON o.user_id = u.id

Common Patterns

Quoting

Quote SQL expressions with special characters:

# Quoted - required for expressions
sql: "\{CUBE\}.amount * 0.1"

# Unquoted - simple column reference
sql: amount

Arrays

# Inline array
includes: [count, total_revenue]

# Block array
includes:
  - count
  - total_revenue

Booleans

primary_key: true
public: false