From 3521ce12a2441aa4b8e24d74ed587eab72db2875 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Mon, 15 Jan 2024 11:29:35 +0000 Subject: [PATCH 1/8] add context --- .../1-how-we-style-our-dbt-models.md | 4 ++ website/docs/docs/build/models.md | 2 - website/docs/docs/build/sql-models.md | 5 +- .../dbt-cloud-ide/develop-in-the-cloud.md | 54 +++++++++---------- 4 files changed, 32 insertions(+), 33 deletions(-) diff --git a/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md b/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md index 0157af63cfb..a524eaded0c 100644 --- a/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md +++ b/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md @@ -8,6 +8,10 @@ id: 1-how-we-style-our-dbt-models - πŸ‘₯ Models should be pluralized, for example, `customers`, `orders`, `products`. - πŸ”‘ Each model should have a primary key. - πŸ”‘ The primary key of a model should be named `_id`, for example, `account_id`. This makes it easier to know what `id` is being referenced in downstream joined models. +- Use underscores for naming dbt models; avoid dots. + - βœ… `models_without_dots` + - ❌ `models.with.dots` + - Underscores are more compatible and clear across platforms. Dots can cause quoting and case sensitivity complexities, especially in systems like Snowflake. Databases may also misinterpret dots as schema or database name separators. Read the [discussion](https://github.com/dbt-labs/dbt-core/issues/3246) for more details. - πŸ”‘ Keys should be string data types. - πŸ”‘ Consistency is key! Use the same field names across models where possible. For example, a key to the `customers` table should be named `customer_id` rather than `user_id` or 'id'. - ❌ Do not use abbreviations or aliases. Emphasize readability over brevity. For example, do not use `cust` for `customer` or `o` for `orders`. diff --git a/website/docs/docs/build/models.md b/website/docs/docs/build/models.md index 1cf2fbafeda..fa2a002a3ef 100644 --- a/website/docs/docs/build/models.md +++ b/website/docs/docs/build/models.md @@ -6,8 +6,6 @@ pagination_next: "docs/build/sql-models" pagination_prev: null --- -## Overview - dbt Core and Cloud are composed of different moving parts working harmoniously. All of them are important to what dbt does β€” transforming dataβ€”the 'T' in ELT. When you execute `dbt run`, you are running a model that will transform your data without that data ever leaving your warehouse. Models are where your developers spend most of their time within a dbt environment. Models are primarily written as a `select` statement and saved as a `.sql` file. While the definition is straightforward, the complexity of the execution will vary from environment to environment. Models will be written and rewritten as needs evolve and your organization finds new ways to maximize efficiency. diff --git a/website/docs/docs/build/sql-models.md b/website/docs/docs/build/sql-models.md index a0dd174278b..b2d4c26462e 100644 --- a/website/docs/docs/build/sql-models.md +++ b/website/docs/docs/build/sql-models.md @@ -29,7 +29,10 @@ dbt's Python capabilities are an extension of its capabilities with SQL models. A SQL model is a `select` statement. Models are defined in `.sql` files (typically in your `models` directory): - Each `.sql` file contains one model / `select` statement - The model name is inherited from the filename. -- Models can be nested in subdirectories within the `models` directory +- Use underscores for model names for better compatibility and clarity (such as `model_without_dots`); avoid using dots to prevent potential issues with database interpretations (`model.with.dots`). +- Models can be nested in subdirectories within the `models` directory. + +Refer to [How we style our dbt models](/best-practices/how-we-style/1-how-we-style-our-dbt-models) for details on how we recommend you name your models. When you execute the [`dbt run` command](/reference/commands/run), dbt will build this model by wrapping it in a `create view as` or `create table as` statement. diff --git a/website/docs/docs/cloud/dbt-cloud-ide/develop-in-the-cloud.md b/website/docs/docs/cloud/dbt-cloud-ide/develop-in-the-cloud.md index 57146ec513a..600ac5c3bfc 100644 --- a/website/docs/docs/cloud/dbt-cloud-ide/develop-in-the-cloud.md +++ b/website/docs/docs/cloud/dbt-cloud-ide/develop-in-the-cloud.md @@ -133,38 +133,32 @@ The dbt Cloud IDE makes it possible to [build and view](/docs/collaborate/build- ## Related docs -- [dbt Cloud features](/docs/cloud/about-cloud/dbt-cloud-features) -- [IDE user interface](/docs/cloud/dbt-cloud-ide/ide-user-interface) +- [How we style our dbt projects](/best-practices/how-we-style/0-how-we-style-our-dbt-projects) +- [User interface](/docs/cloud/dbt-cloud-ide/ide-user-interface) - [Version control basics](/docs/collaborate/git/version-control-basics) - [dbt Commands](/reference/dbt-commands) -- [dbt Cloud IDE release notes](/tags/ide) ## Related questions -
- -
- Is there a cost to using the Cloud IDE? -
-
Not at all! You can use dbt Cloud when you sign up for the Free Developer plan, which comes with one developer seat. If you’d like to access more features or have more developer seats, you can upgrade your account to the Team or Enterprise plan. See dbt pricing plans for more details.
-
-
-
- Can I be a contributor to dbt Cloud? -
-
Anyone can contribute to the dbt project. And whether it's a dbt package, a plugin, dbt-core, or this documentation site, contributing to the open-source code that supports the dbt ecosystem is a great way to level yourself up as a developer, and give back to the community. See Contributing for details on what to expect when contributing to the dbt open source software (OSS).
-
-
-
- What is the difference between developing on the dbt Cloud IDE, the dbt Cloud CLI, and dbt Core? -
-
You can develop dbt using the web-based IDE in dbt Cloud or on the command line interface using the dbt Cloud CLI or open-source dbt Core, all of which enable you to execute dbt commands. The key distinction between the dbt Cloud CLI and dbt Core is the dbt Cloud CLI is tailored for dbt Cloud's infrastructure and integrates with all its features.

- — - dbt Cloud IDE: dbt Cloud is a web-based application that allows you to develop dbt projects with the IDE, includes a purpose-built scheduler, and provides an easier way to share your dbt documentation with your team. The IDE is a faster and more reliable way to deploy your dbt models and provides a real-time editing and execution environment for your dbt project.

- — - dbt Cloud CLI: The dbt Cloud CLI allows you to run dbt commands against your dbt Cloud development environment from your local command line or code editor. It supports cross-project ref, speedier, lower-cost builds, automatic deferral of build artifacts, and more.

- — - dbt Core: dbt Core is an open-sourced software that’s freely available. You can build your dbt project in a code editor, and run dbt commands from the command line. -
-
-
+ + + +Not at all! You can use dbt Cloud when you sign up for the Free Developer plan, which comes with one developer seat. If you’d like to access more features or have more developer seats, you can upgrade your account to the Team or Enterprise plan.
+ +Refer to dbt pricing plans for more details. + + + +Anyone can contribute to the dbt project. And whether it's a dbt package, a plugin, dbt-core, or this documentation site, contributing to the open-source code that supports the dbt ecosystem is a great way to level yourself up as a developer, and give back to the community. See Contributing for details on what to expect when contributing to the dbt open source software (OSS). + + + +You can develop dbt using the web-based IDE in dbt Cloud or on the command line interface using the dbt Cloud CLI or open-source dbt Core, all of which enable you to execute dbt commands. The key distinction between the dbt Cloud CLI and dbt Core is the dbt Cloud CLI is tailored for dbt Cloud's infrastructure and integrates with all its features: + +- dbt Cloud IDE: dbt Cloud is a web-based application that allows you to develop dbt projects with the IDE, includes a purpose-built scheduler, and provides an easier way to share your dbt documentation with your team. The IDE is a faster and more reliable way to deploy your dbt models and provides a real-time editing and execution environment for your dbt project. + +- dbt Cloud CLI: The dbt Cloud CLI allows you to run dbt commands against your dbt Cloud development environment from your local command line or code editor. It supports cross-project ref, speedier, lower-cost builds, automatic deferral of build artifacts, and more. + +- dbt Core: dbt Core is an open-sourced software that’s freely available. You can build your dbt project in a code editor, and run dbt commands from the command line + + From dfe4fba5c4ebdeaffc69159ebe638ed4cc0cc974 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Mon, 15 Jan 2024 11:36:11 +0000 Subject: [PATCH 2/8] add context --- .../how-we-style/1-how-we-style-our-dbt-models.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md b/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md index a524eaded0c..264ea44ccb2 100644 --- a/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md +++ b/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md @@ -11,7 +11,7 @@ id: 1-how-we-style-our-dbt-models - Use underscores for naming dbt models; avoid dots. - βœ… `models_without_dots` - ❌ `models.with.dots` - - Underscores are more compatible and clear across platforms. Dots can cause quoting and case sensitivity complexities, especially in systems like Snowflake. Databases may also misinterpret dots as schema or database name separators. Read the [discussion](https://github.com/dbt-labs/dbt-core/issues/3246) for more details. + - Underscores are more compatible and clear across platforms. Dots can cause quoting and case sensitivity complexities, especially in systems like Snowflake. Databases may also misinterpret dots as schema or database name separators. dbt uses dots in its `unique_id` generation to differentiate resource types, package names, and resource names, which is another reason to avoid dots in model name. Read the [discussion](https://github.com/dbt-labs/dbt-core/issues/3246) for more details. - πŸ”‘ Keys should be string data types. - πŸ”‘ Consistency is key! Use the same field names across models where possible. For example, a key to the `customers` table should be named `customer_id` rather than `user_id` or 'id'. - ❌ Do not use abbreviations or aliases. Emphasize readability over brevity. For example, do not use `cust` for `customer` or `o` for `orders`. From 7eada1cb024f5b53ca264538b2938840898de948 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Mon, 15 Jan 2024 11:36:48 +0000 Subject: [PATCH 3/8] add link to discourse --- .../how-we-style/1-how-we-style-our-dbt-models.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md b/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md index 264ea44ccb2..08fc2913eb9 100644 --- a/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md +++ b/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md @@ -11,7 +11,7 @@ id: 1-how-we-style-our-dbt-models - Use underscores for naming dbt models; avoid dots. - βœ… `models_without_dots` - ❌ `models.with.dots` - - Underscores are more compatible and clear across platforms. Dots can cause quoting and case sensitivity complexities, especially in systems like Snowflake. Databases may also misinterpret dots as schema or database name separators. dbt uses dots in its `unique_id` generation to differentiate resource types, package names, and resource names, which is another reason to avoid dots in model name. Read the [discussion](https://github.com/dbt-labs/dbt-core/issues/3246) for more details. + - Underscores are more compatible and clear across platforms. Dots can cause quoting and case sensitivity complexities, especially in systems like Snowflake. Databases may also misinterpret dots as schema or database name separators. [dbt uses dots](https://discourse.getdbt.com/t/why-cant-model-names-contain-dots/422) in its `unique_id` generation to differentiate resource types, package names, and resource names, which is another reason to avoid dots in model name. Read the [discussion](https://github.com/dbt-labs/dbt-core/issues/3246) for more details. - πŸ”‘ Keys should be string data types. - πŸ”‘ Consistency is key! Use the same field names across models where possible. For example, a key to the `customers` table should be named `customer_id` rather than `user_id` or 'id'. - ❌ Do not use abbreviations or aliases. Emphasize readability over brevity. For example, do not use `cust` for `customer` or `o` for `orders`. From 9556d3a189c1d897c0b4f06f6a7bec4bc27b19d5 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 17 Jan 2024 17:15:02 +0000 Subject: [PATCH 4/8] Update website/docs/docs/build/sql-models.md --- website/docs/docs/build/sql-models.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/sql-models.md b/website/docs/docs/build/sql-models.md index b2d4c26462e..88e8442efc9 100644 --- a/website/docs/docs/build/sql-models.md +++ b/website/docs/docs/build/sql-models.md @@ -29,7 +29,7 @@ dbt's Python capabilities are an extension of its capabilities with SQL models. A SQL model is a `select` statement. Models are defined in `.sql` files (typically in your `models` directory): - Each `.sql` file contains one model / `select` statement - The model name is inherited from the filename. -- Use underscores for model names for better compatibility and clarity (such as `model_without_dots`); avoid using dots to prevent potential issues with database interpretations (`model.with.dots`). +- Use underscores for model names for better compatibility and clarity (such as `model_without_dots`); avoid using dots to prevent issues with the dbt Cloud parser and database interpretations (`model.with.dots`). - Models can be nested in subdirectories within the `models` directory. Refer to [How we style our dbt models](/best-practices/how-we-style/1-how-we-style-our-dbt-models) for details on how we recommend you name your models. From 67d6aed6c43803e6134c193bc804e0c63c553378 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 17 Jan 2024 17:15:26 +0000 Subject: [PATCH 5/8] Update website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md --- .../how-we-style/1-how-we-style-our-dbt-models.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md b/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md index 08fc2913eb9..2e4b6c251dc 100644 --- a/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md +++ b/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md @@ -11,7 +11,8 @@ id: 1-how-we-style-our-dbt-models - Use underscores for naming dbt models; avoid dots. - βœ… `models_without_dots` - ❌ `models.with.dots` - - Underscores are more compatible and clear across platforms. Dots can cause quoting and case sensitivity complexities, especially in systems like Snowflake. Databases may also misinterpret dots as schema or database name separators. [dbt uses dots](https://discourse.getdbt.com/t/why-cant-model-names-contain-dots/422) in its `unique_id` generation to differentiate resource types, package names, and resource names, which is another reason to avoid dots in model name. Read the [discussion](https://github.com/dbt-labs/dbt-core/issues/3246) for more details. + - Use underscores because they’re more compatible and clear across platforms. Dots can cause + dbt Cloud parser, quoting, and case sensitivity issues, especially in systems like Snowflake. Databases may also misinterpret dots as schema or database name separators. [dbt uses dots](https://discourse.getdbt.com/t/why-cant-model-names-contain-dots/422) in its `unique_id` generation to differentiate resource types, package names, and resource names, which is another reason to avoid dots in model name. Read the [discussion](https://github.com/dbt-labs/dbt-core/issues/3246) for more details. - πŸ”‘ Keys should be string data types. - πŸ”‘ Consistency is key! Use the same field names across models where possible. For example, a key to the `customers` table should be named `customer_id` rather than `user_id` or 'id'. - ❌ Do not use abbreviations or aliases. Emphasize readability over brevity. For example, do not use `cust` for `customer` or `o` for `orders`. From 3f14d240f95ab07e0e6a6b335059c192ea9c81a4 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Tue, 23 Jan 2024 12:34:25 +0000 Subject: [PATCH 6/8] Update website/docs/docs/build/sql-models.md Co-authored-by: Joel Labes --- website/docs/docs/build/sql-models.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/sql-models.md b/website/docs/docs/build/sql-models.md index 88e8442efc9..d0dc8becdcb 100644 --- a/website/docs/docs/build/sql-models.md +++ b/website/docs/docs/build/sql-models.md @@ -29,7 +29,7 @@ dbt's Python capabilities are an extension of its capabilities with SQL models. A SQL model is a `select` statement. Models are defined in `.sql` files (typically in your `models` directory): - Each `.sql` file contains one model / `select` statement - The model name is inherited from the filename. -- Use underscores for model names for better compatibility and clarity (such as `model_without_dots`); avoid using dots to prevent issues with the dbt Cloud parser and database interpretations (`model.with.dots`). +- We strongly recommend using underscores for model names, not dots. For example, use `models/my_model.sql` instead of `models/my.model.sql`. - Models can be nested in subdirectories within the `models` directory. Refer to [How we style our dbt models](/best-practices/how-we-style/1-how-we-style-our-dbt-models) for details on how we recommend you name your models. From c8bdb168c907f15034c3acfd558dc582c73f184a Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Tue, 23 Jan 2024 12:39:31 +0000 Subject: [PATCH 7/8] Update website/docs/docs/cloud/dbt-cloud-ide/develop-in-the-cloud.md Co-authored-by: Joel Labes --- website/docs/docs/cloud/dbt-cloud-ide/develop-in-the-cloud.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/cloud/dbt-cloud-ide/develop-in-the-cloud.md b/website/docs/docs/cloud/dbt-cloud-ide/develop-in-the-cloud.md index 600ac5c3bfc..0d87a790042 100644 --- a/website/docs/docs/cloud/dbt-cloud-ide/develop-in-the-cloud.md +++ b/website/docs/docs/cloud/dbt-cloud-ide/develop-in-the-cloud.md @@ -149,7 +149,7 @@ Refer to dbt pricing plans for mor -Anyone can contribute to the dbt project. And whether it's a dbt package, a plugin, dbt-core, or this documentation site, contributing to the open-source code that supports the dbt ecosystem is a great way to level yourself up as a developer, and give back to the community. See Contributing for details on what to expect when contributing to the dbt open source software (OSS). +As a proprietary product, dbt Cloud's source code isn't available for community contributions. If you want to build something in the dbt ecosystem, we encourage you to review [this article](/community/contributing/contributing-coding) about contributing to a dbt package, a plugin, dbt-core, or this documentation site. Participation in open-source is a great way to level yourself up as a developer, and give back to the community. From ddef94272393e287d73af218b2a3a432371503d3 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Tue, 23 Jan 2024 19:21:04 +0000 Subject: [PATCH 8/8] Update 1-how-we-style-our-dbt-models.md Co-authored-by: Joel Labes --- .../how-we-style/1-how-we-style-our-dbt-models.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md b/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md index 2e4b6c251dc..bf8924807a0 100644 --- a/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md +++ b/website/docs/best-practices/how-we-style/1-how-we-style-our-dbt-models.md @@ -11,8 +11,7 @@ id: 1-how-we-style-our-dbt-models - Use underscores for naming dbt models; avoid dots. - βœ… `models_without_dots` - ❌ `models.with.dots` - - Use underscores because they’re more compatible and clear across platforms. Dots can cause - dbt Cloud parser, quoting, and case sensitivity issues, especially in systems like Snowflake. Databases may also misinterpret dots as schema or database name separators. [dbt uses dots](https://discourse.getdbt.com/t/why-cant-model-names-contain-dots/422) in its `unique_id` generation to differentiate resource types, package names, and resource names, which is another reason to avoid dots in model name. Read the [discussion](https://github.com/dbt-labs/dbt-core/issues/3246) for more details. + - Most data platforms use dots to separate `database.schema.object`, so using underscores instead of dots reduces your need for [quoting](/reference/resource-properties/quoting) as well as the risk of issues in certain parts of dbt Cloud. For more background, refer to [this GitHub issue](https://github.com/dbt-labs/dbt-core/issues/3246). - πŸ”‘ Keys should be string data types. - πŸ”‘ Consistency is key! Use the same field names across models where possible. For example, a key to the `customers` table should be named `customer_id` rather than `user_id` or 'id'. - ❌ Do not use abbreviations or aliases. Emphasize readability over brevity. For example, do not use `cust` for `customer` or `o` for `orders`.