Visual Editor quickstart guide #6770
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
github-actions
bot
added
content
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey @matthewshaver I reviewed up until "Create a model" Will finish the rest later!
It looks really good and is a helpful intro to VE
| - Your account must have the following configured: | ||
| - A data warehouse connection | ||
| - Integration with a Git provider | ||
| - Source models for the Visual Editor must have been run at least once |
There was a problem hiding this comment.
I think we can drop the "must" as these are prerequisites and all are musts.
| - Source models for the Visual Editor must have been run at least once | |
| - Source models for the Visual Editor have been run at least once |
| - A data warehouse connection | ||
| - Integration with a Git provider | ||
| - Source models for the Visual Editor must have been run at least once | ||
| - You must have a `developer` license |
There was a problem hiding this comment.
| - You must have a `developer` license | |
| - You have a `developer` license |
|
|
||
| :::note | ||
|
|
||
| The examples in this guide use the [Jaffle Shop](https://github.com/dbt-labs/jaffle-shop) GitHub repo sample project. You can use your own data, but the Jaffle Shop offers a full-featured project useful for testing dbt features. Ask your dbt Cloud administrator about importing it to a project in your environment. They must also execute `dbt run` on the Jaffle Shop project in your `Production` environment before you begin, or you will be unable to reference the source models. |
There was a problem hiding this comment.
Should part of this note be a prereq? Just no sure how you want to phrase them:
- You have imported the Jaffle Shop project to a project in your environment.
- Have a dbt Cloud Administrator execute
dbt runon the Jaffle Shop project in yourProductionenvironment so you can reference the source models.
There was a problem hiding this comment.
The target audience for this guide is a persona that might not be able to get their dbt admin to run this in production. We don't want them to feel this guide isn't for them if they can't do that. We're using the call out to state up front that the examples use the Jaffle Shop, but they can still follow the learning path with their data if using the Jaffle Shop isn't possible. I fear if we list it as a pre-requisite they may avoid the guide if their admins won't let them run the Jaffle Shop in prod. The pre-requisites state only that whatever data you use must have been run in Prod at least once
There was a problem hiding this comment.
@matthewshaver That makes sense. Can we title the note "prerequisites for using a Jaffle Shop project?"
There was a problem hiding this comment.
Great idea! I'll add it
| 1. Click **Develop** from the main menu. If you do not see the **Develop** option, ensure you have selected a **Project** from the menu. | ||
| 2. Click **Visual Editor**. | ||
|
|
||
| <Lightbox src="/img/docs/dbt-cloud/visual-editor/ve-main-menu.png" width="90%" title="Visual Editor in the main menu."/> |
There was a problem hiding this comment.
Can we cut off the bottom half of this image? It's big for just showing the menu selection.
There was a problem hiding this comment.
Also "Visual Editor in the main menu" might be more helpful if we say in the Develop menu. Might make more sense for ereaders.
|
|
||
| <Lightbox src="/img/docs/dbt-cloud/visual-editor/ve-screen.png" width="90%" title="The Visual Editor canvas. The number of items is defined in this section." /> | ||
|
|
||
| Click on an icon to expand its section or execute an action depending on its purpose. The options are as follows: |
There was a problem hiding this comment.
Love how neat the image looks and this section feels helpful!
Co-authored-by: Leona B. Campbell <[email protected]>
There was a problem hiding this comment.
I completed this review without testing VE. Happy to test these steps or maybe @nataliefiann can?
|
|
||
| Read more about the [individual operators](/docs/cloud/visual-editor-interface#operators) to understand the basic purpose of each. The dbt model created by the Visual Editor builds off of existing models. In this guide, there will be input (source) models and an output model (what you are building) which will be _your model_. | ||
|
|
||
| ### Operator tiles |
There was a problem hiding this comment.
This "Operator tiles" section feels like it could go after the procedure as a reference. I was beginning to wonder when we'd get to the steps. We could reference it in step 2 of "Create your model from pre-existing models" in a to "learn more about" sentence. This way for those who need more they can look at that section but others can forge ahead quickly.
|
|
||
| <Lightbox src="/img/docs/dbt-cloud/visual-editor/operator-tile.png" width="90%" title="An operator tile with configurations filled out." /> | ||
|
|
||
| 1. **The connectors:** Click-and-drag to the connector on another operator to link them. |
There was a problem hiding this comment.
What do the L and R mean? Presumable left and right, but what's that about?
|
|
||
| There's a lot of data there. Dozens of customers are buying hundreds of products. You will sort it so that the customers are listed ascending by their CUSTOMER_ID number, with the most purchased products listed in descending order. | ||
|
|
||
| 1. Drag the **Order** operator over to the right of the **Aggregation** tile and connec them. |
There was a problem hiding this comment.
| 1. Drag the **Order** operator over to the right of the **Aggregation** tile and connec them. | |
| 1. Drag the **Order** operator over to the right of the **Aggregation** tile and connect them. |
| Now that you've built a model that results in the data you want, it's time to run it and push it to your Git repo. Before you run your model, keep a few items in mind: | ||
|
|
||
| - When you run previews (at any stage in the process), it does not affect the state of your warehouse. So, you can test and develop in the Visual Editor without impacting anything outside of the dbt Cloud Development environment. | ||
| - When you're ready to use this mode in a downstream tool, you can run it to materialize it in your data warehouse development schema. |
There was a problem hiding this comment.
| - When you're ready to use this mode in a downstream tool, you can run it to materialize it in your data warehouse development schema. | |
| - When you're ready to use this model in a downstream tool, you can run it to materialize it in your data warehouse development schema. |
|
|
||
| - When you run previews (at any stage in the process), it does not affect the state of your warehouse. So, you can test and develop in the Visual Editor without impacting anything outside of the dbt Cloud Development environment. | ||
| - When you're ready to use this mode in a downstream tool, you can run it to materialize it in your data warehouse development schema. | ||
| - Once your model is ready for production and ready to be used by others or orchestrated, commit it and open a PR. |
There was a problem hiding this comment.
Best to be specific in case it's not clear to some.
| - Once your model is ready for production and ready to be used by others or orchestrated, commit it and open a PR. | |
| - Once your model is ready for production and ready to be used by others or orchestrated, commit it and open a pull request. |
|
|
||
| <Lightbox src="/img/docs/dbt-cloud/visual-editor/run-results.png" width="90%" title="The results of a successful run in the 'Runs and previews' pane." /> | ||
|
|
||
| This will [materialize](/docs/build/materializations) the data as a `view` in your developer schema in the database. Once the model has been merged with your project and `dbt run` is executed in your Staging or Production environments, it will be materialized as a view in their related schemas. |
There was a problem hiding this comment.
their related schemas
Who is their? can we just say "related schemas?"
| 3. Click **Commit**. | ||
| 4. The **Commit** button will change to **Create a pull request**. You can add more commits, but click the **Create a pull request** button for now. You will then be redirected to your Git provider in a new tab. | ||
|
|
||
| The following examples use GitHub as the provider: |
There was a problem hiding this comment.
| The following examples use GitHub as the provider: | |
| The following example uses GitHub as the provider: |
|
|
||
| The models built in the Visual Editor are a part of your larger dbt project. They are stored in the `visual_editor` folder of your `/models` directory. This is all done automatically; you don't have to configure any paths or directories. | ||
|
|
||
| <Lightbox src="/img/docs/dbt-cloud/visual-editor/ve-model-folder.png" width="90%" title="Example of the Visual Editors model path in GitHub." /> |
There was a problem hiding this comment.
| <Lightbox src="/img/docs/dbt-cloud/visual-editor/ve-model-folder.png" width="90%" title="Example of the Visual Editors model path in GitHub." /> | |
| <Lightbox src="/img/docs/dbt-cloud/visual-editor/ve-model-folder.png" width="90%" title="Example of the Visual Editor's model path in GitHub." /> |
What are you changing in this pull request and why?
First edition of the quickstart guide for Visual Editor (beta). This guide makes a couple of assumptions about the reader:
Checklist
🚀 Deployment available! Here are the direct links to the updated files: