Code reference

Modules

A module represents a table in your database. A module includes dimensions, join paths, and metrics, making it the foundation for how data is modeled and explored in Steep.

File structure

Keep yaml files modular by defining one module per file.

YAML

module:
  schema: "steep_demo_fintech"
  table: "customers"
  identifier: "customers"
  description: "Records of customers, including IDs, name, sign-up date."
  dimensions:
    - column: "user_country"
      type: "country"
  joinPaths:
    - from:
        column: "id"
      to:
        table: "transactions"
        column: "customer_id"
      type: "one-to-many"
  metrics:
    - identifier: "registrations"
      name: "Registrations"
      description: "Total number of user sign-ups."
      category: "Marketing"
      calculation: "count"
      time: "customers.created_at"

Parameters

Parameter	Type	Description	Required
`identifier`	`string`	Unique name for the module within the workspace.	Required
`schema`	`string`	Name of the database schema.	Required
`table`	`string`	Name of the database table.	Required
`label`	`string`	Display name for the module	Optional
`description`	`string`	A short explanation of the table's contents. Helps teams understand what data the module represents.	Optional
`dimensions`	`array`	Array of dimension definitions for this module	Optional
`metrics`	`array`	Array of metric definitions for this module	Optional
`joinPaths`	`array`	Array of join path definitions to other modules	Optional

Dimensions

A dimension represents a column in your database. Dimensions are used for breakdowns and filters. Examples of dimensions are country or segment.

YAML

dimensions:
  - column: "country"
    type: "country"
    label: "Country"
    description: "The country of the customer"
  - column: "email"
    type: "categorical"
    label: "E-mail"
    description: "The customer e-mail address"

Parameters

Parameter	Type	Description	Required
`column`	`string`	The name of the database column. The column name acts as the identifier of the dimension and is also used to match report filters. Dimensions can only be defined for string or boolean columns.	Required
`label`	`string`	The display name of the dimension. If not defined, the column name will be used.	Optional
`description`	`string`	A short explanation of what the dimension represents. Helps both data teams and business users understand its purpose. (currently not displayed for members)	Optional
`type`	`enum`	The dimension type. Possible values: `categorical`, `city`, `country`, `h3-cell-index`	Required

Join Paths

Join paths let you connect modules so that data from multiple modules can be combined into a single metric.

Define a join path in only one module. Once defined, the join can be used from both sides of the relationship.

Steep can automatically follow join paths up to two steps away.

YAML

This example joins the customers module to the transactions module using the id column on customers and customer_id on transactions.

joinPaths:
  - from:
      column: "id"
    to:
      table: "transactions"
      column: "customer_id"
    type: "one-to-many"

Parameters

Parameter	Type	Description	Required
`from`	`object`	A column in the from module (current module) that you want to join from.	Required
`to`	`object`	The column in the module that you want to join to.	Required
`type`	`enum`	Defines the relationship between the modules. Possible values: `one-to-one`, `one-to-many`	Required

Metrics

A metric is an aggregation or calculation built on top of your modules. It represents key business indicators like order volume, active users, or conversion rate.

Metric Parameters

Parameter	Type	Description	Required	Applies to
`identifier`	`string`	Unique metric identifier, used for referencing the metric.	Required
`name`	`string`	Display name of the metric.	Required
`description`	`string`	Explanation of what the metric measures. Helps data teams and business users understand its purpose.	Optional
`dimensions`	`array`	List of dimension columns available on the metric. Format: schema.table.column. schema and table are optional and can be omitted if same as current module. this.* can be used to get all dimensions from current module, while schema.table.* can be used to get all dimensions from a joined code module.	Optional
`category`	`string`	Metric category. You can add one category.	Optional
`time`	`string`	Column used to analyze the metric over time. Format: `table.column`. You can add only one time column.	Required
`owner_emails`	`array`	Email addresses of one or more metric owners. Must be workspace members.	Optional
`is_private`	`boolean`	Whether the metric is private. Defaults to false.	Optional
`is_unlisted`	`boolean`	Whether the metric is unlisted. Defaults to false.	Optional
`time_grains`	`array`	List of available time grains. Defaults to all time grains.	Optional
`time_resampling`	`enum`	Time resampling method. Defaults depends on the calculation type. Possible values: `sum/divide`, `average/repeat`	Optional
`slices`	`array`	One or more slices of the metric.	Optional
`filters`	`array`	One or more filters applied to the metric.	Optional
`calculation`	`literal`	Type of aggregation. Possible values: `sum`, `ratio`, `count`, `count-distinct`, `custom-value`, `custom-ratio`	Required
`value`	`string`	Column used for sum calculations. Format: `table.column`.	Required	sum
`numerator`	`string`	Column used for ratio calculations. Format: `table.column`.	Required	ratio
`denominator`	`string`	Column used for ratio calculations. Format: `table.column`.	Required	ratio
`format`	`enum`	Format of a ratio metric. Possible values: `number`, `percentage`	Required	ratio, custom-ratio
`distinct_on`	`string`	Column to count distinct values on. Format: `table.column`.	Required	count-distinct
`sql_expression`	`string`	SQL expression that returns the metric value. Columns mentioned in expression should be of format table.column.	Required	custom-value
`numerator_sql`	`string`	SQL expression for the ratio numerator. Columns mentioned in expression should be of format table.column.	Required	custom-ratio
`denominator_sql`	`string`	SQL expression for the ratio denominator. Columns mentioned in expression should be of format table.column.	Required	custom-ratio

Slice Parameters

Parameter	Type	Description	Required
`name`	`string`	Name of the metric slice.	Required
`filter`	`object`	Filter applied to the metric slice.	Required

Filter Parameters

Parameter	Type	Description	Required
`schema`	`string`	Name of the database schema. Optional if same schema as current module.	Optional
`table`	`string`	Name of the database table. Optional if same table as current module.	Optional
`column`	`string`	Name of the database column.	Required
`operator`	`enum`	The operator to use for the filter. Possible values: `equals`, `not-equals`, `less-than`, `less-than-or-equal`, `greater-than`, `greater-than-or-equal`, `in`, `not-in`, `is`, `is-not`, `like`, `not-like`	Required
`expression`	`string`	The expression to use for the filter.	Required

Metric examples

Example yaml code for different metric types.

Sum

metrics:
  - identifier: "order_vol"
    name: "Order volume"
    description: "Total sum of order value."
    category: "Operations"
    calculation: "sum"
    time: "orders.created_at"
    value: "orders.amount"
    owner_emails:
      - "vitor@company.com"
      - "ebba@company.com"
    is_private: true
    is_unlisted: true
    time_grains:
      - "weekly"
      - "monthly"
    filters:
      - column: "country"
        operator: "not-equals"
        expression: "test_country"
    slices:
      - name: "US"
        filter:
          column: "country"
          operator: "equals"
          expression: "US"

Count

metrics:
  - identifier: "orders"
    name: "Orders"
    description: "Number of orders."
    category: "Operations"
    calculation: "count"
    time: "orders.created_at"
    owner_emails:
      - "vitor@company.com"
      - "ebba@company.com"
    filters:
      - column: "country"
        operator: "not-equals"
        expression: "test_country"

Ratio

metrics:
  - identifier: "conversion_rate"
    name: "Conversion rate"
    description: "Conversion rate measures the percentage of users who sign-up."
    calculation: "ratio"
    time: "site.visit_at"
    numerator: "site.conversions"
    denominator: "site.visits"
    format: "percentage"

Unique count

metrics:
  - identifier: "active_users"
    name: "Active users"
    description: "A user is considered active when they've made a transaction during the period"
    calculation: "count-distinct"
    time: "transactions.created_at"
    distinct_on: "customers.customer_id"

Custom Value

metrics:
  - identifier: "partner_orders"
    name: "Partner orders"
    description: "Orders coming in through partner."
    calculation: "custom-value"
    time: "orders.created_at"
    sql_expression: "SUM(CASE WHEN customers.type = 'partner' THEN orders.order_volume END)"

Custom Ratio

metrics:
  - identifier: "kyc_approved"
    name: "KYC Approved %"
    description: "Percentage of users approved through KYC processes. KYC stands for 'Know Your Customer': used to verify a customer's identity and assess risk, helping prevent fraud and financial crimes."
    calculation: "custom-ratio"
    time: "customers.created_at"
    numerator_sql: "SUM(CASE WHEN customers.country != 'SE' THEN 1 END)"
    denominator_sql: "COUNT(*)"
    format: "percentage"