Sync with dbt

The Data Contract CLI integrates with dbt in multiple ways:

Sync: Merge the schema and tests of one or multiple data contracts into an existing dbt project (datacontract dbt sync)
Test: Run the CLI-generated dbt tests, optionally scoped to a contract ( datacontract dbt test)
Export: Do a one-time export from a data contract into a dbt model schema, a sources YAML, or a staging SQL file (datacontract export)
Import: Create a data contract from a dbt manifest file (datacontract import dbt)

`datacontract dbt sync`

dbt sync reads one or more ODCS data contracts and applies the specified schema and tests to an existing dbt project. It updates the model properties files (YAML) in-place and adds singular SQL tests if needed.

# Auto-discover every *.odcs.yaml in a dbt project, update models and test
datacontract dbt sync

# Delete columns, tests etc. that are not specified in the contract
datacontract dbt sync --prune

# Specify contract and dbt project directory
datacontract dbt sync orders.odcs.yaml --project-dir ./warehouse

# Several contracts, or a glob
datacontract dbt sync orders.odcs.yaml customers.odcs.yaml
datacontract dbt sync "contracts/*.odcs.yaml"

# Run the generated tests (or as separate command: datacontract dbt test)
datacontract dbt sync --run-tests

# Generate, run, and publish results to an Entropy Data instance 
datacontract dbt sync orders.odcs.yaml --run-tests --publish https://api.entropy-data.com/api/test-results

A list of all options can be found at the dbt command reference.

What is synced?

All CLI-managed content in the dbt project gets marked with custom meta tags. By default, schemas or tests that are neither specified in the contract nor generated by the CLI are kept, unless --prune is specified.

ODCS source	dbt target
`schema` / `property` description	model / column `description`
`property.logicalType` / `physicalType`	column `data_type`, mapped to the server dialect
`property`	column entry
`schema.tags` / `property.tags`	`config.tags`
`property.required`, single `primaryKey`, `property.quality.mustBe`	native dbt tests (`not_null`, `unique`, `accepted_values`)
composite `primaryKey`, `logicalTypeOptions` bounds (`minLength`, `maxLength`, `pattern`, `minimum`, …), `quality` with a `query` + bound, `schema.quality` `rowCount`	singular SQL tests at `<testsRoot>/datacontract_cli/`

:::tip See the dbt command reference for a worked example and all options. :::

Versioned models

dbt sync works natively with dbt model versions. To specify multiple versions using data contracts, create one contract file per version. Their filename must include an integer version number with a preceding v, e.g. orders-v01.odcs.yaml.

If dbt sync is fed with a subset of the versioned contracts, the other versions remain unchanged.

`datacontract dbt test`

Runs the contract-managed tests that dbt sync generated, reports the results, and optionally publishes them. Like dbt sync, the command accepts multiple contracts.

# Every contract in the current project
datacontract dbt test

# A single contract and dbt target in a specified project
datacontract dbt test orders.odcs.yaml --project-dir ./warehouse --target dev

See the dbt command reference.

dbt exporters

Convert a contract into dbt artifacts:

dbt-models — dbt model schema YAML. If a server is selected via --server, the dbt data_types match the expected data types of that server; otherwise it defaults to snowflake.
dbt-sources — dbt sources YAML.
dbt-staging-sql — a dbt staging SQL file.

datacontract export dbt-models datacontract.yaml --server snowflake

dbt importer

Generate a contract from a dbt project’s manifest.json:

# Import specific tables from a dbt manifest
datacontract import dbt --source manifest.json --model orders --model line_items

# Import all tables
datacontract import dbt --source manifest.json

This site is open source. Improve this page.