Merge branch 'current' into dbeatty/nota-bene

website/docs/docs/build/incremental-models.md

@@ -174,7 +174,7 @@ dbt's incremental materialization works differently on different databases. Wher
 
 On warehouses that do not support `merge` statements, a merge is implemented by first using a `delete` statement to delete records in the target table that are to be updated, and then an `insert` statement.
 
-Transaction management is used to ensure this is executed as a single unit of work.
+Transaction management, a process used in certain data platforms, ensures that a set of actions is treated as a single unit of work (or task). If any part of the unit of work fails, dbt will roll back open transactions and restore the database to a good state.
 
 ## What if the columns of my incremental model change?
 

website/docs/docs/build/projects.md

@@ -19,7 +19,7 @@ At a minimum, all a project needs is the `dbt_project.yml` project configuration
 | [docs](/docs/collaborate/documentation) | Docs for your project that you can build. |
 | [sources](/docs/build/sources) | A way to name and describe the data loaded into your warehouse by your Extract and Load tools. |
 | [exposures](/docs/build/exposures) | A way to define and describe a downstream use of your project. |
-| [metrics](/docs/build/metrics) | A way for you to define metrics for your project. |
+| [metrics](/docs/build/build-metrics-intro) | A way for you to define metrics for your project. |
 | [groups](/docs/build/groups) | Groups enable collaborative node organization in restricted collections. |
 | [analysis](/docs/build/analyses) | A way to organize analytical SQL queries in your project such as the general ledger from your QuickBooks. |
 

website/docs/docs/cloud/cloud-cli-installation.md

@@ -258,16 +258,17 @@ To use these extensions, such as dbt-power-user, with the dbt Cloud CLI, you can
 
 ## FAQs
 
-<details>
+<detailsToggle alt_header="What's the difference between the dbt Cloud CLI and dbt Core?">
 
-<summary>What's the difference between the dbt Cloud CLI and dbt Core?</summary>
-The dbt Cloud CLI and <a href="https://github.com/dbt-labs/dbt-core">dbt Core</a>, an open-source project, are both command line tools that enable you to run dbt commands. The key distinction is the dbt Cloud CLI is tailored for dbt Cloud's infrastructure and integrates with all its <a href="https://docs.getdbt.com/docs/cloud/about-cloud/dbt-cloud-features">features</a>.
+The dbt Cloud CLI and <a href="https://github.com/dbt-labs/dbt-core">dbt Core</a>, an open-source project, are both command line tools that enable you to run dbt commands. 
 
-</details>
+The key distinction is the dbt Cloud CLI is tailored for dbt Cloud's infrastructure and integrates with all its <a href="https://docs.getdbt.com/docs/cloud/about-cloud/dbt-cloud-features">features</a>.
 
-<details>
-<summary>How do I run both the dbt Cloud CLI and dbt Core?</summary>
-For compatibility, both the dbt Cloud CLI and dbt Core are invoked by running <code>dbt</code>. This can create path conflicts if your operating system selects one over the other based on your $PATH environment variable (settings).<br />
+</detailsToggle>
+
+<detailsToggle alt_header="How do I run both the dbt Cloud CLI and dbt Core?">
+
+For compatibility, both the dbt Cloud CLI and dbt Core are invoked by running `dbt`. This can create path conflicts if your operating system selects one over the other based on your $PATH environment variable (settings).
 
 If you have dbt Core installed locally, either:
 
@@ -276,10 +277,11 @@ If you have dbt Core installed locally, either:
 3. (Advanced users) Install natively, but modify the $PATH environment variable to correctly point to the dbt Cloud CLI binary to use both dbt Cloud CLI and dbt Core together.
 
 You can always uninstall the dbt Cloud CLI to return to using dbt Core.
-</details>
 
-<details>
-<summary>How to create an alias?</summary>
+</detailsToggle>
+
+<detailsToggle alt_header="How to create an alias?">
+
 To create an alias for the dbt Cloud CLI: <br />
 
 1. Open your shell's profile configuration file. Depending on your shell and system, this could be <code>~/.bashrc</code>, <code>~/.bash_profile</code>, <code>~/.zshrc</code>, or another file.<br />
@@ -297,9 +299,12 @@ As an example, in bash you would run: <code>source ~/.bashrc</code><br />
 
 
 This alias will allow you to use the <code>dbt-cloud</code> command to invoke the dbt Cloud CLI while having dbt Core installed natively.
-</details>
 
-<details>
-<summary>Why am I receiving a <code>Session occupied</code> error?</summary>
+</detailsToggle>
+
+<detailsToggle alt_header="Why am I receiving a `Session occupied` error?">
+
+
 If you've ran a dbt command and receive a <code>Session occupied</code> error, you can reattach to your existing session with <code>dbt reattach</code> and then press <code>Control-C</code> and choose to cancel the invocation.
-</details>
+
+</detailsToggle>

website/docs/docs/collaborate/govern/model-contracts.md

@@ -91,7 +91,7 @@ When building a model with a defined contract, dbt will do two things differentl
 Select the adapter-specific tab for more information on [constraint](/reference/resource-properties/constraints) support across platforms. Constraints fall into three categories based on support and platform enforcement:
 
 - **Supported and enforced** — The model won't build if it violates the constraint.
-- **Supported and not enforced** — The platform supports specifying the type of constraint, but a model can still build even if building the model violates the constraint. This constraint exists for metadata purposes only. This is common for modern cloud data warehouses and less common for legacy databases.
+- **Supported and not enforced** — The platform supports specifying the type of constraint, but a model can still build even if building the model violates the constraint. This constraint exists for metadata purposes only. This approach is more typical in cloud data warehouses than in transactional databases, where strict rule enforcement is more common.
 - **Not supported and not enforced** — You can't specify the type of constraint for the platform.
 
 

website/docs/docs/dbt-cloud-apis/sl-api-overview.md

@@ -9,10 +9,10 @@ pagination_next: "docs/dbt-cloud-apis/sl-jdbc"
 
 <VersionBlock lastVersion="1.5">
 
-import LegacyInfo from '/snippets/_legacy-sl-callout.md';
-
-<LegacyInfo />
+import DeprecationNotice from '/snippets/_sl-deprecation-notice.md';
 
+<DeprecationNotice />
+
 </VersionBlock>
 
 The rapid growth of different tools in the modern data stack has helped data professionals address the diverse needs of different teams. The downside of this growth is the fragmentation of business logic across teams, tools, and workloads.
@@ -57,5 +57,3 @@ plan="dbt Cloud Team or Enterprise"
     icon="dbt-bit"/>
 
 </div>
-
-

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

@@ -7,10 +7,10 @@ tags: [Semantic Layer, APIs]
 
 <VersionBlock lastVersion="1.5">
 
-import LegacyInfo from '/snippets/_legacy-sl-callout.md';
-
-<LegacyInfo />
+import DeprecationNotice from '/snippets/_sl-deprecation-notice.md';
 
+<DeprecationNotice />
+
 </VersionBlock>
 
 

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

@@ -7,10 +7,10 @@ tags: [Semantic Layer, API]
 
 <VersionBlock lastVersion="1.5">
 
-import LegacyInfo from '/snippets/_legacy-sl-callout.md';
-
-<LegacyInfo />
+import DeprecationNotice from '/snippets/_sl-deprecation-notice.md';
 
+<DeprecationNotice />
+
 </VersionBlock>
 
 The dbt Semantic Layer Java Database Connectivity (JDBC) API enables users to query metrics and dimensions using the JDBC protocol, while also providing standard metadata functionality. 

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

@@ -9,10 +9,10 @@ pagination_next: null
 
 <VersionBlock lastVersion="1.5">
 
-import LegacyInfo from '/snippets/_legacy-sl-callout.md';
-
-<LegacyInfo />
+import DeprecationNotice from '/snippets/_sl-deprecation-notice.md';
 
+<DeprecationNotice />
+
 </VersionBlock>
 
 dbt creates an [artifact](/reference/artifacts/dbt-artifacts) file called the _Semantic Manifest_ (`semantic_manifest.json`), which MetricFlow requires to build and run metric queries properly for the dbt Semantic Layer. This artifact contains comprehensive information about your dbt Semantic Layer. It is an internal file that acts as the integration point with MetricFlow. 
@@ -97,4 +97,3 @@ Top-level keys for the semantic manifest are:
 
 - [dbt Semantic Layer API](/docs/dbt-cloud-apis/sl-api-overview)
 - [About dbt artifacts](/reference/artifacts/dbt-artifacts)
-

website/docs/docs/dbt-versions/core-upgrade/04-upgrading-to-v1.4.md

@@ -48,7 +48,7 @@ For more detailed information and to ask any questions, please visit [dbt-core/d
 
 - [**Events and structured logging**](/reference/events-logging): dbt's event system got a makeover. Expect more consistency in the availability and structure of information, backed by type-safe event schemas.
 - [**Python support**](/faqs/Core/install-python-compatibility): Python 3.11 was released in October 2022. It is officially supported in dbt-core v1.4, although full support depends also on the adapter plugin for your data platform. According to the Python maintainers, "Python 3.11 is between 10-60% faster than Python 3.10." We encourage you to try [`dbt parse`](/reference/commands/parse) with dbt Core v1.4 + Python 3.11, and compare the timing with dbt Core v1.3 + Python 3.10. Let us know what you find!
-- [**Metrics**](/docs/build/metrics): `time_grain` is optional, to provide better ergonomics around metrics that aren't time-bound.
+- [**Metrics**](/docs/build/build-metrics-intro): `time_grain` is optional, to provide better ergonomics around metrics that aren't time-bound.
 - **dbt-Jinja context:** The [local_md5](/reference/dbt-jinja-functions/local_md5) context method will calculate an [MD5 hash](https://en.wikipedia.org/wiki/MD5) for use _within_ dbt. (Not to be confused with SQL md5!)
 - [**Exposures**](/docs/build/exposures) can now depend on `metrics`.
 - [**"Tarball" packages**](/docs/build/packages#internally-hosted-tarball-URL): Some organizations have security requirements to pull resources only from internal services. To address the need to install packages from hosted environments (such as Artifactory or cloud storage buckets), it's possible to specify any accessible URL where a compressed dbt package can be downloaded.

website/docs/docs/dbt-versions/core-upgrade/05-upgrading-to-v1.3.md

@@ -49,7 +49,7 @@ GitHub discussion with details: [dbt-labs/dbt-core#6011](https://github.com/dbt-
 ## New and changed documentation
 
 - **[Python models](/docs/build/python-models)** are natively supported in `dbt-core` for the first time, on data warehouses that support Python runtimes.
-- Updates made to **[Metrics](/docs/build/metrics)** reflect their new syntax for definition, as well as additional properties that are now available.
+- Updates made to **[Metrics](/docs/build/build-metrics-intro)** reflect their new syntax for definition, as well as additional properties that are now available.
 - Plus, a few related updates to **[exposure properties](/reference/exposure-properties)**: `config`, `label`, and `name` validation.
 
 - **[Custom `node_color`](/reference/resource-configs/docs.md)** in `dbt-docs`. For the first time, you can control the colors displayed in dbt's DAG. Want bronze, silver, and gold layers? It's at your fingertips.

website/docs/docs/dbt-versions/core-upgrade/06-upgrading-to-v1.2.md

@@ -34,7 +34,7 @@ See GitHub discussion [dbt-labs/dbt-core#5468](https://github.com/dbt-labs/dbt-c
 ## New and changed functionality
 
 - **[Grants](/reference/resource-configs/grants)** are natively supported in `dbt-core` for the first time. That support extends to all standard materializations, and the most popular adapters. If you already use hooks to apply simple grants, we encourage you to use built-in `grants` to configure your models, seeds, and snapshots instead. This will enable you to [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) up your duplicated or boilerplate code.
-- **[Metrics](/docs/build/metrics)** now support an `expression` type (metrics-on-metrics), as well as a `metric()` function to use when referencing metrics from within models, macros, or `expression`-type metrics. For more information on how to use expression metrics, check out the [**`dbt_metrics` package**](https://github.com/dbt-labs/dbt_metrics)
+- **[Metrics](/docs/build/build-metrics-intro)** now support an `expression` type (metrics-on-metrics), as well as a `metric()` function to use when referencing metrics from within models, macros, or `expression`-type metrics. For more information on how to use expression metrics, check out the [**`dbt_metrics` package**](https://github.com/dbt-labs/dbt_metrics)
 - **[dbt-Jinja functions](/reference/dbt-jinja-functions)** now include the [`itertools` Python module](/reference/dbt-jinja-functions/modules#itertools), as well as the [set](/reference/dbt-jinja-functions/set) and [zip](/reference/dbt-jinja-functions/zip) functions.
 - **[Node selection](/reference/node-selection/syntax)** includes a [file selection method](/reference/node-selection/methods#the-file-method) (`-s model.sql`), and [yaml selector](/reference/node-selection/yaml-selectors) inheritance.
 - **[Global configs](/reference/global-configs/about-global-configs)** now include CLI flag and environment variable settings for [`target-path`](/reference/project-configs/target-path) and [`log-path`](/reference/project-configs/log-path), which can be used to override the values set in `dbt_project.yml`

website/docs/docs/dbt-versions/core-upgrade/08-upgrading-to-v1.0.md

@@ -70,7 +70,7 @@ Several under-the-hood changes from past minor versions, tagged with deprecation
 
 ## New features and changed documentation
 
-- Add [metrics](/docs/build/metrics), a new node type
+- Add [metrics](/docs/build/build-metrics-intro), a new node type
 - [Generic tests](/best-practices/writing-custom-generic-tests) can be defined in `tests/generic` (new), in addition to `macros/` (as before)
 - [Parsing](/reference/parsing): partial parsing and static parsing have been turned on by default.
 - [Global configs](/reference/global-configs/about-global-configs) have been standardized. Related updates to [global CLI flags](/reference/global-cli-flags) and [`profiles.yml`](/docs/core/connect-data-platform/profiles.yml).

website/docs/docs/dbt-versions/release-notes/74-Dec-2023/legacy-sl.md

@@ -0,0 +1,39 @@
+---
+title: "Deprecation: dbt Metrics and the legacy dbt Semantic Layer is now deprecated"
+description: "December 2023: For users on dbt v1.5 and lower, dbt Metrics and the legacy dbt Semantic Layer has been deprecated. Use the migration guide to migrate to and access the latest dbt Semantic Layer. "
+sidebar_label: "Deprecation: dbt Metrics and Legacy dbt Semantic Layer"
+sidebar_position: 09
+date: 2023-12-15
+---
+
+dbt Labs has deprecated dbt Metrics and the legacy dbt Semantic Layer, both supported on dbt version 1.5 or lower. This change starts on December 15th, 2023.
+
+This deprecation means dbt Metrics and the legacy Semantic Layer are no longer supported. We also removed the feature from the dbt Cloud user interface and documentation site.
+
+### Why this change?
+
+The [re-released dbt Semantic Layer](/docs/use-dbt-semantic-layer/dbt-sl), powered by MetricFlow, offers enhanced flexibility, performance, and user experience, marking a significant advancement for the dbt community.
+
+### Key changes and impact
+
+- **Deprecation date** — The legacy Semantic Layer and dbt Metrics will be officially deprecated on December 15th, 2023.
+- **Replacement** — [MetricFlow](/docs/build/build-metrics-intro) replaces dbt Metrics for defining semantic logic. The `dbt_metrics` package will no longer be supported post-deprecation.
+- **New feature** — Exports replaces the materializing data with `metrics.calculate` functionality and will be available in dbt Cloud in December or January.
+
+
+### Breaking changes and recommendations
+
+- For users on dbt version 1.6 and lower with dbt Metrics and Snowflake proxy:
+  - **Impact**: Post-deprecation, queries using the proxy _will not_ run.
+  - **Action required:** _Immediate_ migration is necessary. Refer to the [dbt Semantic Layer migration guide](/guides/sl-migration?step=1)
+
+- For users on dbt version 1.6 and lower using dbt Metrics without Snowflake proxy:
+  - **Impact**: No immediate disruption, but the package will not receive updates or support after deprecation
+  - **Recommendation**: Plan migration to the re-released Semantic Layer for compatibility with dbt version 1.6 and higher.
+
+### Engage and support
+
+- Feedback and community support — Engage and share feedback with the dbt Labs team and dbt Community slack using channels like [#dbt-cloud-semantic-layer](https://getdbt.slack.com/archives/C046L0VTVR6) and [#dbt-metricflow](https://getdbt.slack.com/archives/C02CCBBBR1D). Or reach out to your dbt Cloud account representative.
+- Resources for upgrading — Refer to some additional info and resources to help you upgrade your dbt version:
+  - [Upgrade version in dbt Cloud](/docs/dbt-versions/upgrade-core-in-cloud)
+  - [Version migration guides](/docs/dbt-versions/core-upgrade)