> For the complete documentation index, see [llms.txt](https://docs.dexlabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dexlabs.io/lakehouse-platform/develop-with-dex/project-and-environment-variables.md).

# Project and Environment Variables

Project and Environment variables allow you to parameterize logic in your dex project so it can behave differently depending on where or how it’s running. They’re most commonly used to avoid hardcoded values, toggle configurations between environments, and securely inject credentials or tokens using secrets.

These variables follow a familiar pattern used in templated analytics workflows and are evaluated at **compile time**, making them accessible inside models, macros, snapshots, seeds, and more.

{% hint style="warning" %}
Don’t confuse transformation variables with secrets stored in dex's [S](/lakehouse-platform/variables-and-secrets.md)[ecrets Manager](/lakehouse-platform/variables-and-secrets.md).\
Variables are used to control logic at compile time (like schema names or flags), while secrets are encrypted values (like passwords or tokens) used to securely configure external connections.
{% endhint %}

### Where Variables Come From

Variables in dex are defined in two ways:

* **Project variables**: Defined in the `dbt_project.yml` file. These are global to the entire dex project and apply across all environments.
* **Environment variables**: Defined in the dex UI, scoped to a specific environment (e.g., `dev`, `staging`, `production`). These override project-level defaults and are evaluated first when resolving variables.

You can also mark any environment variable as a **secret**, ensuring it is encrypted and hidden after being saved.

### How to Define Project Variables

Inside your project, you can define variables in `dbt_project.yml` like this:

```yaml
vars:
  start_date: '2023-01-01'
  schema_suffix: '_dev'
```

These variables are accessible anywhere in your models using the `var()` function.

### Using Variables in Your Models

You can access both project and environment variables using the `var()` Jinja function:

```sql
select *
from raw.customers
where created_at >= '{{ var("start_date") }}'
```

You can also use them for logic in macros, seeds, snapshots, and materialization configs:

```sql
{% if var('schema_suffix') == '_prod' %}
  -- production logic
{% else %}
  -- dev logic
{% endif %}

```

Variables are **evaluated at compile time**, meaning they are rendered before your model or macro runs in the warehouse.

### Precedence

When a variable with the same name is defined in both the project and the environment:

* **Environment variable wins** — it will override the project-level default during execution.

This makes it easy to test safely in dev while preserving production configurations in place.

### Example Use Case

Let’s say you want to limit row output in development but run full datasets in production:

* Project-level `dbt_project.yml`:

```yaml
vars:
  row_limit: null
```

* Environment override (dev):

```makefile
Name: ROW_LIMIT  
Value: 100  
Scope: Environment  
Environment: dev
```

* Model logic:

```sql
select *
from {{ ref('orders') }}
{% if var('row_limit') %}
limit {{ var('row_limit') }}
{% endif %}
```

In dev, this model limits rows to 100. In production, it runs without a limit.

### Best Practices

* Use `var('...')` to make behavior configurable across projects or stages
* Always give defaults in `dbt_project.yml` so local runs don’t break
* Use uppercase names with underscores for consistency (`SCHEMA_NAME`, `LIMIT_ROWS`)
* Use secrets for anything sensitive (API tokens, passwords)
* Document variable usage in your project README or `.yml` files


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.dexlabs.io/lakehouse-platform/develop-with-dex/project-and-environment-variables.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.