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:

CLI (within dbt project)--help (-h)

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:

CLI (by name)CLI (by exact name)CLI (by schema)CLI (by wildcard)CLI (by exposure)

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:

ANDOR

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

CLICLI (long style)

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:

CLICLI (long style)

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:

CLICLI (long style)

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:

CLICLI (long style)

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:

CLICLI (long style)

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:

CLI (test_relationship)CLI (semantic)CLI (long style)Use foreign_key test

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:

CLI

dbterd run --target mermaid --omit-columns

dbterd run --manifest-version (-mv)¶

Specified dbt manifest.json version

Auto detect if not specified

Examples:

CLICLI (long style)

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:

CLICLI (long style)

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:

CLICLI (long style)

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:

CLI (use dbt selection)CLI (use dbterd selection)

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:

CLI

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:

CLI

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:

CLI

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:

CLI

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:

CLI

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:

CLI

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:

CLI

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:

Output

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)

CLI Reference (dbterd)¶

dbterd run¶

dbterd run --select (-s)¶

AND and OR logic¶

dbterd run --exclude (-ns)¶

dbterd run --artifacts-dir (-ad)¶

dbterd run --output (-o)¶

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

dbterd run --target (-t)¶

dbterd run --algo (-a)¶

dbterd run --omit-columns¶

dbterd run --manifest-version (-mv)¶

dbterd run --catalog-version (-cv)¶

dbterd run --resource-type (-rt)¶

dbterd run --dbt¶

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

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

dbterd run --dbt-target (-dt)¶

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

dbterd run --omit-entity-name-quotes¶

dbterd run --dbt-cloud¶

dbterd run-metadata¶

dbterd debug¶

`AND` and `OR` logic¶