Skip to main content

Run python scripts from any dbt project.

Project description

Welcome to dbt-fal 👋 do more with dbt

dbt-fal adapter is the ✨easiest✨ way to run your dbt Python models.

Starting with dbt v1.3, you can now build your dbt models in Python. This leads to some cool use cases that was once difficult to build with SQL alone. Some examples are:

  • Using Python stats libraries to calculate stats
  • Building forecasts
  • Building other predictive models such as classification and clustering

This is fantastic! BUT, there is still one issue though! The developer experience with Snowflake and Bigquery is not great, and there is no Python support for Redshift and Postgres.

dbt-fal provides the best environment to run your Python models that works with all other data warehouses! With dbt-fal, you can:

  • Build and test your models locally
  • Isolate each model to run in its own environment with its own dependencies
  • [Coming Soon] Run your Python models in the ☁️ cloud ☁️ with elasticly scaling Python environments.
  • [Coming Soon] Even add GPUs to your models for some heavier workloads such as training ML models.

Getting Started

1. Install dbt-fal

pip install dbt-fal[bigquery,snowflake] Add your current warehouse here

2. Update your profiles.yml and add the fal adapter

  target: dev_with_fal
      type: fal
      db_profile: dev_bigquery # This points to your main adapter
      type: bigquery

Don't forget to point to your main adapter with the db_profile attribute. This is how the fal adapter knows how to connect to your data warehouse.

3. dbt run!

That is it! It is really that simple 😊

4. [🚨 Cool Feature Alert 🚨] Environment management with dbt-fal

If you want some help with environment management (vs sticking to the default env that the dbt process runs in), you can create a fal_project.yml in the same folder as your dbt project and have “named environments”:

In your dbt project folder:

$ touch fal_project.yml

# Paste the config below
  - name: ml
    type: venv
      - prophet

and then in your dbt model:

$ vi models/

def model(dbt, fal):
    dbt.config(fal_environment="ml") # Add this line

    df: pd.DataFrame = dbt.ref("orders_daily")

The dbt.config(fal_environment=“ml”) will give you an isolated clean env to run things in, so you dont pollute your package space.

5. [Coming Soon™️] Move your compute to the Cloud!

Let us know if you are interested in this. We are looking for beta users.

dbt-fal command line tool

With the dbt-fal CLI, you can:

Head to our documentation site for a deeper dive or play with in-depth examples to see how fal can help you get more done with dbt.

1. Install dbt-fal

$ pip install dbt-fal[postgres]

2. Go to your dbt project directory

$ cd ~/src/my_dbt_project

3. Create a Python script:

import os
from slack_sdk import WebClient
from slack_sdk.errors import SlackApiError


client = WebClient(token=SLACK_TOKEN)
message_text = f"Model: {}. Status: {context.current_model.status}."

    response = client.chat_postMessage(
except SlackApiError as e:
    assert e.response["error"]

4. Add a meta section in your schema.yml

  - name: historical_ozone_levels
    description: Ozone levels
      materialized: table
      - name: ozone_level
        description: Ozone level
      - name: ds
        description: Date

5. Run dbt-fal flow run

$ dbt-fal flow run
# both your dbt models and python scripts are run

6. Alternatively run dbt and fal consecutively

$ dbt run
# Your dbt models are run

$ dbt-fal run
# Your python scripts are run

Running scripts before dbt runs

Run scripts before the model runs by using the pre-hook: configuration option.

Given the following schema.yml:

  - name: boston
    description: Ozone levels
      materialized: table
      owner: "@meder"
          - fal_scripts/
          - fal_scripts/

dbt-fal flow run will run fal_scripts/, then the boston dbt model, and finally fal_scripts/ If a model is selected with a selection flag (e.g. --select boston), the hooks associated to the model will always run with it.

$ dbt-fal flow run --select boston


profile.yml and Credentials

fal integrates with dbt's profile.yml file to access and read data from the data warehouse. Once you setup credentials in your profile.yml file for your existing dbt workflows anytime you use ref or source to create a dataframe fal authenticates using the credentials specified in the profile.yml file.

meta Syntax

  - name: historical_ozone_levels
      owner: "@me"

Use the fal and post-hook keys underneath the meta config to let fal CLI know where to look for the Python scripts. You can pass a list of scripts as shown above to run one or more scripts as a post-hook operation after a dbt run.

Variables and functions

Inside a Python script, you get access to some useful variables and functions


A context object with information relevant to the model through which the script was run. For the meta Syntax example, we would get the following:
#= historical_ozone_levels

#= {'owner': '@me'}

#= '@me'

# Could be one of
#= 'success'
#= 'error'
#= 'skipped'

context object also has access to test information related to the current model. If the previous dbt command was either test or build, the context.current_model.test property is populated with a list of tests:

#= [CurrentTest(name='not_null', modelname='historical_ozone_levels, column='ds', status='Pass')]

ref and source functions

There are also available some familiar functions from dbt

# Refer to dbt models or sources by name and returns it as `pandas.DataFrame`
source('source_name', 'table_name')

# You can use it to get the running model data

write_to_model function

❗️ We recommend using the dbt-fal adapter for writing data back to your data-warehouse.

It is also possible to send data back to your data-warehouse. This makes it easy to get the data, process it and upload it back into dbt territory.

This function is available in fal Python models only, that is a Python script inside a fal_models directory and add a fal-models-paths to your dbt_project.yml

name: "jaffle_shop"
# ...
model-paths: ["models"]
# ...

  # Add this to your dbt_project.yml
  fal-models-paths: ["fal_models"]

Once added, it will automatically be run by fal without having to add any extra configurations in the schema.yml.

source_df = source('source_name', 'table_name')
ref_df = ref('a_model')

# Your code here
df = ...

# Upload a `pandas.DataFrame` back to the datawarehouse

write_to_model also accepts an optional dtype argument, which lets you specify datatypes of columns. It works the same way as dtype argument for DataFrame.to_sql function.

from sqlalchemy.types import Integer
# Upload but specifically create the `value` column with type `integer`
# Can be useful if data has `None` values
write_to_model(df, dtype={'value': Integer()})

Importing fal as a Python package

You may be interested in accessing dbt models and sources easily from a Jupyter Notebook or another Python script. For that, just import the fal package and intantiate a FalDbt project:

from fal.dbt import FalDbt
faldbt = FalDbt(profiles_dir="~/.dbt", project_dir="../my_project")

# [
#    DbtSource(name='results' ...),
#    DbtSource(name='ticket_data_sentiment_analysis' ...)
#    ...
# ]

# [
#    DbtModel(name='zendesk_ticket_data' ...),
#    DbtModel(name='agent_wait_time' ...)
#    ...
# ]

sentiments = faldbt.source('results', 'ticket_data_sentiment_analysis')
# pandas.DataFrame
tickets = faldbt.ref('stg_zendesk_ticket_data')
# pandas.DataFrame

Why are we building this?

We think dbt is great because it empowers data people to get more done with the tools that they are already familiar with.

This library will form the basis of our attempt to more comprehensively enable data science workloads downstream of dbt. And because having reliable data pipelines is the most important ingredient in building predictive analytics, we are building a library that integrates well with dbt.

Have feedback or need help?

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dbt_fal-1.5.9.tar.gz (96.6 kB view hashes)

Uploaded source

Built Distribution

dbt_fal-1.5.9-py3-none-any.whl (123.5 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page