Skip to content

dct describe

Describe a dashboard's queries, charts, variables, and layout.

dct describe [OPTIONS] [PATH...]

With no PATH, prints the project overview (see below).

Arguments

Argument Description
PATH... Path(s) to board YAML files or directories. Omit for the project overview.

Options

Flag Description
--chart ID Describe one chart on the board: the chart, the queries it reads, and only the variables it depends on. Takes exactly one board file.
--all Project overview only: also list each board's charts (name, type, query, title). Not allowed with a PATH.
--json Output as JSON.
--project-dir PATH Project directory for resolving relative paths.

Examples

dct describe charts/sales.yml
dct describe charts/sales.yml --json
dct describe charts/sales.yml charts/inventory.yml --json
dct describe charts/
dct describe charts/*.yml --json | jq '.[] | select(.charts | length > 5)'
dct describe charts/sales.yml --chart revenue_kpi

A chart is addressed by its board path plus its chart id, the same pair dct render BOARD --chart ID takes. dct search lists the matching chart ids for each board. An id the board doesn't declare fails with ERR-UNKNOWN-CHART, which lists the board's charts.

When given a directory, dct describe globs **/*.yml and **/*.yaml, skipping any file whose name starts with _ (partials and templates).

Project overview

dct describe with no path orients you in a project in one call:

  • the config file and project root;
  • sources: configured sources: names, each data file with the source: value to write, and the sources: entry for each database file;
  • boards: path, serve URL, and title (YAML and markdown boards);
  • the warehouse tables the boards read, and which boards read each one.

The table list is built without running any query. A board that does not compile, or whose SQL cannot be read, is named under "Incomplete" because the table list may miss its reads.

dct describe
dct describe --all --json

JSON output shape

Single file: returns a JSON object. Two or more files: returns a JSON array. Exit code is 1 if any file has errors.