> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.omni.co/feedback

```json
{
  "path": "/integrations/dbt/deferrals-constraints",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Using dbt constraints and deferrals

> Inherit primary keys, relationships, and column descriptions from dbt constraints, and use deferrals or dbt clone to test changes against production data.

Omni inherits metadata from your dbt project so your BI layer stays in sync with your transformation layer. Two dbt features do most of the work:

* **Constraints** let Omni automatically pick up primary keys, relationships, and column descriptions from dbt.
* **dbt clone** creates zero-copy clones of production objects in your dev schema, so Omni can resolve all table references without you having to rebuild everything.

## Common questions

<AccordionGroup>
  <Accordion title="Does dbt clone override local changes?">
    No. Cloning creates zero-copy clones of all production objects in your development schema. If you then run `dbt build` or `dbt run` on a specific model, dbt replaces that clone with the table or view built from your code. Omni picks up the new version automatically.
  </Accordion>

  <Accordion title="Can dbt constraints be used with views?">
    In many warehouses, constraints are applied to tables rather than views. If your dbt project outputs views, define constraints at the model level in dbt so Omni can still inherit that logic, even if the warehouse doesn't enforce them on the view.
  </Accordion>
</AccordionGroup>

## Requirements

* A configured [dbt integration](/integrations/dbt/setup)
* **For constraints** - Constraints defined in your dbt project (using `dbt-constraints` or native dbt constraints)
* **For deferrals** - A successful production job run in dbt Cloud

## dbt constraints

Omni automatically inherits the semantic logic you've defined in your dbt project to build a baseline model.

* **Relationship inheritance**: If you have primary keys and relationships defined in your dbt project, Omni can automatically create the corresponding relationships and primary keys in your Omni model. To enable this, turn on **Auto-generate primary keys and relationships from dbt constraints** in your dbt connection settings.
* **Description sync**: Column descriptions defined in your `schema.yml` files are brought into Omni automatically, providing immediate context in the UI.
* **Automated joins**: Omni maps join paths based on your dbt constraints. When a user combines fields from `Orders` and `Customers`, Omni joins them using the dbt-defined relationship.

<Tip>
  **Best practice**: Keep source-of-truth logic (like column descriptions and primary keys) in dbt, but manage Omni-specific metadata (like AI instructions or synonyms) directly in the Omni UI.
</Tip>

See [dbt's constraints reference](https://docs.getdbt.com/reference/resource-properties/constraints) for more on how constraints are defined in dbt.

## dbt deferrals

Omni doesn't natively support dbt deferrals. When you switch environments in Omni, it expects all models referenced in that environment to physically exist in the target schema. If you've only built a subset of models, Omni will report `Table not found` errors for anything that wasn't built.

There are two options to resolve this:

1. Perform a full `dbt run` with deferral disabled to build all the views in your developer schema.
2. **Recommended for large tables or partial builds**. Use `dbt clone`, which creates zero-copy clones of production objects in your dev schema so Omni can resolve all table references. Your typical dev workflow should be:

   1. Run `dbt clone` to populate your dev schema with production clones.
   2. Run `dbt build` on only the models you're actively changing.

   Omni will read from the cloned production versions for everything else, and automatically pick up any models you've rebuilt.

### dbt clone with dbt Cloud

<Note>
  Deferrals require at least one successful job run in the designated production requirement.
</Note>

1. In dbt Cloud, enable the **Defer to staging/production** option in your development environment settings. This designates your production job as the reference point.
2. Once enabled, run `dbt clone` from the dbt Cloud IDE.

### dbt clone with a local dbt installation

If you run dbt locally (for example, in VS Code with a local `profiles.yaml`), you need to download the artifacts from your most recent production run first, then pass them to `dbt clone` using the `--state` flag:

```bash theme={null}
dbt clone --state /path/to/production/artifacts
```

Production artifacts are typically available from your CI/CD pipeline, an S3 bucket, or your dbt Cloud job's artifact storage.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Table not found error after switching to dev environment">
    Omni expects every model referenced in an environment to physically exist in the target schema. If you've only built modified models without cloning the rest from production, Omni can't resolve the missing tables.

    Run `dbt clone` before switching environments in Omni to ensure all tables are present. If errors persist, confirm your database user has permission to read the production schema — see [dbt connection setup](/integrations/dbt/setup) for more information.
  </Accordion>
</AccordionGroup>

## Next steps

* [Connecting dbt to Omni](/integrations/dbt/setup) — Configure the dbt integration if you haven't already.
* [Working with dbt models](/integrations/dbt/models) — Author and edit dbt models from Omni.
* [Connection environments](/connect-data/dynamic-environments) — Set up dynamic environments for safe testing.