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

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 Qyra. 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 Qyra 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 Qyra instance), or template a set of virtual views for reuse.

Virtual views are opt-in — a bare qyra download does not pull them, and a bare qyra 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
qyra download --include-virtual-views

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

Each virtual view is written to qyra/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.

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

Upload virtual views

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

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

# Upload everything, including any virtual views on disk
qyra 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 — Qyra 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 qyra 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:

qyra 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.