Quickstart for dbt Cloud and Azure Synapse Analytics

Updated

dbt Cloud

Quickstart

Beginner

Introduction

In this quickstart guide, you'll learn how to use dbt Cloud with Azure Synapse Analytics. It will show you how to:

Load the Jaffle Shop sample data (provided by dbt Labs) into your Azure Synapse Analytics warehouse.
Connect dbt Cloud to Azure Synapse Analytics.
Turn a sample query into a model in your dbt project. A model in dbt is a SELECT statement.
Add tests to your models.
Document your models.
Schedule a job to run.

Prerequisites

You have a dbt Cloud account.
You have an Azure Synapse Analytics account. For a free trial, refer to Synapse Analytics in the Microsoft docs.
As a Microsoft admin, you’ve enabled service principal authentication. You must add the service principal to the Synapse workspace with either a Member (recommended) or Admin permission set. For details, refer to Create a service principal using the Azure portal in the Microsoft docs. dbt Cloud needs these authentication credentials to connect to Azure Synapse Analytics.

Load data into your Azure Synapse Analytics

Log in to your Azure portal account.
On the home page, select the SQL databases tile.
From the SQL databases page, navigate to your organization’s workspace or create a new workspace; refer to Create a Synapse workspace in the Microsoft docs for more details.
From the workspace's sidebar, select Data. Click the three dot menu on your database and select New SQL script to open the SQL editor.

Copy these statements into the SQL editor to load the Jaffle Shop example data:

CREATE TABLE dbo.customers
(
    [ID] [bigint],
    [FIRST_NAME] [varchar](8000),
    [LAST_NAME] [varchar](8000)
);

COPY INTO [dbo].[customers]
FROM 'https://dbtlabsynapsedatalake.blob.core.windows.net/dbt-quickstart-public/jaffle_shop_customers.parquet'
WITH (
    FILE_TYPE = 'PARQUET'
);

CREATE TABLE dbo.orders
(
    [ID] [bigint],
    [USER_ID] [bigint],
    [ORDER_DATE] [date],
    [STATUS] [varchar](8000)
);

COPY INTO [dbo].[orders]
FROM 'https://dbtlabsynapsedatalake.blob.core.windows.net/dbt-quickstart-public/jaffle_shop_orders.parquet'
WITH (
    FILE_TYPE = 'PARQUET'
);

CREATE TABLE dbo.payments
(
    [ID] [bigint],
    [ORDERID] [bigint],
    [PAYMENTMETHOD] [varchar](8000),
    [STATUS] [varchar](8000),
    [AMOUNT] [bigint],
    [CREATED] [date]
);

COPY INTO [dbo].[payments]
FROM 'https://dbtlabsynapsedatalake.blob.core.windows.net/dbt-quickstart-public/stripe_payments.parquet'
WITH (
    FILE_TYPE = 'PARQUET'
);

Example of loading data

Connect dbt Cloud to Azure Synapse Analytics

Create a new project in dbt Cloud. Open the gear menu in the top right corner, select Account settings and click + New Project.
Enter a project name and click Continue.
Choose Synapse as your connection and click Next.
In the Configure your environment section, enter the Settings for your new project:
- Server — Use the service principal's Synapse host name value (without the trailing , 1433 string) for the Synapse test endpoint.
- Port — 1433 (which is the default).
- Database — Use the service principal's database value for the Synapse test endpoint.
Enter the Development credentials for your new project:
- Authentication — Choose Service Principal from the dropdown.
- Tenant ID — Use the service principal’s Directory (tenant) id as the value.
- Client ID — Use the service principal’s application (client) ID id as the value.
- Client secret — Use the service principal’s client secret (not the client secret id) as the value.
Click Test connection. This verifies that dbt Cloud can access your Azure Synapse Analytics account.
Click Next when the test succeeds. If it failed, you might need to check your Microsoft service principal.

Set up a dbt Cloud managed repository

When you develop in dbt Cloud, you can leverage Git to version control your code.

To connect to a repository, you can either set up a dbt Cloud-hosted managed repository or directly connect to a supported git provider. Managed repositories are a great way to trial dbt without needing to create a new repository. In the long run, it's better to connect to a supported git provider to use features like automation and continuous integration.

To set up a managed repository:

Under "Setup a repository", select Managed.
Type a name for your repo such as bbaggins-dbt-quickstart
Click Create. It will take a few seconds for your repository to be created and imported.
Once you see the "Successfully imported repository," click Continue.

Initialize your dbt project and start developing

Now that you have a repository configured, you can initialize your project and start development in dbt Cloud:

Click Start developing in the IDE. It might take a few minutes for your project to spin up for the first time as it establishes your git connection, clones your repo, and tests the connection to the warehouse.
Above the file tree to the left, click Initialize dbt project. This builds out your folder structure with example models.
Make your initial commit by clicking Commit and sync. Use the commit message initial commit and click Commit Changes. This creates the first commit to your managed repo and allows you to open a branch where you can add new dbt code.
You can now directly query data from your warehouse and execute dbt run. You can try this out now:
- In the command line bar at the bottom, enter dbt run and click Enter. You should see a dbt run succeeded message.

Build your first model

Under Version Control on the left, click Create branch. You can name it add-customers-model. You need to create a new branch since the main branch is set to read-only mode.
Click the three dot menu (...) next to the models directory, then select Create file.
Name the file customers.sql, then click Create.

Copy the following query into the file and click Save.

customers.sql

with customers as (

select
    ID as customer_id,
    FIRST_NAME as first_name,
    LAST_NAME as last_name

from dbo.customers
),

orders as (

    select
        ID as order_id,
        USER_ID as customer_id,
        ORDER_DATE as order_date,
        STATUS as status

    from dbo.orders
),

customer_orders as (

    select
        customer_id,

        min(order_date) as first_order_date,
        max(order_date) as most_recent_order_date,
        count(order_id) as number_of_orders

    from orders

    group by customer_id
),

final as (

    select
        customers.customer_id,
        customers.first_name,
        customers.last_name,
        customer_orders.first_order_date,
        customer_orders.most_recent_order_date,
        coalesce(customer_orders.number_of_orders, 0) as number_of_orders

    from customers

    left join customer_orders on customers.customer_id = customer_orders.customer_id
)

select * from final

Enter dbt run in the command prompt at the bottom of the screen. You should get a successful run and see the three models.

Later, you can connect your business intelligence (BI) tools to these views and tables so they only read cleaned up data rather than raw data in your BI tool.

FAQs

How can I see the SQL that dbt is running?

How did dbt choose which schema to build my models in?

Do I need to create my target schema before running dbt?

If I rerun dbt, will there be any downtime as models are rebuilt?

What happens if the SQL in my query is bad or I get a database error?

Change the way your model is materialized

One of the most powerful features of dbt is that you can change the way a model is materialized in your warehouse, simply by changing a configuration value. You can change things between tables and views by changing a keyword rather than writing the data definition language (DDL) to do this behind the scenes.

By default, everything gets created as a view. You can override that at the directory level so everything in that directory will materialize to a different materialization.

Edit your dbt_project.yml file.
- Update your project name to:
  dbt_project.yml
  name: 'jaffle_shop'
- Configure jaffle_shop so everything in it will be materialized as a table; and configure example so everything in it will be materialized as a view. Update your models config block to:
  dbt_project.yml
  models: jaffle_shop: +materialized: table example: +materialized: view
- Click Save.
Enter the dbt run command. Your customers model should now be built as a table!

info
To do this, dbt had to first run a drop view statement (or API call on BigQuery), then a create table as statement.
Edit models/customers.sql to override the dbt_project.yml for the customers model only by adding the following snippet to the top, and click Save:
models/customers.sql
```
{{
  config(
    materialized='view'
  )
}}

with customers as (

    select
        id as customer_id
        ...

)
```
Enter the dbt run command. Your model, customers, should now build as a view.
- BigQuery users need to run dbt run --full-refresh instead of dbt run to full apply materialization changes.
Enter the dbt run --full-refresh command for this to take effect in your warehouse.

FAQs

What materializations are available in dbt?

Which materialization should I use for my model?

What model configurations exist?

Delete the example models

You can now delete the files that dbt created when you initialized the project:

Delete the models/example/ directory.

Delete the example: key from your dbt_project.yml file, and any configurations that are listed under it.

dbt_project.yml

# before
models:
  jaffle_shop:
    +materialized: table
    example:
      +materialized: view

dbt_project.yml

# after
models:
  jaffle_shop:
    +materialized: table

Save your changes.

FAQs

How do I remove deleted models from my data warehouse?

I got an "unused model configurations" error message, what does this mean?

Build models on top of other models

As a best practice in SQL, you should separate logic that cleans up your data from logic that transforms your data. You have already started doing this in the existing query by using common table expressions (CTEs).

Now you can experiment by separating the logic out into separate models and using the ref function to build models on top of other models:

The DAG we want for our dbt project

Create a new SQL file, models/stg_customers.sql, with the SQL from the customers CTE in our original query.

Create a second new SQL file, models/stg_orders.sql, with the SQL from the orders CTE in our original query.

models/stg_customers.sql

select
    ID as customer_id,
    FIRST_NAME as first_name,
    LAST_NAME as last_name

from dbo.customers

models/stg_orders.sql

select
    ID as order_id,
    USER_ID as customer_id,
    ORDER_DATE as order_date,
    STATUS as status

from dbo.orders

Edit the SQL in your models/customers.sql file as follows:

models/customers.sql

with customers as (

    select * from {{ ref('stg_customers') }}

),

orders as (

    select * from {{ ref('stg_orders') }}

),

customer_orders as (

    select
        customer_id,

        min(order_date) as first_order_date,
        max(order_date) as most_recent_order_date,
        count(order_id) as number_of_orders

    from orders

    group by customer_id

),

final as (

    select
        customers.customer_id,
        customers.first_name,
        customers.last_name,
        customer_orders.first_order_date,
        customer_orders.most_recent_order_date,
        coalesce(customer_orders.number_of_orders, 0) as number_of_orders

    from customers

    left join customer_orders on customers.customer_id = customer_orders.customer_id

)

select * from final

Execute dbt run.

This time, when you performed a dbt run, separate views/tables were created for stg_customers, stg_orders and customers. dbt inferred the order to run these models. Because customers depends on stg_customers and stg_orders, dbt builds customers last. You do not need to explicitly define these dependencies.

FAQs

How do I run one model at a time?

Do model names need to be unique?

As I create more models, how should I keep my project organized? What should I name my models?

Add tests to your models

Adding tests to a project helps validate that your models are working correctly.

To add tests to your project:

Create a new YAML file in the models directory, named models/schema.yml

Add the following contents to the file:

models/schema.yml

version: 2

models:
  - name: customers
    columns:
      - name: customer_id
        tests:
          - unique
          - not_null

  - name: stg_customers
    columns:
      - name: customer_id
        tests:
          - unique
          - not_null

  - name: stg_orders
    columns:
      - name: order_id
        tests:
          - unique
          - not_null
      - name: status
        tests:
          - accepted_values:
              values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']
      - name: customer_id
        tests:
          - not_null
          - relationships:
              to: ref('stg_customers')
              field: customer_id

Run dbt test, and confirm that all your tests passed.

When you run dbt test, dbt iterates through your YAML files, and constructs a query for each test. Each query will return the number of records that fail the test. If this number is 0, then the test is successful.

FAQs

What tests are available for me to use in dbt? Can I add my own custom tests?

How do I test one model at a time?

One of my tests failed, how can I debug it?

Does my test file need to be named `schema.yml`?

Why do model and source yml files always start with `version: 2`?

What tests should I add to my project?

When should I run my tests?

Document your models

Adding documentation to your project allows you to describe your models in rich detail, and share that information with your team. Here, we're going to add some basic documentation to our project.

Update your models/schema.yml file to include some descriptions, such as those below.

models/schema.yml

version: 2

models:
  - name: customers
    description: One record per customer
    columns:
      - name: customer_id
        description: Primary key
        tests:
          - unique
          - not_null
      - name: first_order_date
        description: NULL when a customer has not yet placed an order.

  - name: stg_customers
    description: This model cleans up customer data
    columns:
      - name: customer_id
        description: Primary key
        tests:
          - unique
          - not_null

  - name: stg_orders
    description: This model cleans up order data
    columns:
      - name: order_id
        description: Primary key
        tests:
          - unique
          - not_null
      - name: status
        tests:
          - accepted_values:
              values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']
      - name: customer_id
        tests:
          - not_null
          - relationships:
              to: ref('stg_customers')
              field: customer_id

Run dbt docs generate to generate the documentation for your project. dbt introspects your project and your warehouse to generate a JSON file with rich documentation about your project.

Click the book icon in the Develop interface to launch documentation in a new tab.

FAQs

How do I write long-form explanations in my descriptions?

How do I access documentation in dbt Explorer?

Commit your changes

Now that you've built your customer model, you need to commit the changes you made to the project so that the repository has your latest code.

If you edited directly in the protected primary branch:

Click the Commit and sync git button. This action prepares your changes for commit.
A modal titled Commit to a new branch will appear.
In the modal window, name your new branch add-customers-model. This branches off from your primary branch with your new changes.
Add a commit message, such as "Add customers model, tests, docs" and and commit your changes.
Click Merge this branch to main to add these changes to the main branch on your repo.

If you created a new branch before editing:

Since you already branched out of the primary protected branch, go to Version Control on the left.
Click Commit and sync to add a message.
Add a commit message, such as "Add customers model, tests, docs."
Click Merge this branch to main to add these changes to the main branch on your repo.

Deploy dbt

Use dbt Cloud's Scheduler to deploy your production jobs confidently and build observability into your processes. You'll learn to create a deployment environment and run a job in the following steps.

Create a deployment environment

In the upper left, select Deploy, then click Environments.
Click Create Environment.
In the Name field, write the name of your deployment environment. For example, "Production."
In the dbt Version field, select the latest version from the dropdown.
Under Deployment connection, enter the name of the dataset you want to use as the target, such as "Analytics". This will allow dbt to build and work with that dataset. For some data warehouses, the target dataset may be referred to as a "schema".
Click Save.

Create and run a job

Jobs are a set of dbt commands that you want to run on a schedule. For example, dbt build.

As the jaffle_shop business gains more customers, and those customers create more orders, you will see more records added to your source data. Because you materialized the customers model as a table, you'll need to periodically rebuild your table to ensure that the data stays up-to-date. This update will happen when you run a job.

After creating your deployment environment, you should be directed to the page for a new environment. If not, select Deploy in the upper left, then click Jobs.
Click Create one and provide a name, for example, "Production run", and link to the Environment you just created.
Scroll down to the Execution Settings section.
Under Commands, add this command as part of your job if you don't see it:
- dbt build
Select the Generate docs on run checkbox to automatically generate updated project docs each time your job runs.
For this exercise, do not set a schedule for your project to run — while your organization's project should run regularly, there's no need to run this example project on a schedule. Scheduling a job is sometimes referred to as deploying a project.
Select Save, then click Run now to run your job.
Click the run and watch its progress under "Run history."
Once the run is complete, click View Documentation to see the docs for your project.

Congratulations 🎉! You've just deployed your first dbt project!

FAQs

What happens if one of my runs fails?

Introduction​

Prerequisites​

Related content​

Load data into your Azure Synapse Analytics​

Connect dbt Cloud to Azure Synapse Analytics​

Set up a dbt Cloud managed repository​

Initialize your dbt project​ and start developing​

Build your first model​

FAQs​

Change the way your model is materialized​

FAQs​

Delete the example models​

FAQs​

Build models on top of other models​

FAQs​

Add tests to your models​

FAQs​

Document your models​

FAQs​

Commit your changes​

Deploy dbt​

Create a deployment environment​

Create and run a job​

FAQs​

Introduction

Prerequisites

Related content

Load data into your Azure Synapse Analytics

Connect dbt Cloud to Azure Synapse Analytics

Set up a dbt Cloud managed repository

Initialize your dbt project and start developing

Build your first model

FAQs

Change the way your model is materialized

FAQs

Delete the example models

FAQs

Build models on top of other models

FAQs

Add tests to your models

FAQs

Document your models

FAQs

Commit your changes

Deploy dbt

Create a deployment environment

Create and run a job

FAQs