Skip to main content

SQL Runner

The SQL runner is used to build ad-hoc queries or charts using totally custom SQL.

A query built in the SQL runner can be:

  • used to power a single saved chart
  • turned into a virtual view so it becomes a reusable table
  • written back to dbt as a model

Only users with developer or admin access can use the SQL runner.

Getting started with the SQL Runner​

The SQL Runner can be accessed from the new --> Query using SQL Runner option in your navigation bar.

Once you're in the SQL Runner, you'll see four key components:

  1. A list of tables in your data warehouse that Lightdash has access to (based on your data warehouse connection in Lightdash).
  2. The schema of a selected table.
  3. The SQL query builder.
  4. The results from your latest SQL query.

To build a query in the SQL Runner, just write your query in the SQL query builder, then hit run query to see the results.

You can access your query history from your latest SQL Runner session by clicking on the query history button beside run query.

Once you've run your query, you can either:

  1. Build and save a chart from your query
  2. Create a Virtual View so your query becomes a reusable table in Lightdash
  3. Write-back to dbt so your query is saved as a governed model.

Saved charts in the SQL Runner​

Once you've run your query, you can build a chart by clicking on the chart tab in the SQL Runner.

The charts in the SQL Runner are built from the data that you generated in your query. The chart builder automatically aggregates the data from your query results using the aggregation type that you choose. Depending on the column type, the aggregation options are:

  • count (which is a distinct count and will ignore duplicates)
  • any (which will count and include duplicates)
  • sum
  • average
  • max
  • min

Once you've configured your chart, you can save it, add it to a space, and add it to a dashboard by hitting save chart.