From 0ca51eededcf9ead49c46e51cf5f84d3d0f9dd87 Mon Sep 17 00:00:00 2001 From: Karen Hsieh Date: Sat, 19 Apr 2025 11:30:00 -0700 Subject: [PATCH] update get-started --- docs/get-started.md | 117 ++++++++++++++++++++++++++------------------ 1 file changed, 69 insertions(+), 48 deletions(-) diff --git a/docs/get-started.md b/docs/get-started.md index 8e3bbdf..53819ec 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -4,12 +4,67 @@ icon: material/rocket-launch-outline --- # Getting Started +This guide walks you through how to use Recce, whether you're exploring for the first time or expanding to Recce Cloud. -## Prerequisites -Recce requires that your dbt project has two separate [environments](https://docs.getdbt.com/docs/environments-in-dbt) that refers to different [schemas](https://docs.getdbt.com/docs/core/connect-data-platform/connection-profiles#understanding-target-schemas). For example, one for production with prod schema and another for development with dev schema. +Use Recce to validate your data changes with clarity and confidence. Recce helps you: -Recce can get your schema from all data warehouses, so you don't need to update the profiles.yml. However, if you use duckdb, you need to add a separate schemas in your dbt profile so you can run locally.Your `profiles.yml` might look something like this: +- Explore what changed +- Validate downstream impacts +- Collaborate through shareable checklists +For a hands-on walkthrough, check out the [Jaffle Shop Tutorial](./get-started-jaffle-shop.md). + + +## Start Recce with two commands + +Navigate to your dbt project and run: +```shell +cd your-dbt-project/ # if you're not already there +pip install -U recce +recce server +``` + +Recce use dbt [artifacts](https://docs.getdbt.com/reference/artifacts/dbt-artifacts) generated with every invocation. You can find these files in the `target/` folder. + +| artifacts | dbt command | +| ------------- | ---------------------------------- | +| manifest.json | `dbt docs generate`, `dbt run`, .. | +| catalog.json | `dbt docs generate` | + +!!! tip + + The regeneration of the `catalog.json` file is not required after every `dbt run`. it is only required to regenerate this file when models or columns are added or updated. + +## Get instant visibility + +With just one environment, Recce gives you: + +- **Lineage clarity**: Trace changes down to the column level + +- **Query insights**: Explore logic and run custom queries + +- **Live diffing**: Reload and inspect changes as you iterate + +Perfect for early exploration, root cause analysis, and faster debugging before involving others. + +## Unlock diff & validation with two environments +Not all data changes are obviously right or wrong. Comparing metrics before and after is key to confident validation. + +When you configure two dbt environments (e.g. prod and dev schemas), Recce lets you: + +- **Explore** modified models and downstream impact + +- **Validate** changes via diffs or custom queries + +- Add validation results to **Checklists** for review and alignment + + +### How to setup two environments +Setup two separate [environments](https://docs.getdbt.com/docs/environments-in-dbt) that refers to different [schemas](https://docs.getdbt.com/docs/core/connect-data-platform/connection-profiles#understanding-target-schemas), e.g., prod for production and dev for development. + +Recce supports schema discovery across all major warehouses without needing to modify your `profiles.yml`. + +However, if you're using DuckDB, you’ll need to explicitly define both schemas to make it run locally. For example: ```yaml jaffle_shop: target: dev @@ -24,23 +79,6 @@ jaffle_shop: schema: main ``` -## Install Recce - -Install Recce using `pip`: -```shell -pip install -U recce -``` - -## Use Recce in your dbt project - -The following instructions give an overview of the process of using Recce in your dbt project. For a hands-on tutorial, please check the [Jaffle Shop Tutorial](./get-started-jaffle-shop.md). - -Navigate to your dbt project. - -```shell -cd your-dbt-project/ -``` - ### Prepare dbt artifacts Recce expects two sets of dbt [artifacts](https://docs.getdbt.com/reference/artifacts/dbt-artifacts) to be present: @@ -48,8 +86,9 @@ Recce expects two sets of dbt [artifacts](https://docs.getdbt.com/reference/arti - `target-base/` - dbt artifacts for to be used as the base for the comparison e.g. production - `target/` - dbt artifacts for your development branch -#### Prepare artifacts for the `base` environment -For most data warehouses, you can download the artifacts generated from the codebase of your main branch. You don't need to re-run the whole production in your local. +#### Generate artifacts for the `base` environment +For most data warehouses, you can download the artifacts generated from the codebase of your main branch. +You don't need to re-run the whole production in your local. However, if you use duckdb, you need to generate the artifacts for the base environment. Checkout the `main` branch of your project and generate the required artifacts into `target-base`. You can skip `dbt build` if this environment already exists. @@ -69,32 +108,14 @@ git checkout feature/my-awesome-feature dbt run dbt docs generate ``` +## Share to collaborate +If you’ve followed the steps above and are ready to share your checklist with others, Recce Cloud makes it easy. +Just one link gives full context: +- Lineage +- Diff results +- Checklist validation with comments -## Start the Recce server -Start the Recce server with the follow command: - -```shell -recce server -``` - -Recce use dbt [artifacts](https://docs.getdbt.com/reference/artifacts/dbt-artifacts), which is generated when every invocation. You can find these files in the `target/` folder. - -| artifacts | dbt command | -| ------------- | ---------------------------------- | -| manifest.json | `dbt docs generate`, `dbt run`, .. | -| catalog.json | `dbt docs generate` | - -!!! tip - - The regeneration of the `catalog.json` file is not required after every `dbt run`. it is only required to regenerate this file when models or columns are added or updated. - -## First Time Guide for Recce instance -After you start the Recce server, you can see the Recce instance, the Web UI of the active Recce server. - -Here are the 3 steps to use Recce: (see the image below) +Built for teams, Recce Cloud includes secure, cloud-hosted sharing and collaboration features designed for fast reviews and confident sign-off. -1. Click the model you want to check -1. Click “Explore Change” -1. Click “Add to Checklist” -![first time guide of Recce instance](assets/images/onboarding/material.svg){: .shadow} \ No newline at end of file +[Sign up for Recce Cloud](https://datarecce.io/pricing) to unlock collaboration at scale. \ No newline at end of file