Merge branch 'mwong-severity' of https://github.com/dbt-labs/docs.get…

…dbt.com into mwong-severity

website/blog/2023-11-14-specify-prod-environment.md

@@ -0,0 +1,73 @@
+---
+
+title: Why you should specify a production environment in dbt Cloud
+description: "The bottom line: You should split your Environments in dbt Cloud based on their purposes (e.g. Production and Staging/CI) and mark one environment as Production. This will improve your CI experience and enable you to use dbt Explorer."
+slug: specify-prod-environment
+
+authors: [joel_labes]
+
+tags: [dbt Cloud]
+hide_table_of_contents: false
+
+date: 2023-11-14
+is_featured: false
+
+---
+
+:::tip The Bottom Line:
+You should [split your Jobs](#how) across Environments in dbt Cloud based on their purposes (e.g. Production and Staging/CI) and set one environment as Production. This will improve your CI experience and enable you to use dbt Explorer.
+:::
+
+[Environmental segmentation](/docs/environments-in-dbt) has always been an important part of the analytics engineering workflow:
+
+- When developing new models you can [process a smaller subset of your data](/reference/dbt-jinja-functions/target#use-targetname-to-limit-data-in-dev) by using `target.name` or an environment variable.
+- By building your production-grade models into [a different schema and database](https://docs.getdbt.com/docs/build/custom-schemas#managing-environments), you can experiment in peace without being worried that your changes will accidentally impact downstream users.
+- Using dedicated credentials for production runs, instead of an analytics engineer's individual dev credentials, ensures that things don't break when that long-tenured employee finally hangs up their IDE.
+
+Historically, dbt Cloud required a separate environment for _Development_, but was otherwise unopinionated in how you configured your account. This mostly just worked – as long as you didn't have anything more complex than a CI job mixed in with a couple of production jobs – because important constructs like deferral in CI and documentation were only ever tied to a single job.
+
+But as companies' dbt deployments have grown more complex, it doesn't make sense to assume that a single job is enough anymore. We need to exchange a job-oriented strategy for a more mature and scalable environment-centric view of the world. To support this, a recent change in dbt Cloud enables project administrators to [mark one of their environments as the Production environment](/docs/deploy/deploy-environments#set-as-production-environment-beta), just as has long been possible for the Development environment.
+
+Explicitly separating your Production workloads lets dbt Cloud be smarter with the metadata it creates, and is particularly important for two new features: dbt Explorer and the revised CI workflows.
+
+<!-- truncate -->
+
+## Make sure dbt Explorer always has the freshest information available
+
+**The old way**: Your dbt docs site was based on a single job's run.
+
+**The new way**: dbt Explorer uses metadata from across every invocation in a defined Production environment to build the richest and most up-to-date understanding of your project.
+
+Because dbt docs could only be updated by a single predetermined job, users who needed their documentation to immediately reflect changes deployed throughout the day (regardless of which job executed them) would find themselves forced to run a dedicated job which did nothing other than run `dbt docs generate` on a regular schedule.
+
+The Discovery API that powers dbt Explorer ingests all metadata generated by any dbt invocation, which means that it can always be up to date with the applied state of your project. However it doesn't make sense for dbt Explorer to show docs based on a PR that hasn't been merged yet.
+
+To avoid this conflation, you need to mark an environment as the Production environment. All runs completed in _that_ environment will contribute to dbt Explorer's, while others will be excluded. (Future versions of Explorer will support environment selection, so that you can preview your documentation changes as well.)
+
+## Run Slimmer CI than ever with environment-level deferral
+
+**The old way**: [Slim CI](/guides/set-up-ci?step=2) deferred to a single job, and would only detect changes as of that job's last build time.
+
+**The new way**: Changes are detected regardless of the job they were deployed in, removing false positives and overbuilding of models in CI.
+
+Just like dbt docs, relying on a single job to define your state for comparison purposes leads to a choice between unnecessarily rebuilding models which were deployed by another job, or creating a dedicated job that runs `dbt compile` on repeat to keep on top of all changes.
+
+By using the environment as the arbiter of state, any time a change is made to your Production deployment it will immediately be taken into consideration by subsequent Slim CI runs.
+
+## The easiest way to break apart your jobs {#how}
+
+<Lightbox src="/img/blog/2023-11-06-differentiate-prod-and-staging-environments/data-landscape.png" alt="A chart showing the interplay of Data Warehouse, git repo and dbt Cloud project across Dev, CI and Prod environments." title="Your organization's data landscape should separate Dev, CI and Prod environments. To achieve this, configure your data warehouse, git repo and dbt Cloud account as shown above." width="100%"/>
+
+For most projects, changing from a job-centric to environment-centric approach to metadata is straightforward and immediately pays dividends as described above. Assuming that your Staging/CI and Production jobs are currently intermingled, you can extricate them as follows:
+
+1. Create a new dbt Cloud environment called Staging
+2. For each job that belongs to the Staging environment, edit the job and update its environment
+3. Tick the ["Mark as Production environment" box](/docs/deploy/deploy-environments#set-as-production-environment-beta) in your original environment's settings
+
+## Conclusion
+
+Until very recently, I only thought of Environments in dbt Cloud as a way to use different authentication credentials in different contexts. And until very recently, I was mostly right.
+
+Not anymore. The metadata dbt creates is critical for effective data teams – whether you're concerned about cost savings, discoverability, increased development speed or reliable results across your organization – but is only fully effective if it's segmented by the environment that created it.
+
+Take a few minutes to clean up your environments - it'll make all the difference.

website/blog/categories.yml

@@ -19,3 +19,5 @@
   display_title: SQL magic
   description: Stories of dbt developers making SQL sing across warehouses.
   is_featured: true
+- name: dbt Cloud
+  description: Using dbt Cloud to build for scale

website/docs/docs/build/metrics.md

@@ -7,13 +7,10 @@ keywords:
 tags: [Metrics]
 ---
 
-:::caution Upgrade to access MetricFlow and the new dbt Semantic Layer
+import DeprecationNotice from '/snippets/_sl-deprecation-notice.md';
 
-The dbt_metrics package has been deprecated and replaced with [MetricFlow](/docs/build/about-metricflow?version=1.6). If you're using the dbt_metrics package or the legacy Semantic Layer (available on v1.5 or lower), we **highly** recommend [upgrading your dbt version](/docs/dbt-versions/upgrade-core-in-cloud) to dbt v1.6 or higher to access MetricFlow and the new [dbt Semantic Layer](/docs/use-dbt-semantic-layer/dbt-sl?version=1.6).
+<DeprecationNotice />
 
-To migrate to the new Semantic Layer, refer to the dedicated [migration guide](/guides/sl-migration) for more info.
-
-:::
 
 <VersionBlock firstVersion="1.6">
 
@@ -38,11 +35,7 @@ A metric is an aggregation over a <Term id="table" /> that supports zero or more
 - active users
 - monthly recurring revenue (mrr)
 
-In v1.0, dbt supports metric definitions as a new node type. Like [exposures](exposures), metrics appear as nodes in the directed acyclic graph (DAG) and can be expressed in YAML files. Defining metrics in dbt projects encodes crucial business logic in tested, version-controlled code. Further, you can expose these metrics definitions to downstream tooling, which drives consistency and precision in metric reporting.
-
-Review the video below to learn more about metrics, why they're important, and how to get started:
-
-<LoomVideo id="b120ca9d042d46abad1d873a676bf20a" />    
+In v1.0, dbt supports metric definitions as a new node type. Like [exposures](exposures), metrics appear as nodes in the directed acyclic graph (DAG) and can be expressed in YAML files. Defining metrics in dbt projects encodes crucial business logic in tested, version-controlled code. Further, you can expose these metrics definitions to downstream tooling, which drives consistency and precision in metric reporting. 
 
 ### Benefits of defining metrics
 

website/docs/docs/cloud/about-cloud-develop-defer.md

@@ -7,18 +7,15 @@ pagination_next: "docs/cloud/cloud-cli-installation"
 ---
 
 
-[Defer](/reference/node-selection/defer) is a powerful feature that allows developers to only build and run and test models they've edited without having to first run and build all the models that come before them (upstream parents). This is powered by using a production manifest for comparison, and dbt will resolve the `{{ ref() }}` function with upstream production artifacts. 
+[Defer](/reference/node-selection/defer) is a powerful feature that allows developers to only build and run and test models they've edited without having to first run and build all the models that come before them (upstream parents). dbt powers this by using a production manifest for comparison, and resolves the `{{ ref() }}` function with upstream production artifacts. 
 
-By default, dbt follows these rules:
-
-- Defers to the production environment when there's no development schema.
-- If a development schema exists, dbt will prioritize those changes, which minimizes development time and avoids unnecessary model builds.
+Both the dbt Cloud IDE and the dbt Cloud CLI enable users to natively defer to production metadata directly in their development workflows. 
 
-Both the dbt Cloud IDE and the dbt Cloud CLI allow users to natively defer to production metadata directly in their development workflows.
+By default, dbt follows these rules:
 
-For specific scenarios:
-- Use [`--favor-state`](/reference/node-selection/defer#favor-state) to always use production artifacts to resolve the ref.
-- If facing issues with outdated tables in the development schema, `--favor-state` is an alternative to defer.
+- dbt uses the production locations of parent models to resolve `{{ ref() }}` functions, based on metadata from the production environment.
+- If a development version of a deferred model exists, dbt preferentially uses the development database location when resolving the reference.
+- Passing the [`--favor-state`](/reference/node-selection/defer#favor-state) flag overrides the default behavior and _always_ resolve refs using production metadata, regardless of the presence of a development relation.
 
 For a clean slate, it's a good practice to drop the development schema at the start and end of your development cycle.
 

website/docs/docs/cloud/about-cloud/regions-ip-addresses.md

@@ -12,7 +12,7 @@ dbt Cloud is [hosted](/docs/cloud/about-cloud/architecture) in multiple regions
 | Region | Location | Access URL | IP addresses | Developer plan | Team plan | Enterprise plan |
 |--------|----------|------------|--------------|----------------|-----------|-----------------|
 | North America multi-tenant [^1] | AWS us-east-1 (N. Virginia) | cloud.getdbt.com | 52.45.144.63 <br /> 54.81.134.249 <br />52.22.161.231 | ✅ | ✅ | ✅ |
-| North America Cell 1 [^1]       | AWS us-east-1 (N.Virginia) | {account prefix}.us1.dbt.com | [Located in Account Settings](#locating-your-dbt-cloud-ip-addresses) | ❌ | ❌ | ❌ |
+| North America Cell 1 [^1]       | AWS us-east-1 (N.Virginia) | {account prefix}.us1.dbt.com | [Located in Account Settings](#locating-your-dbt-cloud-ip-addresses) | ❌ | ❌ | ✅ |
 | EMEA [^1] | AWS eu-central-1	(Frankfurt) | emea.dbt.com | 3.123.45.39 <br /> 3.126.140.248 <br /> 3.72.153.148 | ❌ | ❌ | ✅ |
 | APAC  [^1] | 	AWS ap-southeast-2  (Sydney)| au.dbt.com | 52.65.89.235 <br /> 3.106.40.33 <br /> 13.239.155.206 <br />| ❌ | ❌ | ✅ |
 | Virtual Private dbt or Single tenant | Customized |  Customized | Ask [Support](/community/resources/getting-help#dbt-cloud-support) for your IPs | ❌ | ❌ | ✅ |

website/docs/docs/dbt-cloud-apis/sl-graphql.md

@@ -282,7 +282,7 @@ mutation {
   createQuery(
     environmentId: BigInt!
     metrics: [{name: "order_total"}]
-    groupBy: [{name: "metric_time", grain: "month"}] 
+    groupBy: [{name: "metric_time", grain: MONTH}] 
   ) {
     queryId
   }
@@ -298,7 +298,7 @@ mutation {
   createQuery(
     environmentId: BigInt!
     metrics: [{name: "food_order_amount"}, {name: "order_gross_profit"}]
-    groupBy: [{name: "metric_time, grain: "month"}, {name: "customer__customer_type"}]
+    groupBy: [{name: "metric_time, grain: MONTH}, {name: "customer__customer_type"}]
   ) {
     queryId
   }
@@ -320,7 +320,7 @@ mutation {
   createQuery(
     environmentId: BigInt!
     metrics:[{name: "order_total"}]
-    groupBy:[{name: "customer__customer_type"}, {name: "metric_time", grain: "month"}]
+    groupBy:[{name: "customer__customer_type"}, {name: "metric_time", grain: MONTH}]
     where:[{sql: "{{ Dimension('customer__customer_type') }} = 'new'"}, {sql:"{{ Dimension('metric_time').grain('month') }} > '2022-10-01'"}]
     ) {
      queryId
@@ -335,8 +335,8 @@ mutation {
   createQuery(
     environmentId: BigInt!
     metrics: [{name: "order_total"}]
-    groupBy: [{name: "metric_time", grain: "month"}] 
-    orderBy: [{metric: {name: "order_total"}}, {groupBy: {name: "metric_time", grain: "month"}, descending:true}]
+    groupBy: [{name: "metric_time", grain: MONTH}] 
+    orderBy: [{metric: {name: "order_total"}}, {groupBy: {name: "metric_time", grain: MONTH}, descending:true}]
   ) {
     queryId
   }
@@ -351,7 +351,7 @@ mutation {
   createQuery(
     environmentId: BigInt!
     metrics: [{name:"food_order_amount"}, {name: "order_gross_profit"}]
-    groupBy: [{name:"metric_time, grain: "month"}, {name: "customer__customer_type"}]
+    groupBy: [{name:"metric_time, grain: MONTH}, {name: "customer__customer_type"}]
     limit: 10 
   ) {
     queryId
@@ -368,7 +368,7 @@ mutation {
   compileSql(
     environmentId: BigInt!
     metrics: [{name:"food_order_amount"} {name:"order_gross_profit"}]
-    groupBy: [{name:"metric_time, grain:"month"}, {name:"customer__customer_type"}]
+    groupBy: [{name:"metric_time, grain: MONTH}, {name:"customer__customer_type"}]
   ) {
     sql
   }

website/docs/docs/dbt-support.md

@@ -7,7 +7,7 @@ pagination_prev: null
 
 Support for dbt is available to all users through the following channels:
 
-- Dedicated dbt Support team (For dbt Cloud users).
+- Dedicated dbt Support team (dbt Cloud users).
 - [The Community Forum](https://discourse.getdbt.com/).
 - [dbt Community slack](https://www.getdbt.com/community/join-the-community/).
 
@@ -39,14 +39,14 @@ Types of dbt Cloud-related questions our Support team can assist you with, regar
     - set up a dbt Cloud project?
     - set up a private package in dbt Cloud?
     - configure custom branches on git repos?
-    - link dbt to a new github account?
+    - link dbt to a new GitHub account?
 - **Help! I can't...**
     - log in.
     - access logs.
     - update user groups.
 - **I need help understanding...**
     - why this run failed.
-    - why I am getting this error message in dbt Cloud.
+    - why I am getting this error message in dbt Cloud?
     - why my CI jobs are not kicking off as expected.
 
 
@@ -77,7 +77,7 @@ For help writing SQL, reviewing the overall performance of your project, or want
 
 ### Severity level
 
-Enterprise support tickets are assigned a severity level based on the impact of the issue to your business. The severity level determines the priority level of support you will receive. For specific ticket response times, Support does not have access to an Enterprise account's service level agreement (SLA). Please contact your legal team for a copy of your contract.
+Enterprise support tickets are assigned a severity level based on the impact of the issue on your business. The severity level determines the priority level of support you will receive. For specific ticket response times, Support does not have access to an Enterprise account's service level agreement (SLA). Please contact your legal team for a copy of your contract.
 
 
 | Severity Level | Description |

website/docs/docs/use-dbt-semantic-layer/avail-sl-integrations.md

@@ -38,9 +38,9 @@ import AvailIntegrations from '/snippets/_sl-partner-links.md';
 
 <VersionBlock lastVersion="1.5">
 
-import LegacyInfo from '/snippets/_legacy-sl-callout.md';
+import DeprecationNotice from '/snippets/_sl-deprecation-notice.md';
 
-<LegacyInfo />
+<DeprecationNotice />
 
 A wide variety of data applications across the modern data stack natively integrate with the dbt Semantic Layer and dbt metrics &mdash; from Business Intelligence tools to notebooks, data catalogs, and more.
 

website/docs/docs/use-dbt-semantic-layer/dbt-sl.md

@@ -67,9 +67,9 @@ plan="dbt Cloud Team or Enterprise"
 
 <VersionBlock lastVersion="1.5">
 
-import LegacyInfo from '/snippets/_legacy-sl-callout.md';
+import DeprecationNotice from '/snippets/_sl-deprecation-notice.md';
 
-<LegacyInfo />
+<DeprecationNotice />
 
 The dbt Semantic Layer allows your data teams to centrally define essential business metrics like `revenue`, `customer`, and `churn` in the modeling layer (your dbt project) for consistent self-service within downstream data tools like BI and metadata management solutions. The dbt Semantic Layer provides the flexibility to define metrics on top of your existing models and then query those metrics and models in your analysis tools of choice.
 

website/docs/docs/use-dbt-semantic-layer/gsheets.md

@@ -13,10 +13,10 @@ The dbt Semantic Layer offers a seamless integration with Google Sheets through
 
 ## Prerequisites
 
-1. You have a Google account with access to Google Sheets.
-2. You can install Google add-ons.
-3. You have [set up the dbt Semantic Layer](/docs/use-dbt-semantic-layer/setup-sl).
-4. You have a dbt Cloud Environment ID and a [service token](/docs/dbt-cloud-apis/service-tokens) to authenticate with from a dbt Cloud account.
+- You have [configured the dbt Semantic Layer](/docs/use-dbt-semantic-layer/setup-sl) and are using dbt v1.6 or higher.
+- You have a Google account with access to Google Sheets.
+- You can install Google add-ons.
+- You have a dbt Cloud Environment ID and a [service token](/docs/dbt-cloud-apis/service-tokens) to authenticate with from a dbt Cloud account.
 
 ## Installing the add-on 
 

website/docs/docs/use-dbt-semantic-layer/quickstart-sl.md

@@ -114,9 +114,9 @@ User data passes through the Semantic Layer on its way back from the warehouse.
 
 <VersionBlock lastVersion="1.5">
 
-import LegacyInfo from '/snippets/_legacy-sl-callout.md';
+import DeprecationNotice from '/snippets/_sl-deprecation-notice.md';
 
-<LegacyInfo />
+<DeprecationNotice />
 
 To try out the features of the dbt Semantic Layer, you first need to have a dbt project set up. This quickstart guide will lay out the following steps, and recommends a workflow that demonstrates some of its essential features:
 

website/docs/docs/use-dbt-semantic-layer/setup-sl.md

@@ -39,9 +39,9 @@ import SlSetUp from '/snippets/_new-sl-setup.md';
 
 <VersionBlock lastVersion="1.5">
 
-import LegacyInfo from '/snippets/_legacy-sl-callout.md';
+import DeprecationNotice from '/snippets/_sl-deprecation-notice.md';
 
-<LegacyInfo />
+<DeprecationNotice />
 
 With the dbt Semantic Layer, you can define business metrics, reduce code duplication and inconsistency, create self-service in downstream tools, and more. Configure the dbt Semantic Layer in dbt Cloud to connect with your integrated partner tool. 
 

website/docs/docs/use-dbt-semantic-layer/sl-architecture.md

@@ -56,6 +56,10 @@ The dbt Semantic Layer is proprietary; however, some components of the dbt Seman
 
 <VersionBlock lastVersion="1.5">
 
+import DeprecationNotice from '/snippets/_sl-deprecation-notice.md';
+
+<DeprecationNotice />
+
 ## Product architecture 
 
 The dbt Semantic Layer product architecture includes four primary components: