Substitutions¶

substitutions/<env>.yaml supplies the values LHP substitutes into ${...} tokens when generating a pipeline for environment <env> (selected by lhp generate --env <env>). Recognized top-level keys:

global:              # tokens shared across every environment
  <token>: <value>
<env>:               # dev, staging, prod, ... — one block per environment
  <token>: <value>
secrets:             # secret-scope configuration
  default_scope: <scope>
  scopes:
    <alias>: <databricks_scope>

Top-level keys¶

Key	Type	Description
`<env>`	mapping	Token map for one environment. The key matches the `--env` value (e.g. `dev`, `staging`, `prod`). Only the block matching the active environment is loaded.
`global`	mapping	Token map applied to every environment. A token also present in the active `<env>` block takes its environment-block value.
`secrets`	mapping	Secret-scope configuration (`default_scope` and `scopes`). See below.

Token maps¶

Each <env> and global block maps token names to values. A name used in a ${name} reference resolves to the value here. Values may be strings, numbers, or booleans (coerced to strings); nested mappings and lists are preserved for structured tokens.

Two reserved tokens are provided automatically and need not be declared:

Token	Default	Override
`workspace_env`	The active `--env` value.	`WORKSPACE_ENV` OS environment variable.
`logical_env`	The active `--env` value.	`LOGICAL_ENV` OS environment variable.

global:
  landing_volume: /Volumes/shared/landing

dev:
  catalog: dev_catalog
  bronze_schema: bronze
  silver_schema: silver

prod:
  catalog: prod_catalog
  bronze_schema: bronze
  silver_schema: silver

secrets¶

The top-level secrets block configures how ${secret:...} references resolve. Both fields are optional.

Field	Type	Required	Default	Description
`default_scope`	string	No	—	Scope used for the `${secret:key}` form (no scope segment). Required only if that form is used.
`scopes`	mapping	No	—	Alias-to-scope map. An alias used in `${secret:alias/key}` resolves to the mapped Databricks secret-scope name; an unmapped scope is passed through unchanged.

secrets:
  default_scope: dev_secrets
  scopes:
    database_secrets: dev_db_secrets
    storage_secrets: dev_azure_secrets

Token syntax¶

Syntax	Name	Defined in
`%{local_var}`	Local variable	`variables:` block of the flowgroup YAML (flowgroup-scoped).
`{{ template_param }}`	Template parameter	`template_parameters:` of the flowgroup; expanded by the Jinja2 template.
`${env_token}`	Environment token	`global` / `<env>` block of `substitutions/<env>.yaml`.
`${secret:scope/key}`	Secret reference	Resolved to a `dbutils.secrets.get()` call. Use `${secret:key}` to fall back to `default_scope`.

The bare {token} form (no $) is deprecated; use ${token}. Resolution order across these forms is covered in the substitutions concept page.

variables:
  entity: customer

actions:
  - name: "load_%{entity}"
    type: load
    source:
      type: delta
      catalog: "${catalog}"
      schema: "${bronze_schema}"
      table: "%{entity}"
    target: "v_%{entity}"

  - name: load_jdbc
    type: load
    source:
      type: jdbc
      url: "jdbc:postgresql://host:5432/db"
      user: "${secret:database_secrets/user}"
      password: "${secret:database_secrets/password}"
      driver: org.postgresql.Driver
      table: public.customers
    target: v_customers_raw