Skip to main content

Introduction

The Reference Queries feature allows you to include SQL code from another file in your current SQL query. This is useful for reusing common parts of a query, ensuring that your SQL code is consistent and easy to maintain.

How It Works

To reference SQL code from another file, use the syntax {ref ('other_query')}, where other_query is the name of another .sql file located in the /queries folder. This syntax imports the raw SQL code from the specified file to the location where it is added.

Referencing queries as a source

An important use case for referencing queries is adding them as source. You can do this as follows:
SELECT *
FROM {ref ('users_clean')}
Which will translate to:
users_clean.sql
SELECT id, first_name, ...
FROM users
SELECT *
FROM (
    SELECT
        id,
        first_name,
        last_name,
        email
)

About queries path resolution

When you reference a query, the path is resolved relative to the current query. This means that you can reference queries in the same folder, in a parent folder, or in a sibling folder. Assuming you are editing queries/users/query.sql and you want to reference /queries/users/orders query:
queries/
  users/
    query.sql
    orders/
      query.sql
-- queries/users/query.sql
SELECT *
FROM {ref ('orders/query')}
This is equivalent to use a relative path:
-- queries/users/query.sql
SELECT *
FROM {ref ('./orders/query')}

Absolute paths.

You can also reference queries with a / prefix. This means the path of the query is resolved from the root of queries folder. Following the previous example, you can reference /queries/users/orders query as follows:
-- queries/users/query.sql
SELECT *
FROM {ref ('/users/orders/query.sql')}
queries folder doesn’t need to be included in the path. Also .sql is optional. You can add if you want
I