Skip to content

CLI Reference (dbterd)

Run dbterd --help or dbterd -h to see the basic guideline for CLI Reference

dbterd -h Usage: dbterd [OPTIONS] COMMAND [ARGS]...

Tools for producing diagram-as-code

Options:
--version Show the version and exit.
-h, --help Show this message and exit.

Commands:
debug Inspect the hidden magics
run Run the convert

dbterd run

Command to generate diagram-as-a-code file

Examples:

dbt docs generate
dbterd run [-t dbml or -t mermaid]
Usage: dbterd run [OPTIONS]

Run the convert

Options:
    -ad, --artifacts-dir TEXT     Specified the full path to dbt artifacts path
                                    which known as /target directory  [default:
                                    C:\Users\DAT\Documents\Sources\dbterd\target]
    -o, --output TEXT             Output the result file. Default to the same
                                    target dir  [default:
                                    C:\Users\DAT\Documents\Sources\dbterd\target]
    -s, --select TEXT             Selecttion criteria
    -ns, --exclude TEXT           Exclusion criteria
    -t, --target TEXT             Target to the diagram-as-code platform
                                    [default: dbml]
    -a, --algo TEXT               Specified algorithm in the way to detect
                                    diagram connectors  [default:
                                    test_relationship]
    -mv, --manifest-version TEXT  Specified dbt manifest.json version
    -cv, --catalog-version TEXT   Specified dbt catalog.json version
    -rt, --resource-type TEXT     Specified dbt resource type(seed, model,
                                    source, snapshot),default:model, use examples,
                                    -rt model -rt source
    --omit-columns                Flag to omit columns in diagram. Currently
                                    only mermaid is supported
    -h, --help                    Show this message and exit.

dbterd run --select (-s)

Selection criteria.

Select all dbt models if not specified, supports multiple options

Rules:

  • By name: model name starts with input string
  • By exact: exact model name, formed as exact:model.package.name
  • By schema: schema name starts with an input string, formed as schema:<your_schema_name>
  • By wildcard: model name matches to a wildcard pattern, formed as wildcard:<your_wildcard>
  • By exposure: exposure name, exact match

Examples:

dbterd run -s "model.package.partital_name"
dbterd run -s "exact:model.package.name"
dbterd run -s "schema:my_schema_name"
dbterd run -s "wildcard:*xyz"
dbterd run -s "exposure:my_exposure_name"

AND and OR logic

  • AND logic is applied to a single selection split by comma (,)
  • OR logic is applied to 2+ selection

Examples:

# All models belong to 'abc' schema AND also need to match the pattern of '*xyz.*'
dbterd run -s schema:abc,wildcard:*xyz.*
# All models belong to 'abc' schema, OR match to the pattern of '*xyz.*'
dbterd run -s schema:abc -s wildcard:*xyz.*

dbterd run --exclude (-ns)

Exclusion criteria. Rules are the same as Selection Criteria.

Do not exclude any dbt models if not specified, supports multiple options

Examples:

dbterd run -ns 'model.package_name.table'
dbterd run --exclude 'model.package_name.table'

dbterd run --artifacts-dir (-ad)

Configure the path to directory containing dbt artifact files.

It will take the the nested /target directory of --dbt-project-dir if not specified.

Default to the current directory's /target if both this option and --dbt-project-dir option are not specified

Examples:

dbterd run -ad "./target"
dbterd run --artifacts-dir "./target"

dbterd run --output (-o)

Configure the path to directory containing the output diagram file.

Default to ./target

Examples:

dbterd run -o "./target"
dbterd run --output "./target"

dbterd run --output-file-name (-ofn)

Configure the output file name

Default to output.{modulename} which is defined in the target module

Examples:

dbterd run -ofn "erd.dbml"
dbterd run --output-file-name "erd.dbml"

dbterd run --target (-t)

Default to dbml

Supported target, please visit Generate the Targets

Examples:

dbterd run -t dbml
dbterd run --target dbml

dbterd run --algo (-a)

Specified algorithm in the way to detect diagram connectors

Check the docs 📖

Supported ones:

  • test_relationship: Looking for all relationship tests to understand the ERs
  • semantic: Looking for all semantic models' entities (primary & foreign) to understand the ERs

In the advanced use case of test_relationship, the test name can be configurable by following syntax:

{algorithm_name}:(name:{contains_test_name}|c_from:{referencing_column_name}|c_to:{referenced_column_name})

In the above:

  • algorithm_name (Mandatory): test_relationship or semantic
  • contains_test_name: Configure the test name (detected with contains logic). Default to relationship
  • c_from: Configure the test metadata attribute (1) for the foreign key column name(s). If (1)'s value is multiple columns, it will concat them all with _and wording > NOTE: It always looking at the column_name attribute firstly
  • c_to: Configure the test metadata attribute (2) for the referenced column name(s). If (2)'s value is multiple columns, it will concat them all with _and wording. Default to field

For example, if you would use dbt-constraints package

The dbt-constraints package is using different name of test which is close to the constraint names, in this case, you would need to customize the input string here:

dbterd run \
--algo "test_relationship:(name:foreign_key|c_from:fk_column_name|c_to:pk_column_name)"

Examples:

dbterd run -a test_relationship
dbterd run -a semantic
dbterd run --algo test_relationship
dbterd run --algo "test_relationship:(name:foreign_key|c_from:fk_column_name|c_to:pk_column_name)"

dbterd run --omit-columns

Flag to omit columns in diagram. Currently only mermaid is supported

Default to False

Examples:

dbterd run --target mermaid --omit-columns

dbterd run --manifest-version (-mv)

Specified dbt manifest.json version

Auto detect if not specified

Examples:

dbterd run --manifest-version 7
dbterd run -mv 7

dbterd run --catalog-version (-cv)

Specified dbt catalog.json version

Auto detect if not specified

Examples:

dbterd run --catalog-version 7
dbterd run -cv 7

dbterd run --resource-type (-rt)

Specified dbt resource type(seed, model, source, snapshot).

Default to ["model"], supports multiple options

Examples:

dbterd run -rt model -rt source
dbterd run --resource-type model

dbterd run --dbt

Flag to indicate the Selection to follow dbt's one leveraging Programmatic Invocation

Default to False

Examples:

dbterd run -s +something --dbt
# select 'something' and the upstream
dbterd run -s something
# select starts with 'something'

dbterd run --dbt --dbt-auto-artifact

Flag to indicate force running dbt docs generate to the targeted project in order to produce the dbt artifact files.

This option have to be enabled together with --dbt option, and will override the value of --artifacts-dir to be using the /target dir of the value of --dbt-project-dir.

Default to False

Examples:

dbterd run -s +something --dbt --dbt-auto-artifacts

dbterd run --dbt-project-dir (-dpd)

Specified dbt project directory path

You should specified this option if your CWD is not the dbt project dir, and normally used with --dbt enabled. It will take the value of --artifacts-dir if not specified.

Default to the current directory if both this option and --artifacts-dir option are not specified

Examples:

dbterd run -s +something --dbt-project-dir /path/to/dbt/project --dbt
# select 'something' and the upstream of the dbt project located at /path/to/dbt/project
# the artifacts dir will probably be assumed as: /path/to/dbt/project/target

dbterd run --dbt-target (-dt)

Specified dbt target name

Probably used with --dbt enabled.

Default to the dbt's profile configuration

Examples:

dbterd run -s +something --dbt-project-dir /path/to/dbt/project --dbt --dbt-target prod
# select 'something' and the upstream of the dbt project located at /path/to/dbt/project using target name 'prod'
# the artifacts dir will probably be assumed as: /path/to/dbt/project/target

dbterd run --entity-name-format (-enf)

Decide how the table name is generated on the ERD.

By default, the table name is the dbt node name (resource_type.package_name.model_name).

Currently, it supports the following keys in the format:

  • resource.package.model (by default)
  • database.schema.table
  • Or any other partial forms e.g. schema.table, resource.model

Examples:

dbterd run --entity-name-format resource.package.model # by default
dbterd run --entity-name-format database.schema.table # with fqn of the physical tables
dbterd run --entity-name-format schema.table # with schema.table only
dbterd run --entity-name-format table # with table name only

dbterd run --omit-entity-name-quotes

Flag to omit the double quotes in the generated entity name. Currently only dbml is supported.

Default to False

Enabled it to allow dbdocs to recognize the schemas and display them as grouping:

  • With quotes:

dbdocs-enf-with-quotes

  • Without quotes:

dbdocs-enf-without-quotes

⚠️ As of 2024 June: DBML doesn't support nested schema in the entity name which means 'database.schema.table' won't be allowed, but 'schema.table' does!

Examples:

dbterd run --entity-name-format resource.package.model --omit-entity-name-quotes # ❌
dbterd run --entity-name-format database.schema.table --omit-entity-name-quotes # ❌
dbterd run --entity-name-format schema.table --omit-entity-name-quotes # ✅

dbterd run --dbt-cloud

Decide to download artifact files from dbt Cloud Job Run instead of compiling locally.

Check Download artifacts from a Job Run for more details.

Examples:

dbterd run --dbt-cloud
dbterd run --dbt-cloud --select wildcard:*transaction*

dbterd run-metadata

Command to generate diagram-as-a-code file by connecting to dbt Cloud Discovery API using GraphQL connection.

Check this guideline for more details.

Examples:

dbterd run-metadata [-t dbml or -t mermaid]

dbterd debug

Shows hidden configured values, which will help us to see what configs are passed into and how they are evaluated to be used.

Examples:

2023-09-08 16:43:45,066 - dbterd - INFO - Run with dbterd==1.0.0 (main.py:54)
2023-09-08 16:43:45,071 - dbterd - INFO - **Arguments used** (main.py:63)
2023-09-08 16:43:45,073 - dbterd - DEBUG - {
    "artifacts_dir": "",
    "output": "C:\\Users\\DAT\\Documents\\Sources\\dbterd\\target",
    "select": [],
    "exclude": [],
    "target": "dbml",
    "algo": "test_relationship",
    "manifest_version": null,
    "catalog_version": null,
    "resource_type": [
        "model"
    ],
    "dbt": false,
    "dbt_project_dir": "",
    "dbt_target": null
} (main.py:64)
2023-09-08 16:43:45,079 - dbterd - INFO - **Arguments evaluated** (main.py:65)
2023-09-08 16:43:45,081 - dbterd - INFO - Using dbt artifact dir at: C:\Users\DAT\Documents\Sources\dbterd\target (base.py:41)
2023-09-08 16:43:45,082 - dbterd - INFO - Using dbt project  dir at: C:\Users\DAT\Documents\Sources\dbterd (base.py:42)
2023-09-08 16:43:45,084 - dbterd - DEBUG - {
    "artifacts_dir": "C:\\Users\\DAT\\Documents\\Sources\\dbterd\\target",
    "output": "C:\\Users\\DAT\\Documents\\Sources\\dbterd\\target",
    "select": [],
    "exclude": [],
    "target": "dbml",
    "algo": "test_relationship",
    "manifest_version": null,
    "catalog_version": null,
    "resource_type": [
        "model"
    ],
    "dbt": false,
    "dbt_project_dir": "C:\\Users\\DAT\\Documents\\Sources\\dbterd",
    "dbt_target": null
} (main.py:66)