> ## Documentation Index
> Fetch the complete documentation index at: https://lightdash-mintlify-cccf65ca.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# lightdash.config.yml reference

> The lightdash.config.yml file allows you to configure project-wide settings for your Lightdash project, including Metrics Catalog, parameters, and defaults.

## What is lightdash.config.yml?

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

<Warning>
  `lightdash.config.yml` is **not supported** when your project is connected directly to dbt Cloud.

  This file only works with projects that use direct git connections or deploy with the CLI (either from local dbt projects and/or continuous deployment).
</Warning>

## Do I need this file?

You **don't need** `lightdash.config.yml` to get started with Lightdash! This file is for users who want to:

* **Organize metrics in the [Metrics Catalog](/guides/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 Lightdash, you can skip this file and come back to it later when you want these advanced features.

## Getting started

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

1. ✅ A working Lightdash project (completed the [getting started guide](/get-started/setup-lightdash/intro))
2. ✅ A local dbt project (not connected to dbt Cloud)
3. ✅ The [Lightdash CLI](/get-started/setup-lightdash/get-project-lightdash-ready#step-1-install-the-lightdash-cli-tool) installed and configured

<Steps>
  <Step title="Create the file">
    Create a new file called `lightdash.config.yml` in the **root directory of your dbt project** - this is the same folder where your `dbt_project.yml` file is located.

    ```bash theme={null}
    # Navigate to your dbt project directory
    cd /path/to/your/dbt/project

    # Create the config file
    touch lightdash.config.yml
    ```
  </Step>

  <Step title="Add your first configuration">
    Start with a simple configuration. Here's a basic example that sets up Metrics Catalog categories:

    ```yaml theme={null}
    # Basic lightdash.config.yml example
    spotlight:
      default_visibility: "show"
      categories:
        finance:
          label: "Finance"
          color: "green"
        marketing:
          label: "Marketing" 
          color: "blue"
    ```
  </Step>

  <Step title="Deploy your changes">
    After creating or updating your `lightdash.config.yml` file, deploy the changes to your Lightdash project:

    ```bash theme={null}
    lightdash deploy
    ```

    That's it! Your configuration is now active in your Lightdash project.
  </Step>
</Steps>

## Configuration options

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

```yaml theme={null}
# 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](/guides/metrics-catalog#the-spotlight-config) — 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 lightdash.config.yml file.

```yaml theme={null}
spotlight:
  default_visibility: "show"
  categories:
    finance:
      label: "Finance"
      color: "green"
    user_engagement:
      label: "User Engagement"
      color: "blue"
```

| Property             | Required | Value       | Description                                                                                       |
| :------------------- | :------- | :---------- | :------------------------------------------------------------------------------------------------ |
| `default_visibility` | No       | string enum | The default visibility of Metrics Catalog metrics. Defaults to `show`, can also be set to `hide`. |
| `categories`         | No       | Object      | Define the categories that can be used in the Metrics Catalog on your model yml files.            |

Each category in the `categories` object requires the following properties:

| Property | Required | Value       | Description                                                                                                                                                         |
| :------- | :------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `label`  | Yes      | string      | The label of the category as it will be displayed in the Metrics Catalog.                                                                                           |
| `color`  | No       | string enum | The color of the category. If not provided, it will be set to gray. Allowed values: `gray`, `violet`, `red`, `orange`, `green`, `blue`, `indigo`, `pink`, `yellow`. |

## Parameters configuration

The `parameters` section allows you to define project-wide parameters that can be referenced in various parts of your Lightdash project.

```yaml theme={null}
parameters:
  region:
    label: "Region"
    description: "Filter data by region"
    options:
      - "EMEA"
      - "AMER"
      - "APAC"
    default: ["EMEA", "AMER"]
    multiple: true
  min_revenue:
    label: "Minimum Revenue"
    description: "Filter for minimum revenue threshold"
    type: "number"
    options:
      - 1000
      - 5000
      - 10000
    default: 5000
  custom_date_range_start:
    label: "Custom date range - start"
    description: "The start date for a custom date range filter"
    type: "date"
custom_date_range_end:
    label: "Custom date range - end"
    description: "The end date for a custom date range filter"
    type: "date"
department:
    label: "Department"
    description: "Filter data by department"
    options_from_dimension:
      model: "employees"
      dimension: "department"
```

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

| Property                 | Required | Value                                       | Description                                                                                                |
| :----------------------- | :------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------- |
| `label`                  | Yes      | string                                      | A user-friendly label for the parameter as it will be displayed in the UI.                                 |
| `description`            | No       | string                                      | A description of the parameter.                                                                            |
| `type`                   | No       | "string", "number", or "date"               | The type of the parameter. Defaults to "string" if not specified.                                          |
| `options`                | No       | Array of strings or numbers                 | A list of possible values for the parameter.                                                               |
| `default`                | No       | string, number, or Array of strings/numbers | The default value(s) for the parameter.                                                                    |
| `multiple`               | No       | boolean                                     | Whether the parameter input will be a multi-select.                                                        |
| `allow_custom_values`    | No       | boolean                                     | Whether users can input custom values beyond predefined options.                                           |
| `options_from_dimension` | No       | Object                                      | Get parameter options from a dimension in a model. Requires `model` and `dimension` arguments (see below). |

If using `options_from_dimension`, the object requires the following properties:

| Property    | Required | Value  | Description                         |
| :---------- | :------- | :----- | :---------------------------------- |
| `model`     | Yes      | string | The model containing the dimension. |
| `dimension` | Yes      | string | The dimension to get options from.  |

### Using parameters in your project

Parameters defined in the `lightdash.config.yml` file can be referenced in various parts of your Lightdash project using the syntax `${lightdash.parameters.parameter_name}` or the shorter alias `${ld.parameters.parameter_name}`.

For example, to reference a parameter named `region`:

```yaml theme={null}
${lightdash.parameters.region}
```

Or using the shorter alias:

```yaml theme={null}
${ld.parameters.region}
```

See the [Parameters guide](/guides/developer/using-parameters) for more information on how to use parameters.

### Reserved parameter names

A small set of parameter names are **reserved** by Lightdash and resolve automatically from the query context — you don't need to declare them in `lightdash.config.yml` or in a model.

| Reserved name | Resolves to                                                                                                                                              |
| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `date_zoom`   | The currently selected [date zoom](/guides/date-zoom) granularity, lowercased (e.g. `day`, `week`, `month`). Empty string when no date zoom is selected. |

If you define a user parameter with one of these names, your user parameter shadows the reserved one. See [Reserved parameters](/guides/developer/using-parameters#reserved-parameters) for usage details.

## 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.

```yaml theme={null}
defaults:
  case_sensitive: false
  column_totals: false
```

| Property         | Required | Value   | Description                                                                                                                                                                                                                                                           |
| :--------------- | :------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `case_sensitive` | No       | boolean | Default case sensitivity for string filters across the project. When `false`, all string filters will be case insensitive by default. Defaults to `true`.                                                                                                             |
| `column_totals`  | No       | boolean | Default behavior for column totals in the explorer results table. When `false`, Lightdash skips the extra warehouse query that calculates column totals for new queries. Charts that explicitly enable "Show column totals" still calculate them. Defaults to `true`. |

### Disabling column totals by default

Every time you run a query in the explorer, Lightdash 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.

```yaml theme={null}
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:

```http theme={null}
PUT /api/v2/projects/{projectUuid}/defaults
{ "column_totals": false }
```

### 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 `lightdash.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:

```yaml theme={null}
# lightdash.config.yml
defaults:
  case_sensitive: false  # Project-wide default
```

```yaml theme={null}
# 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
```

<Info>
  See [Tables reference](/references/tables#case-sensitive) for explore-level configuration and [Dimensions reference](/references/dimensions#case-sensitive) for dimension-level configuration.
</Info>

## Custom granularities configuration

<Info>
  **Availability:** Custom granularities are a [Beta](/references/workspace/feature-maturity-levels) feature.
</Info>

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.

```yaml theme={null}
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:

| Property | Required | Value                            | Description                                                                                                                                                                                                         |
| :------- | :------- | :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `label`  | Yes      | string                           | A user-friendly label for the granularity as it will be displayed in the date zoom dropdown.                                                                                                                        |
| `sql`    | Yes      | string                           | SQL expression that defines how to truncate/transform the date. Use `${COLUMN}` as a placeholder for the actual date column - it will be replaced with the column's SQL at runtime.                                 |
| `type`   | No       | `date`, `timestamp`, or `string` | The output type of the SQL expression. Use `date` for truncated dates, `timestamp` for truncated timestamps, or `string` for formatted text output (e.g., fiscal year labels). Defaults to `date` if not specified. |

### How custom granularities work

Custom granularities are defined at the project level in `lightdash.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:

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

```yaml theme={null}
# 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.

<Info>
  Custom granularities inherit `requiredAttributes` and `anyAttributes` from the parent dimension, so access controls are automatically applied.
</Info>

<Info>
  See the [Date zoom guide](/guides/date-zoom) for information on configuring which granularities appear in the dropdown and setting defaults.
</Info>

### 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"

<Info>
  See [Dimensions reference](/references/dimensions#time-intervals) for more information on configuring time intervals on dimensions, including how to reference custom granularities.
</Info>

## 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).

```yaml theme={null}
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:

| Property      | Required | Value  | Description                                              |
| :------------ | :------- | :----- | :------------------------------------------------------- |
| `label`       | Yes      | string | Display label shown in the sidebar for this table group. |
| `description` | No       | string | Optional description of this table group.                |

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.

<Info>
  When you run `lightdash deploy` or `lightdash preview`, the CLI only syncs table groups if the `table_groups` key is present in your config. To clear all previously deployed table groups, set `table_groups: {}` explicitly — omitting the key leaves the server-side groups unchanged.
</Info>

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

```yaml theme={null}
models:
  - name: users
    meta:
      groups: ['mobile', 'engagement']
```

<Info>
  See [Tables reference](/references/tables#groups) for more information on grouping tables in the sidebar.
</Info>