What is qyra.config.yml?

The qyra.config.yml file is an optional configuration file that allows you to define project-wide settings for your Qyra project. Think of it as a way to customize and enhance your Qyra experience beyond the basic setup.

Do I need this file?

You don't need qyra.config.yml to get started with Qyra! This file is for users who want to:

• Organize metrics in the Metrics Catalog with custom categories and visibility settings
• Create parameters that users can change to modify data across multiple charts and dashboards

If you're just getting started with Qyra, you can skip this file and come back to it later when you want these advanced features.

Getting started

Before creating a qyra.config.yml file, make sure you have:

1. ✅ A working Qyra project (completed the getting started guide)
2. ✅ A local dbt project (not connected to dbt Cloud)
3. ✅ The Qyra CLI installed and configured

# Navigate to your dbt project directory
cd /path/to/your/dbt/project

# Create the config file
touch qyra.config.yml

# Basic qyra.config.yml example
spotlight:
  default_visibility: "show"
  categories:
    finance:
      label: "Finance"
      color: "green"
    marketing:
      label: "Marketing" 
      color: "blue"

qyra deploy

Configuration options

The qyra.config.yml file supports the following top-level configuration options:

# Configuration for project-wide spotlight settings
spotlight:
  # ...

# Configuration for project-wide parameters
parameters:
  # ...

# Configuration for project-wide defaults
defaults:
  # ...

# Configuration for custom date granularities
custom_granularities:
  # ...

# Configuration for table groups in the sidebar
table_groups:
  # ...

Metrics Catalog configuration

The spotlight section allows you to configure project-wide Metrics Catalog settings. spotlight is the YAML namespace that covers everything about how your metrics show up across the Metrics experience — here you set the project-wide defaults, and you can override them per model or metric in your model .yml files. This section is required in the qyra.config.yml file.

spotlight:
  default_visibility: "show"
  categories:
    finance:
      label: "Finance"
      color: "green"
    user_engagement:
      label: "User Engagement"
      color: "blue"

Each category in the categories object requires the following properties:

Parameters configuration

The parameters section defines project-wide parameters that can be referenced across your Qyra project. Project-level parameters use the same property schema as model-level parameters.

parameters:
  region:
    label: "Region"
    description: "Filter data by region"
    options:
      - "EMEA"
      - "AMER"
      - "APAC"
    default: ["EMEA", "AMER"]
    multiple: true

Reference a project-level parameter in SQL with ${qyra.parameters.parameter_name} (or the shorter ${ld.parameters.parameter_name}).

See the Parameters reference for the full property schema, and the Parameters guide for where and how to use parameters across your project.

Reserved parameter names

A small set of parameter names — currently date_zoom — are reserved by Qyra and resolve automatically from the query context, so you don't declare them in qyra.config.yml. Defining a user parameter with a reserved name shadows the reserved one. See Reserved parameters for the full list and usage.

Defaults configuration

The defaults section allows you to set project-wide default settings that apply across all explores and dimensions. These defaults can be overridden at the explore or dimension level.

defaults:
  case_sensitive: false
  column_totals: false
  pre_aggregate_execution_fallback: false
  additional_time_intervals:
    date: ['fiscal_quarter']
    timestamp: ['HOUR']
  granularity_labels:
    week: "Week starting Monday"

Disabling column totals by default

Every time you run a query in the explorer, Qyra runs an additional warehouse query to calculate column totals for the results table footer. For cost-conscious users, setting column_totals: false skips this extra query by default, which can reduce warehouse spend on busy projects.

defaults:
  column_totals: false

This is a default, not a kill switch — charts that explicitly enable "Show column totals" still calculate totals as expected. You can also toggle this default via the API:

PUT /api/v2/projects/{projectUuid}/defaults
{ "column_totals": false }

Pre-aggregate execution fallback

When a query matches a pre-aggregate but the pre-aggregate execution itself fails — for example, an unreadable materialization file, a DuckDB error, or a missing external table — Qyra retries the query against the source warehouse by default. This keeps dashboards available when a materialization breaks.

Set pre_aggregate_execution_fallback: false to disable that retry. The query returns an error instead of silently running on the warehouse, so a broken pre-aggregate surfaces immediately rather than masking as warehouse latency and cost.

defaults:
  pre_aggregate_execution_fallback: false

You can also toggle this default via the API:

PUT /api/v2/projects/{projectUuid}/defaults
{ "pre_aggregate_execution_fallback": false }

This setting only covers execution-time failures on a matched query. Queries that don't match any pre-aggregate — including cases where the pre-aggregate can't be resolved, or when a sql_filter or non-field reference makes the query ineligible — still run against the warehouse.

Case sensitivity hierarchy

The case_sensitive setting follows a hierarchy where more specific settings override broader ones:

1. Dimension-level (highest priority) - Set on individual dimensions
2. Explore/table-level - Set on the explore or table
3. Project-level - Set in qyra.config.yml defaults
4. Default behavior - Case sensitive (true) if nothing is specified

This allows you to set organization-wide defaults while maintaining the flexibility to override them for specific explores or dimensions as needed.

Example: Set case insensitivity as the project default, but override for a specific table:

# qyra.config.yml
defaults:
  case_sensitive: false  # Project-wide default

# In your model yml file - override for a specific table
models:
  - name: case_sensitive_table
    meta:
      case_sensitive: true  # Override: this table uses case sensitive filters

Additional time intervals

By default, Qyra exposes a fixed set of time intervals on date and timestamp dimensions:

• Date dimensions: DAY, WEEK, MONTH, QUARTER, YEAR
• Timestamp dimensions: RAW, DAY, WEEK, MONTH, QUARTER, YEAR

The additional_time_intervals setting lets you append extra intervals (standard granularities or custom granularity keys) to those built-in defaults project-wide, so you don't have to repeat time_intervals on every column.

defaults:
  additional_time_intervals:
    date:
      - fiscal_quarter      # custom_granularities key
    timestamp:
      - HOUR                # standard granularity
      - fiscal_quarter      # custom_granularities key

How it works:

• Additive only — the built-in defaults are always included; values listed here are appended after them and de-duplicated.
• Fallback-only — if a dimension declares its own time_intervals in its model .yml, the per-column list wins and additional_time_intervals is ignored for that dimension.
• Validation — values are validated once at project compile time. Standard granularities are accepted case-insensitively. Sub-day grains (RAW, MILLISECOND, SECOND, MINUTE, HOUR) are not valid under date and are dropped with a warning. Unknown names that don't match a standard grain or a defined custom_granularities key are also dropped with a warning.

Example: Add HOUR to every timestamp dimension and a fiscal_quarter custom granularity to both:

# qyra.config.yml
custom_granularities:
  fiscal_quarter:
    label: "Fiscal Quarter"
    sql: "DATE_TRUNC('quarter', ${COLUMN} + INTERVAL '1 month')"
    type: date

defaults:
  additional_time_intervals:
    date: ['fiscal_quarter']
    timestamp: ['HOUR', 'fiscal_quarter']

A column that overrides this default still works as before:

# In your model yml file - this column ignores the project default
columns:
  - name: created_at
    meta:
      dimension:
        type: timestamp
        time_intervals: ['DAY', 'WEEK']  # explicit list wins

Granularity label overrides

The granularity_labels setting lets you replace how standard granularities are displayed across the project. This is useful when your business uses a non-default convention — for example, a week that starts on Monday — and you want the UI to reflect that everywhere a granularity is shown.

defaults:
  granularity_labels:
    week: "Week starting Monday"
    month: "Calendar month"

Supported keys are the standard Qyra TimeFrames values, written in lowercase or uppercase, for example week, month, or hour. Unknown keys are ignored with a warning at project compile time.

Where the override is applied:

• Explorer dimension labels — the configured string replaces the built-in grain segment of the auto-generated dimension label. For example, with week: "Week starting Monday", the Order date Week dimension becomes Order date Week starting Monday.
• Explorer sidebar tree — the same relabeling is shown in the dimension tree.
• Date zoom dropdown — the configured string is used verbatim as the option label (e.g. Week starting Monday instead of Week).
• Chart axis labels — axis labels that reflect the active grain pick up the override automatically.

How it works:

• Full replacement — the configured string replaces the grain label outright. Provide the complete label you want users to see (e.g. "Week starting Monday"), not just a suffix.
• Standard granularities only — to relabel non-standard time periods (e.g. fiscal quarters), define a custom granularity instead.
• Project-wide — applies to every date and timestamp dimension in the project; there is no per-dimension override.

Example: Make every weekly grain advertise its week-start convention:

# qyra.config.yml
defaults:
  granularity_labels:
    week: "Week starting Monday"

With this config, a created_at timestamp dimension exposes Created at Week starting Monday in the Explorer, sidebar tree, and chart axis labels, and Week starting Monday appears in the date zoom dropdown.

Custom granularities configuration

The custom_granularities section allows you to define reusable custom time granularities that appear in the date zoom dropdown alongside standard options (Day, Week, Month, Quarter, Year). This is useful for business-specific time periods like fiscal quarters, Monday-to-Sunday weeks, or other custom date groupings.

custom_granularities:
  fiscal_quarter:
    label: "Fiscal Quarter"
    sql: "DATE_TRUNC('quarter', ${COLUMN} + INTERVAL '1 month')"
    type: date
  week_monday:
    label: "Week (Mon-Sun)"
    sql: "DATE_TRUNC('week', ${COLUMN})"
    type: date
  fiscal_year:
    label: "Fiscal Year"
    sql: "EXTRACT(YEAR FROM ${COLUMN} + INTERVAL '1 month')"
    type: string

Each custom granularity is defined as a key-value pair where the key is the granularity name (must be alphanumeric with underscores) and the value is an object with the following properties:

How custom granularities work

Custom granularities are defined at the project level in qyra.config.yml and become available on date dimensions through the time_intervals property. The ${COLUMN} template in the SQL expression is automatically replaced with the actual column SQL when generating queries.

Example: Define a fiscal quarter granularity and use it on a dimension:

# qyra.config.yml
custom_granularities:
  fiscal_quarter:
    label: "Fiscal Quarter"
    sql: "DATE_TRUNC('quarter', ${COLUMN} + INTERVAL '1 month')"
    type: date

# In your model yml file
columns:
  - name: order_date
    meta:
      dimension:
        type: date
        time_intervals: ['DAY', 'WEEK', 'MONTH', 'fiscal_quarter', 'YEAR']

The custom granularity fiscal_quarter will now appear in the date zoom dropdown for order_date, alongside the standard intervals.

See the date zoom guide for how to configure which granularities appear in the dropdown and how to set defaults.

Use cases

• Fiscal calendars: Define fiscal quarters or years that don't align with calendar quarters
• Week start customization: Create weeks that start on Monday or any other day
• Custom periods: Define business-specific time periods like "retail weeks" or "academic terms"

See the dimensions reference for configuring time intervals on dimensions, including how to reference custom granularities.

Table groups configuration

The table_groups section defines display labels and descriptions for the group keys referenced by your models in their meta.groups array. These groups are used to render nested table groups in the Explore sidebar (up to 3 levels of nesting).

table_groups:
  mobile:
    label: 'Mobile App'
    description: 'Tables related to the mobile app'
  engagement:
    label: 'Engagement'
  finance:
    label: 'Finance'
    description: 'Revenue, billing, and accounting tables'

Each entry in table_groups is keyed by the group identifier you reference from a model's meta.groups, and supports the following properties:

Group keys must match the pattern ^[a-zA-Z0-9_-]+$. If a key referenced from a model's meta.groups is not defined in table_groups, the key itself is used as the label.

To assign a table to a group, use the groups property on the model's meta:

models:
  - name: users
    meta:
      groups: ['mobile', 'engagement']