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"
      type: "count"
      time: "customers.created_at"
      dimensions:
        - "country"

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
`accessPolicies`	`array`	Array of access policy definitions for this module.	Optional

Access policy

An access policy controls which rows each workspace member can access. Access policies are defined on modules and filter data based on user attributes. Read more →

Access policies are defined as a list under accessPolicies within a module. Multiple policies on the same module are combined with AND.

YAML

accessPolicies:
  - column: "account_id"
    attribute: "user.account_id"
  - schema: "steep_demo_fintech"
    table: "transactions"
    column: "country"
    attribute: "user.market"

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`	The column that contains the row-level information to filter on.	Required
`attribute`	`string`	The user attribute that will determine how the policy filters data for each member, in user.<name> format.	Required

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`, `time`	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.

Metrics are defined in the module that represents the table that the metric is calculated on. Derived ratio metrics, which are not based on any table, can be defined in any module, but it is recommended to define them in the same module as the numerator metric.

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
`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
`type`	`enum`	Metric type. Possible values: `derived-ratio`, `sum`, `ratio`, `count`, `count-distinct`, `custom-value`, `custom-ratio`	Required
`numerator`	`string`	For ratio metrics, the column used for ratio calculations in the format: `table.column`. For derived ratio metrics, the identifier of the metric used as the numerator.	Required	derived-ratio, ratio
`denominator`	`string`	For ratio metrics, the column used for ratio calculations in the format: `table.column`. For derived ratio metrics, the identifier of the metric used as the denominator.	Required	derived-ratio, ratio
`format`	`string`	Format of a ratio metric. Defaults to 'percentage'.	Optional	derived-ratio, ratio, custom-ratio
`time`	`string`	Column used to analyze the metric over time. Format: `table.column`. You can add only one time column.	Required	sum, ratio, count, count-distinct, custom-value, custom-ratio
`value`	`string`	Column used for sum calculations. Format: `table.column`.	Required	sum
`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"
    type: "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"
    dimensions:
      - "this.*"

Count

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

Ratio

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

Unique count

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

Custom Value

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

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."
    type: "custom-ratio"
    time: "customers.created_at"
    numerator_sql: "SUM(CASE WHEN customers.country != 'SE' THEN 1 END)"
    denominator_sql: "COUNT(*)"
    format: "percentage"
    dimensions:
      - "this.*"

Derived Ratio

metrics:
  - identifier: "orders_per_active_user"
    name: "Orders per Active User"
    description: "Number of orders per active customer"
    category: "Commercial"
    numerator: "orders"
    denominator: "active_customers"
    type: "derived-ratio"
    format: "number"
    dimensions:
      - "this.*"