From a628d90f41b73f1b8be694df858fbb79825ca5b0 Mon Sep 17 00:00:00 2001 From: Jillian Vogel Date: Wed, 24 Jan 2024 00:53:10 +1030 Subject: [PATCH] docs: improve the "Extending dbt" how-to --- docs/how-tos/dbt_extensions.rst | 45 ++++++++++++++++++++++++++++----- 1 file changed, 38 insertions(+), 7 deletions(-) diff --git a/docs/how-tos/dbt_extensions.rst b/docs/how-tos/dbt_extensions.rst index 4a18545..8c05f14 100644 --- a/docs/how-tos/dbt_extensions.rst +++ b/docs/how-tos/dbt_extensions.rst @@ -3,14 +3,45 @@ Extending dbt ************* -As noted in :ref:`dbt`, you can install your own custom dbt packages to apply your own transforms to the event data in Aspects. +As noted in :ref:`dbt`, you can install your own custom ``dbt`` package to apply your own transforms to the event data +in Aspects. -To change which dbt packages are installed, use the following Tutor variables: +**Step 1. Create your dbt package** -- **EXTRA_DBT_PACKAGES**: A list of pip dbt packages for Aspects to install. Add your custom dbt packages here. -- **DBT_REPOSITORY**: A git repository URL to clone and use as the main Aspects dbt project. -- **DBT_BRANCH**: The branch to use when cloning ``DBT_REPOSITORY``. +See `Building dbt packages`_ for details. -To change how the ``dbt`` packages are configured, use these Tutor variables: +**Step 2. Link to aspects-dbt** -- **DBT_PROFILE_\***: variables used in the ``dbt/profiles.yml`` file, including several Clickhouse connection settings +Aspects charts depend on the transforms in `aspects-dbt`_, so it's important that your ``dbt`` package also installs +`aspects-dbt`_. + +To do this, add a ``packages.yml`` file to your ``dbt`` package at the top level, with content like this: + +.. code-block:: yaml + + packages: + - git: "https://github.com/openedx/aspects-dbt.git" + revision: v2.2 + +**Step 3. Install and run your dbt package** + +Update the following Tutor variables to use your package instead of the Aspects default. + +- **DBT_REPOSITORY**: A git repository URL to clone and use as the ``dbt`` project. + + Default: ``https://github.com/openedx/aspects-dbt`` +- **DBT_BRANCH**: The branch to use when cloning the ``dbt`` project. + + Default: varies between versions of Aspects. +- **DBT_PROJECT_DIR**: The directory to use as the ``dbt`` project. + + Default: ``aspects-dbt`` +- **EXTRA_DBT_PACKAGES**: Add any python packages that your ``dbt`` project requires here. + + Default: ``[]`` +- **DBT_PROFILE_\***: variables used in the Aspects ``dbt/profiles.yml`` file, including several Clickhouse connection settings. + +Once your package is configured in Tutor, you can run ``dbt`` commands directly on your deployment; run ``tutor [dev|local] do dbt --help`` for details. + +.. _aspects-dbt: https://github.com/openedx/aspects-dbt +.. _Building dbt packages: https://docs.getdbt.com/guides/building-packages