From f7f70f671d3d75055c75b10d2e16a76cd28ee75d Mon Sep 17 00:00:00 2001 From: Karen Hsieh Date: Wed, 16 Apr 2025 15:44:59 -0700 Subject: [PATCH 1/4] update get started --- docs/docs/get-started.md | 114 +++++++++++++++++++++++---------------- 1 file changed, 67 insertions(+), 47 deletions(-) diff --git a/docs/docs/get-started.md b/docs/docs/get-started.md index c4b925b7..8962335e 100644 --- a/docs/docs/get-started.md +++ b/docs/docs/get-started.md @@ -5,11 +5,64 @@ icon: material/rocket-launch-outline # Getting Started -## 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 dbt 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](https://www.notion.so/infuseai/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), 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. + +## 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. For example: ```yaml jaffle_shop: target: dev @@ -24,23 +77,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,10 +84,10 @@ 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. -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. ```shell @@ -70,31 +106,15 @@ dbt run dbt docs generate ``` +## Share to collaborate +With Recce Cloud, you can share your validation view with stakeholders, no screenshots or pasted images needed. -## 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. +Just one link to share: -## 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. +- Lineage -Here are the 3 steps to use Recce: (see the image below) +- Diff results -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 +- Checklist validation and comments + +Sign up for [Recce Cloud](https://cloud.datarecce.io) and [learn more](/pricing) about the it. \ No newline at end of file From 7a855fa06f80061268b31414d1d8420f27ed4079 Mon Sep 17 00:00:00 2001 From: Karen Hsieh Date: Wed, 16 Apr 2025 20:18:57 -0700 Subject: [PATCH 2/4] update words --- docs/docs/get-started.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/docs/get-started.md b/docs/docs/get-started.md index 8962335e..e7db1fc7 100644 --- a/docs/docs/get-started.md +++ b/docs/docs/get-started.md @@ -3,7 +3,7 @@ title: Getting Started icon: material/rocket-launch-outline --- -# Getting Started +# Getting started Use Recce to validate your dbt changes with clarity and confidence. Recce helps you: @@ -13,7 +13,7 @@ Use Recce to validate your dbt changes with clarity and confidence. Recce helps For a hands-on walkthrough, check out the [Jaffle Shop Tutorial](https://www.notion.so/infuseai/get-started-jaffle-shop.md). -## Start Recce with Two Commands +## Start Recce with two commands Navigate to your dbt project and run: ```shell @@ -33,7 +33,7 @@ Recce use dbt [artifacts](https://docs.getdbt.com/reference/artifacts/dbt-artifa 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 +## Get instant visibility With just one environment, Recce gives you: @@ -45,7 +45,7 @@ With just one environment, Recce gives you: Perfect for early exploration, root cause analysis, and faster debugging before involving others. -## Unlock Diff & Validation with Two Environments +## 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: @@ -115,6 +115,8 @@ Just one link to share: - Diff results -- Checklist validation and comments +- Checklist validation with comments + +Built for teams, Recce Cloud includes secure, cloud-hosted sharing and collaboration features designed for fast reviews and confident sign-off. -Sign up for [Recce Cloud](https://cloud.datarecce.io) and [learn more](/pricing) about the it. \ No newline at end of file +[Sign up for Recce Cloud](/pricing) to unlock collaboration at scale. \ No newline at end of file From 047a19aa0c434d1579867cbabf1217d022bac6da Mon Sep 17 00:00:00 2001 From: Karen Hsieh Date: Wed, 16 Apr 2025 22:36:46 -0700 Subject: [PATCH 3/4] modify for users who see get started from Recce Cloud hompage --- docs/docs/get-started.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/docs/get-started.md b/docs/docs/get-started.md index e7db1fc7..498673cd 100644 --- a/docs/docs/get-started.md +++ b/docs/docs/get-started.md @@ -5,6 +5,8 @@ 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. + Use Recce to validate your dbt changes with clarity and confidence. Recce helps you: - Explore what changed @@ -22,7 +24,7 @@ pip install -U recce 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. +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 | | ------------- | ---------------------------------- | @@ -50,11 +52,11 @@ Not all data changes are obviously right or wrong. Comparing metrics before and When you configure two dbt environments (e.g. prod and dev schemas), Recce lets you: -- Explore modified models and downstream impact +- **Explore** modified models and downstream impact -- Validate changes via diffs or custom queries +- **Validate** changes via diffs or custom queries -- Add validation results to checklists for review and alignment +- Add validation results to **Checklists** for review and alignment ### How to setup two environments @@ -107,9 +109,9 @@ dbt docs generate ``` ## Share to collaborate -With Recce Cloud, you can share your validation view with stakeholders, no screenshots or pasted images needed. +If you’ve followed the steps above and are ready to share your checklist with others, Recce Cloud makes it easy. -Just one link to share: +Just one link gives full context: - Lineage From 0ecdb8876154af27d8dbc11dfcdd774c69f0b775 Mon Sep 17 00:00:00 2001 From: Karen Hsieh Date: Fri, 18 Apr 2025 11:03:21 -0700 Subject: [PATCH 4/4] update duckdb wording --- docs/docs/get-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/get-started.md b/docs/docs/get-started.md index 498673cd..eea46755 100644 --- a/docs/docs/get-started.md +++ b/docs/docs/get-started.md @@ -64,7 +64,7 @@ Setup two separate [environments](https://docs.getdbt.com/docs/environments-in-d 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. For example: +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