Qyra
DocsAPI
ExploreMetrics catalog

Catalog

Browse, explore, and curate your metrics in the Metrics Catalog

Browsing the catalog

Browse all the project metrics you have access to (based on permissions and user-attributes) in the Metrics Catalog.

The Metrics Catalog listing metrics with their descriptions, categories and popularity, and a search bar above

  1. Search: Easily find metrics by their names or .yml descriptions using the searchbar.

  2. View .yml descriptions: Click on any description to expand and view the full content, including rendered Markdown.

  3. Categories: Use categories to streamline your metrics and KPIs. Filter metrics by category and add new ones directly in the UI. Users with editor permissions and above can click on any category cell to edit, rename, change its color, or delete it.

  4. View popularity: Discover a metric's popularity and see where it's being used. Click to explore a complete list of charts which use the metric. Metrics are sorted by default to highlight the most used ones first.

  5. Explore: Interactive viewers and above can dive deeper by clicking Explore to visualize the metric in a chart format.

Exploring a metric

Visualize your metrics in the Metrics Explorer.

The Metrics Explorer with a metric plotted as a line over time, and controls for date range, granularity, dimension filter, segment-by and comparison

  1. Plot over time: View your selected metric plotted over a time dimension as a line chart. You can adjust this dimension or set a default time dimension in your .yml to simplify the process for users. See how

  2. Filter by date: Use the date picker with convenient presets for quick selection. See how default presets work based on the granularity

  3. Adjust the time granularity: Refine your view by choosing the desired level of date granularity.

  4. Filter by a dimension: Filter your metric by any string or boolean dimension from the same table.

  5. Segment-by: Break down the metric by any non-time dimension in your dataset.

  6. Compare to:

    • 'This time last year': Compare the selected time period to the same period last year

    • 'Another metric': Compare to another metric from the same table that has a default time dimension specified in the .yml. See how

    Cross-table metric comparison (including joined tables) is not yet supported but is planned. See GitHub issue #21003 for updates.

  7. Drag to zoom: Click and drag across the chart to highlight the desired time range or data points, then release to zoom in on that segment. Hit 'Reset Zoom' to reset chart.

Curating Metrics Catalog for your business users

Metrics Catalog is designed to be a tool for your business users to explore and understand your data.

To make Metrics Catalog more useful for your business users, you can curate the metrics they can see and explore.

To do this, you can:

  • Control the visibility of metrics in the catalog

  • Add categories to your metrics

  • Add default time settings to your metrics

All through your Qyra .yml files. Metrics curation is configured under the spotlight key — see the spotlight config for an overview of what it covers.

Configuring global visibility of metrics

You can control the visibility of metrics in the catalog by creating a new file called qyra.config.yml in the root of your dbt project.

If you're new to qyra.config.yml, check out our getting started guide to learn how to create and set up this file.

See this video for an example on how to set this up:

Step-by-step guide

  1. Add the following to your qyra.config.yml file:
spotlight:
  default_visibility: show

The default visibility can be set to show or hide.

If you don't set this, the default visibility will be show, so all metrics will be visible in the catalog by default (but other settings like user attributes will still apply).

This will set the default visibility of metrics in the catalog to show for all metrics in your project. You can also set this to hide if you prefer to hide metrics by default and then override this on a per-model/metric basis.

  1. Now that you've set the default visibility, you can override this on a per-model/metric basis.
models:
  - name: events
    config:
      meta:
        spotlight:
          visibility: hide
models:
  - name: events
    meta:
      spotlight:
        visibility: hide
type: model
name: events

spotlight:
  visibility: hide

This will hide the events model from the catalog.

  1. If there are metrics in the events model that you want to make visible, you can override the default visibility for those metrics.
models:
  - name: events
    config:
      meta:
        spotlight:
          visibility: hide
        metrics:
          event_count:
            type: count
            spotlight:
              visibility: show
models:
  - name: events
    meta:
      spotlight:
        visibility: hide
      metrics:
        event_count:
          type: count
          spotlight:
            visibility: show
type: model
name: events

spotlight:
  visibility: hide

metrics:
  event_count:
    type: count
    spotlight:
      visibility: show
  1. Once you compile your project, you'll see the event_count metric in the catalog, even though the events model is hidden.

Assigning categories to metrics

Categories are a great way to organize your metrics in the catalog. You can create a new category by adding a new categories field to your qyra.config.yml file.

Here's a video showing how to set this up:

Step-by-step guide

  1. Add the following to your qyra.config.yml file:
spotlight:
  categories:
    revenue: # Required, this is the name of the category, and how it will be referenced in the catalog. It must be unique.
      label: Revenue # Required, this is what will be displayed in the catalog
      color: "orange" # Optional, defaults to "gray", with the option to choose from a range of colors: "gray", "violet", "red", "orange", "green", "blue", "indigo", "pink", "yellow"
  1. Now that you've added a category, you can assign metrics to it by adding a categories field to your models .yml file.
models:
  - name: events
    config:
      meta:
        spotlight:
          visibility: show
          categories:
            - revenue
models:
  - name: events
    meta:
      spotlight:
        visibility: show
        categories:
          - revenue
type: model
name: events

spotlight:
  visibility: show
  categories:
    - revenue

This will add the revenue category to all metrics in the events model.

If you want to add another category to a specific metric, you can do so by adding the categories field to the metric's .yml file. And remember, you can only add categories that have been defined in the qyra.config.yml file.

  1. Now you can add the marketing category to the event_count metric: So in your qyra.config.yml file, you need to have another category. Let's call it marketing and add it to the event_count metric, like so:
spotlight:
  categories:
    marketing:
      label: Marketing
      color: "blue"
    revenue:
      label: Revenue
      color: "orange"

Now you can add the marketing category to the event_count metric:

models:
  - name: events
    config:
      meta:
        spotlight:
          visibility: show
          categories:
            - revenue
        metrics:
          event_count:
            type: count
            spotlight:
              categories:
                - marketing
models:
  - name: events
    meta:
      spotlight:
        visibility: show
        categories:
          - revenue
      metrics:
        event_count:
          type: count
          spotlight:
            categories:
              - marketing
type: model
name: events

spotlight:
  visibility: show
  categories:
    - revenue

metrics:
  event_count:
    type: count
    spotlight:
      categories:
        - marketing

In this example, the event_count metric will have both the marketing and revenue categories, it's cumulative.

  1. Once you compile your project, you'll see the event_count metric in the catalog with both the marketing and revenue categories and you can use this to filter your metrics in the catalog.

The categories you define need to be unique, so you can't have two categories with the same name.

If you try to add a category with the same name as an existing category, you'll get an error. This error will be displayed in the UI and in the terminal (if you use the Qyra CLI) when you compile your project.

Assigning owners to metrics

You can assign owners to metrics using the spotlight.owner property. The owner displays in the metrics catalog with their name and avatar.

Set an owner at the metric level

models:
  - name: orders
    columns:
      - name: amount
        config:
          meta:
            metrics:
              total_revenue:
                type: sum
                spotlight:
                  owner: alice@yourcompany.com
models:
  - name: orders
    columns:
      - name: amount
        meta:
          metrics:
            total_revenue:
              type: sum
              spotlight:
                owner: alice@yourcompany.com
type: model
name: orders

dimensions:
  - name: amount

metrics:
  total_revenue:
    type: sum
    sql: ${TABLE}.amount
    spotlight:
      owner: alice@yourcompany.com

Set a default owner at the model level

You can set a default owner for all metrics in a model. Metric-level owners override the model-level default.

models:
  - name: orders
    config:
      meta:
        spotlight:
          owner: bob@yourcompany.com  # default for all metrics in this model
    columns:
      - name: amount
        config:
          meta:
            metrics:
              total_revenue:
                type: sum
                spotlight:
                  owner: alice@yourcompany.com  # overrides model owner
              avg_revenue:
                type: average
                # inherits bob@yourcompany.com from model
models:
  - name: orders
    meta:
      spotlight:
        owner: bob@yourcompany.com  # default for all metrics in this model
    columns:
      - name: amount
        meta:
          metrics:
            total_revenue:
              type: sum
              spotlight:
                owner: alice@yourcompany.com  # overrides model owner
            avg_revenue:
              type: average
              # inherits bob@yourcompany.com from model
type: model
name: orders

spotlight:
  owner: bob@yourcompany.com  # default for all metrics in this model

dimensions:
  - name: amount

metrics:
  total_revenue:
    type: sum
    sql: ${TABLE}.amount
    spotlight:
      owner: alice@yourcompany.com  # overrides model owner
  avg_revenue:
    type: average
    sql: ${TABLE}.amount
    # inherits bob@yourcompany.com from model
  • Use the email address of a Qyra user in your organization.
  • Metric-level owner takes precedence over model-level.
  • You can filter by owner in the Metrics Catalog UI.
  • If the email doesn't match a Qyra user, the metric shows as "Unassigned".

Controlling filtering and segmentation options

You can control which dimensions appear in the filter and segment-by dropdowns when exploring metrics. This helps users focus on relevant dimensions. You can also pre-apply a default segment and filter so users land on the most useful view as soon as they open a metric.

Hide a dimension from all metrics

Use boolean values at the dimension level to hide a dimension from filter or segment-by dropdowns for all metrics in that model:

models:
  - name: orders
    columns:
      - name: internal_tracking_id
        config:
          meta:
            dimension:
              spotlight:
                filter_by: false   # hide from filter dropdown
                segment_by: false  # hide from segment-by dropdown
models:
  - name: orders
    columns:
      - name: internal_tracking_id
        meta:
          dimension:
            spotlight:
              filter_by: false   # hide from filter dropdown
              segment_by: false  # hide from segment-by dropdown
type: model
name: orders

dimensions:
  - name: internal_tracking_id
    spotlight:
      filter_by: false   # hide from filter dropdown
      segment_by: false  # hide from segment-by dropdown

Allowlist specific dimensions for a metric

Use an array of dimension names at the metric level to create an allowlist of dimensions for that specific metric:

models:
  - name: orders
    columns:
      - name: amount
        config:
          meta:
            metrics:
              total_revenue:
                type: sum
                spotlight:
                  filter_by:
                    - status
                    - region
                    - order_date
                  segment_by:
                    - status
                    - customer_segment
models:
  - name: orders
    columns:
      - name: amount
        meta:
          metrics:
            total_revenue:
              type: sum
              spotlight:
                filter_by:
                  - status
                  - region
                  - order_date
                segment_by:
                  - status
                  - customer_segment
type: model
name: orders

dimensions:
  - name: amount

metrics:
  total_revenue:
    type: sum
    sql: ${TABLE}.amount
    spotlight:
      filter_by:
        - status
        - region
        - order_date
      segment_by:
        - status
        - customer_segment

Set a default segment and filter for a metric

While segment_by and filter_by control which dimensions are available, default_segment and default_filter control which are pre-selected when a metric is opened. Use them when a metric is almost always viewed the same way (e.g., revenue segmented by region, or active users filtered to a specific status), so users don't have to set it up themselves every time.

models:
  - name: orders
    columns:
      - name: amount
        config:
          meta:
            metrics:
              total_revenue:
                type: sum
                spotlight:
                  segment_by:
                    - status
                    - customer_segment
                  filter_by:
                    - status
                    - region
                  default_segment: customer_segment
                  default_filter:
                    status: completed
models:
  - name: orders
    columns:
      - name: amount
        meta:
          metrics:
            total_revenue:
              type: sum
              spotlight:
                segment_by:
                  - status
                  - customer_segment
                filter_by:
                  - status
                  - region
                default_segment: customer_segment
                default_filter:
                  status: completed
type: model
name: orders

dimensions:
  - name: amount

metrics:
  total_revenue:
    type: sum
    sql: ${TABLE}.amount
    spotlight:
      segment_by:
        - status
        - customer_segment
      filter_by:
        - status
        - region
      default_segment: customer_segment
      default_filter:
        status: completed

Now when someone opens the total_revenue metric in the Metrics Explorer, it's segmented by customer_segment and filtered to completed orders right away.

default_filter uses the same syntax as metric filters, so you can express:

default_filter:
  status: completed                 # is
default_filter:
  status: [completed, shipped]      # is one of
default_filter:
  status: "!cancelled"              # is not
  • Defaults are just a starting point: users can change or remove them while exploring, and their choices always take precedence. The defaults re-apply the next time the metric is opened.
  • default_segment must be a segmentable dimension (string or boolean) and, if you've set a segment_by allowlist, must be one of those dimensions.
  • default_filter accepts a single dimension and, if you've set a filter_by allowlist, that dimension must be in it. Only the is and is not operators are supported.

How it works

  • Dimension-level (boolean, default true): Controls whether a dimension appears in dropdowns for all metrics in that model.
  • Metric-level (array of dimension names): Creates an allowlist of dimensions for that specific metric.
  • Metric-level allowlists override dimension-level settings: If a dimension has filter_by: false but a metric includes it in its filter_by array, it will still be available for that metric.
  • Defaults pre-select, allowlists restrict: default_segment and default_filter choose the starting view, while segment_by and filter_by control what users can switch to.

Use cases

  • Hide internal/technical dimensions that aren't useful for analysis.
  • Curate the exploration experience per metric (e.g., revenue metrics only filterable by business dimensions).
  • Land users on the most useful view by default (e.g., revenue is always segmented by region, active users are always filtered to status: active).
  • Reduce clutter in models with many dimensions.

Configuring default time settings in .yml

We recommend setting up default time fields to make it easier for your business users and save them time.

To pre-select a time field in the explore view, simply define the default settings in your Qyra .yml files.

Set a table-level default time dimension

  1. Create or modify your table configuration in the .yml file. For example, to set a default time dimension on the events table:
models:
  - name: events
    columns:
      - name: event_date
        description: "Event date"
        config:
          meta:
            dimension:
              label: "Event date"
              type: date
              time_intervals:
                - DAY
      - name: event
        description: "Event"
        config:
          meta:
            dimension:
              type: string
            metrics:
              count:
                type: count
models:
  - name: events
    columns:
      - name: event_date
        description: "Event date"
        meta:
          dimension:
            label: "Event date"
            type: date
            time_intervals:
              - DAY
      - name: event
        description: "Event"
        meta:
          dimension:
            type: string
          metrics:
            count:
              type: count
type: model
name: events

dimensions:
  - name: event_date
    description: "Event date"
    label: "Event date"
    type: date
    time_intervals:
      - DAY
  - name: event
    description: "Event"
    type: string

metrics:
  count:
    type: count
    sql: ${TABLE}.event
  1. Add the default time dimension at the table level:
models:
  - name: events
    config:
      meta:
        default_time_dimension:
          field: event_date
          interval: DAY
    columns:
      # ... your column definitions here
models:
  - name: events
    meta:
      default_time_dimension:
        field: event_date
        interval: DAY
    columns:
      # ... your column definitions here
type: model
name: events

default_time_dimension:
  field: event_date
  interval: DAY

dimensions:
  # ... your dimension definitions here

  1. Compile your project

  2. Navigate to the metrics catalog

  3. Open any metrics from the events table

  4. All metrics with that default time set will be plotted against the event date with day granularity in the last 30 days

Set a metric-level default time dimension

This will override the time dimension defined on the table level.

  1. Modify your existing table configuration to add a metric-level default time dimension:
models:
  - name: events
    config:
      meta:
        default_time_dimension:
          field: event_date
          interval: DAY
    columns:
      - name: event
        description: "Event"
        config:
          meta:
            metrics:
              count:
                type: count
                # This will override the table level default time dimension
                default_time_dimension:
                  field: event_date
                  interval: MONTH
models:
  - name: events
    meta:
      default_time_dimension:
        field: event_date
        interval: DAY
    columns:
      - name: event
        description: "Event"
        meta:
          metrics:
            count:
              type: count
              # This will override the table level default time dimension
              default_time_dimension:
                field: event_date
                interval: MONTH
type: model
name: events

default_time_dimension:
  field: event_date
  interval: DAY

dimensions:
  - name: event
    description: "Event"

metrics:
  count:
    type: count
    sql: ${TABLE}.event
    # This will override the table level default time dimension
    default_time_dimension:
      field: event_date
      interval: MONTH

  1. Compile your project

  2. Navigate to the metrics catalog

  3. Explore the Events' count metric

  4. The metric will be plotted against the event date with month granularity, instead of the default day granularity applied to the table

FAQs

a. What time intervals are supported?

Currently, we only support: DAY, WEEK, MONTH, YEAR

b. What pre-filled filters are applied?

  • Time grain Year -> past 3 years

  • Time grain Month -> past 12 months

  • Time grain Week -> past 12 weeks

  • Time grain Day -> past 30 days

So if one of your business users explores a metric with a default time grain of DAY, metrics will be shown for the past 30 days with granularity of days with the default time dimension prefilled.

c. Can I pull through other metadata from my .yml files?

Not yet, but soon you'll be able to manage metadata directly in the UI and sync it back to dbt.

d. Which other metrics can I compare my selected metric by?

Currently, the "Compare to another metric" dropdown shows metrics from the same table as your selected metric that meet the following criteria:

  1. Metrics with defaults in .yml: Metrics with a default time dimension specified in the .yml file will appear.

  2. Metrics with a single time dimension: Metrics from tables with only one time dimension will appear as it's assumed to be the most relevant.

Cross-table metric comparison (including joined tables) is not yet supported. See GitHub issue #21003 for updates.

e. How can I be sure that my yml changes are correct?

If you use VSCode, you can use our Qyra schema validation to check your yml files are correct.

  1. Install this YAML extension for VSCode: https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml

  2. Open your user settings in JSON format and add the following:

"[yaml]": {
  "editor.defaultFormatter": "redhat.vscode-yaml"
},
"yaml.schemas": {
  "https://raw.githubusercontent.com/quanvio/qyra/refs/heads/main/packages/common/src/schemas/json/qyra-dbt-2.0.json": [
    "*.yml",
    "/**/models/**/*.yml",
    "/**/models/**/*.yaml",
    "!qyra.config.yml",
    "!dbt_project.yml"
  ],
  "https://raw.githubusercontent.com/quanvio/qyra/refs/heads/main/packages/common/src/schemas/json/qyra-project-config-1.0.json": [
    "qyra.config.yml"
  ]
}

This will add schema validation to your model yml files and your qyra.config.yml file.

  1. Reload VSCode

  2. You'll see a red squiggly line under any errors in your yml files as well as suggestions for how to fix them and what is allowed.

A YAML file in VS Code with a red squiggle under an invalid key and a tooltip listing the allowed values

Roles and permissions

ActionProject AdminProject DeveloperProject EditorProject Interactive ViewerProject Viewer
Browse the 'Metrics catalog'
Add/edit /delete 'Categories'
Open the 'Metrics Explorer'

Metrics catalog

Browse and explore your metrics in the catalog, and map how they relate with Saved Trees

Saved Trees

Build shareable diagrams that show how your metrics relate to each other

On this page

Browsing the catalogExploring a metricCurating Metrics Catalog for your business usersConfiguring global visibility of metricsAssigning categories to metricsAssigning owners to metricsSet an owner at the metric levelSet a default owner at the model levelControlling filtering and segmentation optionsHide a dimension from all metricsAllowlist specific dimensions for a metricSet a default segment and filter for a metricHow it worksUse casesConfiguring default time settings in .ymlSet a table-level default time dimensionSet a metric-level default time dimensionFAQsRoles and permissions