Virtual views

Turn a custom SQL query into a reusable table in Lightdash. Build a virtual view in the SQL Runner, explore and join it like any dbt table, and manage it as code.

A virtual view is created in the SQL Runner and lets other users reuse your custom SQL query in Lightdash. It gets listed in your Tables and can be used like the tables that come from your dbt project.

A virtual view won’t be saved to or managed in your dbt project.

If you’re expecting to use this query regularly, we recommend writing it back to dbt.

Create a virtual view

To create a virtual view from the SQL Runner, select the Create Virtual View option from the save drop-down.

Your virtual view will appear in the list of Tables available to explore in Lightdash. Everyone in your team can use virtual views to build queries and charts just like they would any other Table.

Edit or delete a virtual view

To edit a virtual view, you need to open it in the Explorer, then beside the name, there’s a three-dot-menu where you can choose to edit or delete the virtual view.

Any changes you make will affect all existing content built using the virtual view.

Manage virtual views as code

You can manage virtual views as code alongside your charts and dashboards with the Lightdash CLI. This is useful when you want to review virtual-view changes in a pull request, promote the same SQL across projects (for example from a staging to a production Lightdash instance), or template a set of virtual views for reuse.

Virtual views are opt-in — a bare lightdash download does not pull them, and a bare lightdash upload does not push them. You have to ask for them explicitly with --include-virtual-views or --virtual-views <slug>.

Download virtual views

Use --include-virtual-views to download every virtual view in the project, or --virtual-views <slug> to download specific ones:

# All virtual views in the project
lightdash download --include-virtual-views

# Only the virtual views you name
lightdash download --virtual-views orders_enriched customers_enriched

Each virtual view is written to lightdash/virtual-views/<slug>.yml. To skip virtual views when a filter is otherwise selecting them, add --skip-virtual-views.

Virtual view YAML

Virtual views serialize to a portable YAML contract keyed by a project-scoped slug (the immutable explore name used by any charts, dashboards, or joined models that reference the view). The name is the mutable display label shown in the UI.

Virtual view YAML example

contentType: virtual_view
version: 1
slug: orders_enriched
name: "Orders enriched"
sql: |-
  select
    o.order_id,
    o.customer_id,
    o.status,
    o.created_at,
    o.total_amount,
    c.country
  from ecom.orders o
  left join ecom.customers c on c.customer_id = o.customer_id
columns:
  - reference: country
    type: string
  - reference: created_at
    type: timestamp
  - reference: customer_id
    type: string
  - reference: order_id
    type: string
  - reference: status
    type: string
  - reference: total_amount
    type: number
parameters: null

Field	Description
contentType	Always virtual_view.
version	Schema version. Currently 1.
slug	Immutable project-scoped identifier. Must be canonical snake_case — this is the explore name that downstream charts and dashboards reference.
name	Display label for the UI. Safe to rename.
sql	Raw SELECT for the virtual view. Referenced parameters must have matching keys in parameters.
columns	The list of columns exposed as dimensions. Each entry needs a unique reference and a valid dimension type. Columns are sorted by reference on download.
parameters	Saved parameter values used by the view’s SQL, or null if the view takes no parameters.

Upload virtual views

Use --virtual-views <slug> on lightdash upload to target specific views, or run a bare upload (without any content filters) to include every virtual view in lightdash/virtual-views/.

# Upload one virtual view
lightdash upload --virtual-views orders_enriched

# Upload everything, including any virtual views on disk
lightdash upload

The CLI compares each file against the current cached version of the view and reports one of:

• created — no view with this slug existed yet.
• updated — the view existed and one or more fields changed.
• skipped — the file is byte-equivalent to the current view, so nothing is sent.

If the same slug already exists as a non-virtual explore (for example, a dbt model), the upload is rejected — Lightdash won’t adopt a dbt-managed explore into virtual-view storage.

Validation errors

Uploads fail fast with a ParameterError when the YAML isn’t a valid virtual view. Common causes:

• slug is empty, contains slashes, or isn’t canonical snake_case.
• name or sql is empty.
• columns is empty, contains duplicate or blank reference values, or uses an unknown type.
• parameters includes keys that the sql never references.
• contentType isn’t virtual_view or version isn’t the supported version.

Fix the YAML locally and re-run lightdash upload.

Destructive changes and --force

Removing a column or changing its type is a destructive change — any charts or dashboards that reference the removed or retyped column will break. To protect against accidental breakage, the CLI rejects destructive column changes by default and lists the offending columns in the error.

Re-run the upload with --force when the change is intentional:

lightdash upload --virtual-views orders_enriched --force

--force also allows replacing a virtual view whose cached state can no longer be represented as YAML (for example, a legacy view with non-subquery SQL).

Permissions

Virtual view download and upload reuse the same content-as-code scopes as charts and dashboards:

• view:ContentAsCode is required to download virtual views.
• manage:ContentAsCode is required to upload virtual views. Uploads also check the virtual-view edit permissions the UI enforces, so the CLI, API, and app stay in lockstep.