​

Cube style guide

• All users of Cube Cloud and self-hosted Cube Core deployments.
• Solution integrators from the Cube Partner Network.
• Cube team (for demo projects, documentation, and customer engagements).

​

Syntax

• Default to YAML syntax for data modeling.
• Use snake case when using either YAML or JavaScript syntax.
• Follow the recommendations on YAML syntax and SQL syntax below.

​

Folder structure

• Put cube and view files in model/cubes and model/views folders.
• Within these folders, create subfolders to reflect your business units structure.

cube_project
└── model
    ├── cubes
    │   ├── finance
    │   │   ├── stripe_invoices.yml
    │   │   └── stripe_payments.yml
    │   └── sales
    │       └── base_opportunities.yml
    └── views
        ├── product
        │   └── cloud_tenants.yml
        └── sales
            └── opportunities.yml

​

Cubes

• Cubes should remain private; set public: false for all cubes. Only views can be exposed to visualization tools.
• A cube’s name should represent a business entity and be plural. If a cube’s name may clash with a view’s name, add the base_ prefix to the cube’s name, e.g., base_opportunities.yml.
• If possible, use sql_table instead of sql, i.e., use sql_table: schema.table instead of sql: SELECT * FROM schema.table.
• Use many_to_one, one_to_many, one_to_one join relationship types instead of belongs_to, has_many, has_one.
• Applicable cube parameters should be ordered as follows:
  • name
  • sql_alias
  • extends
  • data_source
  • sql
  • sql_table
  • title
  • description
  • public
  • refresh_key
  • meta
  • pre_aggregations
  • joins
  • dimensions
  • hierarchies
  • segments
  • measures
  • access_policy

​

Dimensions & measures

• Primary key of the cube should be the first dimension listed.
• Applicable dimension and measure parameters should be ordered as follows:
  • name
  • title
  • description
  • sql
  • type
  • primary_key
  • sub_query
  • public
  • format
  • filters
  • drill_members
• Use title and description if the name is not intuitive.

​

Example cube

cubes:
  - name: line_items
    sql_table: public.line_items
    public: false

    joins:
      - name: products
        sql: "{CUBE}.product_id = {products.id}"
        relationship: many_to_one

      - name: orders
        sql: "{CUBE}.order_id = {orders.id}"
        relationship: many_to_one

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

      - name: created_date
        sql: created_at
        type: time

    measures:
      - name: count
        type: count

      - name: total_amount
        sql: price
        type: sum

​

Views

• Views should be designed for data consumers and optimized for consumption in visualization tools.
• Applicable view parameters should be ordered as follows:
  • name
  • description
  • public
  • cubes
  • folders
  • access_policy

​

Example view

views:
  - name: orders

    cubes:
      - join_path: base_orders
        includes:
          # dimensions
          - status
          - created_date

          # measures
          - total_amount
          - total_amlunt_shipped
          - count
          - average_order_value

      - join_path: base_orders.line_items.products
        includes:
          - name: name
            alias: product

      - join_path: base_orders.line_items.products.product_categories
        includes:
          - name: name
            alias: product_category

      - join_path: base_orders.users
        prefix: true
        includes:
          - city

​

SQL style guide

• Indent with 2 spaces.
• Use trailing commas.
• Use upper case for SQL keywords and function names.
• Use != instead of <>.
• Always use the AS keyword when aliasing columns, expressions, and tables.
• Unless SQL query is a trivial one-liner, start SQL query from the new line.
• Use new lines, optimize for readability and maintainability.
• Use common table expressions (CTE) rather than subqueries.
• When joining multiple tables, always prefix the column names with the table name/alias.
• Use single quotes for strings.
• Avoid initialisms and unnecessary table aliases.
• If there’s only one thing in the list (e.g., projection expressions in SELECT), put it on the same line as the opening keyword.
• If there are multiple things in the list, put each one on its own line (including the first one), indented one level more than the opening keyword.

​

Example SQL

cubes:
  - name: california_users
    sql: |
      SELECT
        id,
        first_name,
        last_name
      FROM public.users WHERE state = 'CA'

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

      - name: first_name
        sql: first_name
        type: string

      - name: last_name
        sql: last_name
        type: string

    measures:
      - name: count
        type: count

​

YAML style guide

• Use .yml extension instead of .yaml.
• Indent with 2 spaces.
• Indent list items.
• Use a new line to separate list items that are dictionaries, where appropriate.
• Make sure lines are no longer than 80 characters.
• Prefer literal style (|) for multi-line strings over folded style (>).
• If quotes are needed around a string, use double quotes.

​

Example YAML

cubes:
  - name: users
    description: |
      All users in the system.
      Note that this dataset contains PII data.
    sql_table: public.users

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

      - name: city
        sql: city
        type: string

      - name: lifetime_value
        sql: "{line_items.total_amount}"
        type: number
        sub_query: true

    measures:
      - name: count
        type: count

      - name: total_orders_amount
        sql: "{lifetime_value}"
        type: sum

​

JavaScript style guide

• Indent with 2 spaces.
• Don’t use trailing semicolons.
• Don’t use trailing commas after last elements of arrays and objects.
• Use a new line to separate list items that are objects, where appropriate.
• Make sure lines are no longer than 80 characters.
• If quotes are needed around a string, use backticks.

​

Example JavaScript

cube(`users`, {
  sql_table: `public.users`,

  dimensions: {
    id: {
      sql: `id`,
      type: `number`,
      primary_key: true
    },

    city: {
      sql: `city`,
      type: `string`
    },

    lifetime_value: {
      sql: `${line_items.total_amount}`,
      type: `number`,
      sub_query: true
    }
  },

  measures: {
    count: {
      type: `count`
    },

    total_orders_amount: {
      sql: `${lifetime_value}`,
      type: `sum`
    }
  }
})

​

Credits

• Brooklyn Data Co. SQL style guide
• LAMS Style Guide