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}
|
|
||
| :::tip | ||
|
|
||
| Want to practice on your own? Try adding a **Filter** operator that removes items with less than 10 sales for any customer ID. Be sure to run the preview and verify the data is correct. |
There was a problem hiding this comment.
agreed, excellent practice item here!
| Click on an icon to expand its section or execute an action depending on its purpose. The options are as follows: | ||
|
|
||
| 1. The model's title. This defaults to "Untitled" but can be edited anytime by clicking on it. | ||
| 2. The **Operators** menu contains the building blocks of [creating a model](#create-a-model) with the editor. |
There was a problem hiding this comment.
Hiya @matthewshaver
It could just be me, but when I click this link, it doesn't take me to a page and when I right click to open the link in a new window, I'm directed to the same page.
Kind Regards
Natalie
Co-authored-by: Mirna Wong <[email protected]>
There was a problem hiding this comment.
this is looking great @matthewshaver ! i have a couple thoughts on a few wording items such as "source" but not married to them . thank you!!
|
|
||
| :::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 before you begin, or you will be unable to reference the source models. |
There was a problem hiding this comment.
don't they need to build the full jaffle shop dataset in prod before it's usable in VE? rather than just a dbt run in dev?
There was a problem hiding this comment.
Good question! WIll get an answer and clarify
There was a problem hiding this comment.
yep, they'll need a prod run before this is useable.
| Click on an icon to expand its section or execute an action depending on its purpose. The options are as follows: | ||
|
|
||
| 1. The model's title. This defaults to "Untitled" but can be edited anytime by clicking on it. | ||
| 2. The **Operators** menu contains the building blocks of creating a model with the editor. |
There was a problem hiding this comment.
in these docs: https://docs.getdbt.com/docs/cloud/visual-editor-interface you call it the "Operator toolbar"--are you married to menu or toolbar? I have called it the operator toolbar in the lesson outline.
not sure how important this is lol just flagging that it's called different stuff
There was a problem hiding this comment.
Let's stick with toolbar!
| - Center the model to fit the screen | ||
| - Auto-layout option for the individual operator tiles | ||
| 8. The **Run** command executes `dbt run` for the model. | ||
| 9. This button is initially a **Commit** command for your integrated Git provider. Changes will be made to "Open pull request" once changes are committed. This will not appear until a change is made requiring a commit. |
There was a problem hiding this comment.
the wording feels a little unclear to me in number 9 here....maybe something closer to "The button will change to 'open pull request' once changes are committed"
|
|
||
| ::: | ||
|
|
||
| ### Create your source models |
There was a problem hiding this comment.
mixed feelings on calling these source models given that they're not dbt sources? is there another thing we could call them? maybe "create your first models"? especially since reading in sources is something that's coming to VE?
|
|
||
| <Lightbox src="/img/docs/dbt-cloud/visual-editor/one-model-operator.png" width="90%" title="A single model operator." /> | ||
|
|
||
| You now have your first data source! |
There was a problem hiding this comment.
also here. maybe just "you now have your first model in visual editor" or something like that?
|
|
||
| <Lightbox src="/img/docs/dbt-cloud/visual-editor/two-model-operators.png" width="90%" title="Two model operators in the canvas."/> | ||
|
|
||
| Now, you have two source data models and are ready to transform the data! |
|
|
||
| :::tip | ||
|
|
||
| Don't see a source model you're looking for? Ask your dbt admins to ensure it's been run recently and hasn't gone stale. |
There was a problem hiding this comment.
same here w/source. and is it worth saying "been run in production" recently? the reader might not know what that means but their dbt admin would know.
|
|
||
| ## Enhance your model | ||
|
|
||
| You've got the basics going with your Visual Editor model! It has successfully joined two source models, but you need to further transform the data to get what you need. A list of customers who buy repeat items as you consider a loyalty club rewards program. |
There was a problem hiding this comment.
flagging another source mention here
|
|
||
| :::tip | ||
|
|
||
| Want to practice on your own? Try adding a **Filter** operator that removes items with less than 10 sales for any customer ID. Be sure to run the preview and verify the data is correct. |
There was a problem hiding this comment.
agreed, excellent practice item here!
|
|
||
| ### Run | ||
|
|
||
| To run your model, you only need to click the big **Run** button. With the Visual Editor, there is no command line and no need to memorize a list of commands; there is only **Run**. Click it to see the results populate in the **Runs and previews** pane. |
github-actions
bot
added
size: large
| 6. Click **Select and rename columns** and click **Configure columns** | ||
| select the following columns: | ||
| - From `stg_orders` click `ORDER_ID` and `CUSTOMER_ID`. | ||
| - From `stg_order` click `PRODUCT_ID`. |
There was a problem hiding this comment.
should this be stg_order_items?
| 6. Complete the **Add a title** and **Add a description** fields. If your description is split between both, copy all the contents to the description field and give it a shorter title. | ||
| 7. Click **Create pull request**. | ||
|
|
||
| You've just submitted your first model from the Visual Editor for review. Once approved and merged, the model will be included in your organization’s project and run whenever `dbt run` is executed in any environment it is in. You're now on your way to becoming an expert in data transformation! |
There was a problem hiding this comment.
| You've just submitted your first model from the Visual Editor for review. Once approved and merged, the model will be included in your organization’s project and run whenever `dbt run` is executed in any environment it is in. You're now on your way to becoming an expert in data transformation! | |
| You've just submitted your first model from the Visual Editor for review. Once approved and merged, the model will be included in your organization’s project and run whenever `dbt run` is executed in any environment your model is in. You're now on your way to becoming an expert in data transformation! |
|
|
||
| ## Prerequisites | ||
|
|
||
| To use the Visual Editor, you must meet the following prerequisites: |
There was a problem hiding this comment.
Enterprise only as well!
|
|
||
| ## Navigating the interface | ||
|
|
||
| The Visual editor comprises a series of menus activated by clicking icons surrounding the border of the larger canvas. With none of the menu items activated, the workspace looks like this: |
There was a problem hiding this comment.
nit: capitalize Editor
|
|
||
| <Lightbox src="/img/docs/dbt-cloud/visual-editor/operators.png" width="90%" title="The operator’s menu on the side of the Visual Editor canvas." /> | ||
|
|
||
| Read more about the [individual operators](/docs/cloud/visual-editor-interface#operators) to understand the basic purpose of each. Keep in mind that the model you're creating relies on existing models and that the term will primarily be used to reference the model operator in this section. |
There was a problem hiding this comment.
I'd clarify the second half of this sentence. Maybe:
"The dbt model created by the Visual Editor builds off of existing models - in these docs, the term "model" will primarily refer to the model operator found this operator drawer."
| <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. | ||
| 2. **The title:** Click to change. The examples in this guide will remain default. |
There was a problem hiding this comment.
"In images in this guide, the operators names are kept as the defaults."
|
|
||
| 1. **The connectors:** Click-and-drag to the connector on another operator to link them. | ||
| 2. **The title:** Click to change. The examples in this guide will remain default. | ||
| 3. **Play icon and menu:** Preview the data at any point in its transformation by clicking the tiles play icon. The dropdown menu contains the option to **Delete** a tile. |
|
|
||
| 1. Expand the **Operators** menu and drag the **Model** operator over to the canvas. | ||
| 2. Click **Configure model** and then select the source `stg_models` from the dropdown. | ||
| 3. Click the **Output all columns** option. |
|
|
||
| ::: | ||
|
|
||
| ### Create your model with pre-existing data |
There was a problem hiding this comment.
should we clarify that this is building from a pre-existing dbt model?
|
|
||
| ## Enhance your model | ||
|
|
||
| You've got the basics going with your Visual Editor model! It has successfully joined two pre-existing models, but you need to transform the data further to get what you need. A list of customers who buy repeat items as you consider a loyalty club rewards program. |
|
|
||
| ## Run and share your model | ||
|
|
||
| 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. |
There was a problem hiding this comment.
I would break this down and recap how preview/run/prod work at the top, since it's a new concept.
- preview does not affect state in your warehouse, so you can test and develop.
- when you're ready to use this mode in a downstream tool, you can run it to materialize it in the warehouse.
- Once the model is ready to make its way to production and be used by others or orchestrated, you can commit and open a PR.
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: