DJ (Data JSON) Framework Settings Reference

Complete guide to configuring the DJ (Data JSON) Framework VS Code extension.

Quick Reference

Setting	Purpose	Takes Effect
`pythonVenvPath`	Python virtual environment path	Next command ⚡
`trinoPath`	Trino CLI executable location	Next query ⚡
`dbtProjectNames`	Filter which dbt projects to load	Refresh 🔄
`dbtMacroPath`	Custom path for extension macros	Refresh 🔄
`dbtGenericTestsPath`	Custom path for generic test files	Refresh 🔄
`airflowGenerateDags`	Enable Airflow DAG generation	Refresh 🔄
`airflowTargetVersion`	Target Airflow version	Refresh 🔄
`airflowDagsPath`	Custom path for Airflow DAGs	Refresh 🔄
`lightdashProjectPath`	Custom Lightdash project path	Next preview ⚡
`lightdashProfilesPath`	Custom Lightdash profiles path	Next preview ⚡
`lightdash.defaultSqlFilter`	Global default `sql_filter` for lightdash tables	Next sync 🔄
`lightdash.defaultSqlFilterRequiredColumns`	Required columns guard for the global filter	Next sync 🔄
`lightdash.defaultPartitionColumnCaseSensitive`	Set default `case_sensitive` value for partition columns in YAML	Next sync 🔄
`lightdash.defaultAddPathToGitignore`	Default state of the Download tab `.gitignore` checkbox	Next panel ⚡
`lightdash.restrictedProjects`	Block/warn DJ Upload against Lightdash project UUIDs	Next upload ⚡
`aiHintTag`	Tag for AI-generated hints	Next sync 🔄
`codingAgent`	Coding agent integration	Refresh 🔄
`autoGenerateTests`	Auto-generate row count tests	Varies 🔄
`columnLineage.autoRefresh`	Auto-refresh column lineage	File switch ✅
`dataExplorer.autoRefresh`	Auto-refresh data explorer	File switch ✅
`logLevel`	Extension logging level	Immediate ✅

Legend: ✅ Immediate | ⚡ Next command/action | 🔄 Requires DJ: Refresh Projects or sync

Settings by Category

Python & Environment

dj.pythonVenvPath - Path to Python virtual environment

{ "dj.pythonVenvPath": ".venv" }

Supports relative (.venv) or absolute paths (/full/path/to/.venv)
Extension activates venv when running dbt and Python tools
Validated: checks for bin/activate file

dj.trinoPath - Path to Trino CLI executable (default: "trino-cli")

{ "dj.trinoPath": "/usr/local/bin" }

Supports: command names ("trino"), full paths ("/usr/bin/trino"), or directories ("/usr/local/bin")
For directories: automatically checks for trino-cli then trino
Test with: DJ: Test Trino Connection command
See Trino Integration Guide

Project Configuration

dj.dbtProjectNames - Filter which dbt projects to load

{ "dj.dbtProjectNames": ["analytics", "marketing"] }

Useful for monorepos with multiple dbt projects
Omit to load all projects
Names must match name: field in dbt_project.yml

dj.dbtMacroPath - Extension macro folder (default: "macros")

{ "dj.dbtMacroPath": "macros/ext" }

Relative to each dbt project root
Where _ext_.sql and _ext_.yml files are written

dj.dbtGenericTestsPath - Generic test location (default: "tests/generic")

{ "dj.dbtGenericTestsPath": "tests/generic" }

Airflow Integration

dj.airflowGenerateDags - Enable DAG generation (default: false)

{
  "dj.airflowGenerateDags": true,
  "dj.airflowTargetVersion": "2.10",
  "dj.airflowDagsPath": "airflow/dags"
}

dj.airflowTargetVersion - Target version: "2.7" | "2.8" | "2.9" | "2.10"

dj.airflowDagsPath - Custom DAG output directory

Lightdash Integration

dj.lightdashProjectPath - Custom dbt project path for Lightdash

dj.lightdashProfilesPath - Custom dbt profiles path

{
  "dj.lightdashProjectPath": "dbt/analytics",
  "dj.lightdashProfilesPath": ".dbt"
}

Both optional (extension auto-detects by default)
See Lightdash Configuration Guide

dj.lightdash.defaultSqlFilter - Global default sql_filter for lightdash tables

dj.lightdash.defaultSqlFilterRequiredColumns - Columns required for the default to apply

{
  "dj.lightdash.defaultSqlFilter": "account_project_id in (select id from finops.account_rollup_hierarchy where proj_level_1_cd in (${lightdash.attributes.opus_purpose_level2}))",
  "dj.lightdash.defaultSqlFilterRequiredColumns": ["account_project_id"]
}

Filtering rules:

Inheriting the default — when a model's lightdash block omits sql_filter, DJ injects the global default (only if every column in defaultSqlFilterRequiredColumns is present on the model).
No lightdash block — DJ never adds the filter; the model's YAML is unchanged.
Per-model override — lightdash.table.sql_filter: "<some other filter>" wins over the global default.
Explicit disable — lightdash.table.sql_filter: null turns the filter off for that model, even when the global default is set.
Missing required columns — when defaultSqlFilterRequiredColumns lists columns the model doesn't produce, the filter is silently skipped for that model.

Takes effect on next DJ: Sync to SQL and YML.

dj.lightdash.defaultPartitionColumnCaseSensitive - Auto-emit case_sensitive: true on partition columns in generated YAML (default: false)

{ "dj.lightdash.defaultPartitionColumnCaseSensitive": true }

When true, every generated partition column in .yml files gets meta.dimension.case_sensitive: true. This stops Lightdash from wrapping the column in UPPER() in queries, preserving Trino predicate pushdown on partitioned tables.
When false (the default), partition columns are emitted without the auto-injected case_sensitive flag. Per-model and per-column lightdash.case_sensitive overrides in .model.json continue to work in either mode.
Takes effect on next DJ: Sync to SQL and YML.

dj.lightdash.defaultAddPathToGitignore - Initial state of the Download tab Add path to .gitignore checkbox (default: true)

{ "dj.lightdash.defaultAddPathToGitignore": true }

Controls whether the Add path to .gitignore checkbox on the Dashboards-as-Code Download tab starts checked. When checked, downloading appends the configured dj.lightdash.dashboardsAsCodePath to the workspace .gitignore as a root-anchored entry (e.g. /lightdash/, inside a managed # dj … # /dj marker block) so generated YAML stays out of version control without ignoring same-named directories nested elsewhere.
When false, the checkbox starts unchecked (the previous opt-in behaviour).
This setting only seeds the checkbox's default; users can still toggle it per-download.
Takes effect the next time the Dashboards-as-Code panel is opened (no resync / refresh needed).

dj.lightdash.restrictedProjects - Restrict the DJ Dashboards-as-Code Upload tab against specific Lightdash project UUIDs (default: [])

{
  "dj.lightdash.restrictedProjects": [
    { "uuid": "prod-uuid-here", "mode": "block", "label": "production" },
    { "uuid": "preview-uuid-here", "mode": "warn", "label": "preview" }
  ]
}

mode: "block" — the Upload tab refuses to spawn lightdash upload and shows an inline error on the Project UUID field.
mode: "warn" — the Upload tab shows a confirmation dialog; the upload only runs after explicit acknowledgement.
label is optional and surfaces in the error / confirmation message alongside the UUID.
Unlisted UUIDs are allowed. Matching is case-insensitive and whitespace-tolerant.
Enforcement runs in both the webview (pre-flight) and the extension host (defense-in-depth). Direct API callers can't bypass the policy.
The setting only restricts uploads initiated from the DJ Upload tab. Users with the right Lightdash permissions can still run lightdash upload manually from a terminal; DJ has no way to intercept the standalone CLI.
Takes effect on the next DJ Lightdash upload (no resync / refresh needed).

dj.lightdash.defaultSqlFilter - Global default sql_filter for lightdash tables

dj.lightdash.defaultSqlFilterRequiredColumns - Columns required for the default to apply

{
  "dj.lightdash.defaultSqlFilter": "account_project_id in (select id from finops.account_rollup_hierarchy where proj_level_1_cd in (${lightdash.attributes.opus_purpose_level2}))",
  "dj.lightdash.defaultSqlFilterRequiredColumns": ["account_project_id"]
}

Filtering rules:

Inheriting the default — when a model's lightdash block omits sql_filter, DJ injects the global default (only if every column in defaultSqlFilterRequiredColumns is present on the model).
No lightdash block — DJ never adds the filter; the model's YAML is unchanged.
Per-model override — lightdash.table.sql_filter: "<some other filter>" wins over the global default.
Explicit disable — lightdash.table.sql_filter: null turns the filter off for that model, even when the global default is set.
Missing required columns — when defaultSqlFilterRequiredColumns lists columns the model doesn't produce, the filter is silently skipped for that model.

Takes effect on next DJ: Sync to SQL and YML.

AI & Coding Agents

dj.aiHintTag - Automatically tag models with AI hints

{ "dj.aiHintTag": "ai-hints" }

Scans descriptions for AI hint markers
Adds tag to models containing hints
Takes effect on next DJ: Sync to SQL and YML

dj.codingAgent - Enable coding agent integration

{ "dj.codingAgent": true }

Set to true (recommended) to enable AI agent integration
Writes AGENTS.md to .agents/dj/ and skill files to .agents/skills/ at the workspace root
Legacy string values ("github-copilot", "claude-code", "cline") still accepted but deprecated
Skills are agent-agnostic markdown files usable by any AI coding tool

Auto-Generation & Tests

dj.autoGenerateTests - Auto-generate row count tests (⚠️ Experimental)

{
  "dj.autoGenerateTests": {
    "enabled": true,
    "tests": {
      "equalRowCount": {
        "enabled": true,
        "applyTo": ["left"],
        "targetFolders": ["models/intermediate"]
      }
    }
  }
}

equalRowCount - Assert same row count as parent
equalOrLowerRowCount - Assert ≤ rows than parent
applyTo - Which join types: ["left", "inner", "full", "cross"]
targetFolders - Which model folders to scan
New models: tests added immediately
Existing models: requires project reload

Lineage Visualization

dj.columnLineage.autoRefresh - Auto-refresh lineage (default: true)

dj.dataExplorer.autoRefresh - Auto-refresh data preview (default: false)

{
  "dj.columnLineage.autoRefresh": false,
  "dj.dataExplorer.autoRefresh": true
}

Updates views when switching between model files
Data explorer disabled by default (executes queries)
See Lineage Documentation

Diagnostics

dj.logLevel - Logging verbosity (default: "info")

{ "dj.logLevel": "debug" }

Options: "debug" | "info" | "warn" | "error"
View logs: View → Output → DJ
Use debug for troubleshooting

When Settings Take Effect

✅ Immediate

logLevel
columnLineage.autoRefresh / dataExplorer.autoRefresh (next file switch)

⚡ Next Command/Action

pythonVenvPath - Next dbt/Python command
trinoPath - Next Trino query
lightdashProjectPath / lightdashProfilesPath - Next Lightdash preview

🔄 Requires `DJ: Refresh Projects`

Run this command (Cmd/Ctrl+Shift+P → DJ: Refresh Projects) after changing:

dbtProjectNames, dbtMacroPath, dbtGenericTestsPath
airflowGenerateDags, airflowTargetVersion, airflowDagsPath
codingAgent
autoGenerateTests (for existing models only)

🔄 Requires `DJ: Sync to SQL and YML`

aiHintTag - Recompiles models with updated tags
lightdash.defaultSqlFilter / lightdash.defaultSqlFilterRequiredColumns - Re-emits lightdash table meta on existing models
lightdash.defaultPartitionColumnCaseSensitive - Re-emits partition column YAML meta

Troubleshooting

Settings Not Working?

Check When Settings Take Effect section
Run appropriate command (Refresh Projects or Sync)
Check Output panel (View → Output → DJ) for validation errors

Path Validation Errors?

Use relative paths from workspace root: ".venv", "macros/ext"
Or use absolute paths: "/full/path/to/folder"
Ensure directories exist before setting
For trinoPath: Run DJ: Test Trino Connection to verify
For pythonVenvPath: Check for bin/activate file

Where Are Settings Stored?

Workspace settings (recommended for project-specific):

.vscode/settings.json in workspace root

User settings (apply to all projects):

Mac/Linux: ~/.config/Code/User/settings.json
Windows: %APPDATA%\Code\User\settings.json

Workspace settings override User settings.

Reset a Setting

Settings UI: Cmd/Ctrl+, → Search setting → Gear icon → "Reset Setting"

Or edit .vscode/settings.json and remove the line.

Additional Resources

Setup Guide - Initial extension setup
Lightdash Configuration - Detailed Lightdash setup
Trino Integration - Trino CLI setup
dbt Integration - dbt configuration
Lineage Guide - Column lineage features

Need help? Check the main documentation or open an issue on GitHub.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DJ (Data JSON) Framework Settings Reference

Quick Reference

Settings by Category

Python & Environment

Project Configuration

Airflow Integration

Lightdash Integration

AI & Coding Agents

Auto-Generation & Tests

Lineage Visualization

Diagnostics

When Settings Take Effect

✅ Immediate

⚡ Next Command/Action

🔄 Requires `DJ: Refresh Projects`

🔄 Requires `DJ: Sync to SQL and YML`

Troubleshooting

Settings Not Working?

Path Validation Errors?

Where Are Settings Stored?

Reset a Setting

Additional Resources

FilesExpand file tree

SETTINGS.md

Latest commit

History

SETTINGS.md

File metadata and controls

DJ (Data JSON) Framework Settings Reference

Quick Reference

Settings by Category

Python & Environment

Project Configuration

Airflow Integration

Lightdash Integration

AI & Coding Agents

Auto-Generation & Tests

Lineage Visualization

Diagnostics

When Settings Take Effect

✅ Immediate

⚡ Next Command/Action

🔄 Requires DJ: Refresh Projects

🔄 Requires DJ: Sync to SQL and YML

Troubleshooting

Settings Not Working?

Path Validation Errors?

Where Are Settings Stored?

Reset a Setting

Additional Resources

🔄 Requires `DJ: Refresh Projects`

🔄 Requires `DJ: Sync to SQL and YML`