Home

Awesome

fzf-dbt - An interactive search for dbt models

Adds interactive model search and selection to dbt-cli.

Instead of having to remember your model names, you can simply type dbt run -m **<TAB> and an interactive search will appear.

It works by integrating the command line fuzzy finder fzf with dbt.

  1. Demo
    1. Interactive search and model selection
    2. Model code preview
    3. Tag and package selection
    4. Selection modifiers + and @ are also supported
  2. Installation
    1. Install fzf
    2. Install other dependencies
    3. Install fzf-dbt
  3. Usage
  4. Configuration
    1. Preview command
    2. Window Height
  5. Limitations
  6. Related Projects

Demo

fzf-dbt - demo video

Interactive search and model selection

You can narrow down the available models by typing. The search is "fuzzy". So if you want to select the model netsuite_customers_source, you can simply type custso and it will appear as the top match.

You can select the model by pressing enter and it will be added to your command line. Alternatively, you can also press tab or shift-tab to select multiple models at once.

Model code preview

While browsing the models, you can also see a preview of the model code on the right. You can even use bat to get code syntax highlighting.

The preview content can also be scrolled with your trackpad or mouse wheel.

Tag and package selection

fzf-dbt - other view

In the default view fzf-dbt shows you all your dbt models. But you can also press . to switch to the tag and package selection view.

While in the tag and package selection view, the preview will show you all the models that would be included with the tag or package.

To switch back to the model view, press ,.

Selection modifiers + and @ are also supported

Simply press < (shift and ,) to switch to the advanced model selection view that contains all models including modifiers, such as 2+stg_orders.

You can switch back to the other views by pressing , or ..

fzf-dbt - other view

Installation

Please keep in mind that currently fzf-dbt only work with zsh. So if you are using bash, you'll need to switch to zsh.

Install fzf

First you need to install fzf itself.

# Download the fzf source
git clone --depth 1 https://github.com/junegunn/fzf.git ~/.fzf

# Run the fzf install script
~/.fzf/install --key-bindings --completion --update-rc

Then simply open a new shell in a new terminal window or tab.

You can test whether fzf was installed successfully by typing ssh **<TAB>. An fzf shell with a list of previously connected SSH hosts should appear.

You are good to go if fzf appears. If not, please consult fzf's own documentation here.

Install other dependencies

You will also need to install the command line JSON processor jq. It's used to parse dbt's manifest json.

# macOS
brew install jq

# Ubuntu and debian
sudo apt-get install jq

For other systems, please consult the jq's documentation.

Optionally, you can also install bat, which is a cat clone that supports code syntax highlighting.

# macOS
brew install bat

# Ubuntu and debian
# Download and install the deb file from https://github.com/sharkdp/bat/releases

Install fzf-dbt


# Copy and paste the following command to add fzf-dbt to your `.zshrc`

cat <<EOF >> ~/.zshrc
FZF_DBT_PATH=~/.fzf-dbt/fzf-dbt.sh
if [[ ! -f $FZF_DBT_PATH ]]; then
    FZF_DBT_DIR=$(dirname $FZF_DBT_PATH)
    print -P "%F{green}Installing fzf-dbt into $FZF_DBT_DIR%f"
    mkdir -p $FZF_DBT_DIR
    command curl -L https://raw.githubusercontent.com/Infused-Insight/fzf-dbt/main/src/fzf_dbt.sh > $FZF_DBT_PATH && \
        print -P "%F{green}Installation successful.%f" || \
        print -P "%F{red}The download has failed.%f"
fi

export FZF_DBT_PREVIEW_CMD="cat {}"
export FZF_DBT_HEIGHT=80%
source $FZF_DBT_PATH
EOF

After that simply start a new shell in your terminal. Zsh will download and activate fzf-dbt.

Usage

Activation

You can activate fzf-dbt by typing **<TAB> while entering a dbt command, such as dbt run -m **<TAB>.

It's also not limited to the -m parameter and works everywhere like --select, --exclude and so on.

Search

To search, simply start typing and fzf will show you the models that match your input.

Model Selection

To select a single model, navigate to it with the up/down keyboard keys and press enter.

Alternatively, you can also use tab or shift+tab to select multiple models before sending all of them to the command line with enter.

View switching

In addition to that, you can also switch different views by pressing ,, . and <. This allows you to select tags, package paths and models with + and @ modifiers.

Please refer to the demo section above for more information and a demo video.

Configuration

Preview command

You can adjust the command that is used to show a preview of the dbt models.

To do this, simply set the FZF_DBT_PREVIEW_CMD environment variable. The {} placeholder will be replaced with the file path of the model.

It's recommended to use bat, which is a cat clone that supports code syntax highlighting.

Edit your .zshrc and adjust the FZF_DBT_PREVIEW_CMD variable to something like...

export FZF_DBT_PREVIEW_CMD='bat --theme OneHalfLight --color=always --style=numbers {}'

Window Height

You can also adjust the height of the window. By default, it is 80% of your terminal window's height.

But you can adjust it with...

export FZF_DBT_HEIGHT=40%

Limitations

In order to be fast, fzf-dbt parses dbt's manifest.json file. But this file is only updated when you run the compile, run, test or another dbt command that compiles the project.

Therefore if you add a models, but don't run any of these commands, fzf-dbt won't be able to find those models.

Related Projects