Merge branch 'current' into jerco/clarify-model-contract-inferred-par…

…tial

.github/ISSUE_TEMPLATE/improve-docs.yml → .github/ISSUE_TEMPLATE/a-improve-docs.yml

@@ -39,4 +39,4 @@ body:
       label: Additional information
       description: Add any other context or screenshots about the feature request here.
     validations:
-      required: false
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -1,8 +1,5 @@
 blank_issues_enabled: true
 contact_links:
-  - name: Want to see new content? Open a discussion!
-    url: https://github.com/dbt-labs/docs.getdbt.com/discussions/new
-    about: You can open a discussion to propose new content for the dbt product documentation.
   - name: Have questions about dbt? Join the Community!
     url: https://www.getdbt.com/community/join-the-community
     about: You can join the dbt Labs Community to ask and answer questions.

.github/ISSUE_TEMPLATE/improve-the-site.yml

@@ -1,6 +1,6 @@
-name: Improve the docs.getdbt.com site
-description: Make a suggestion or report a problem about the technical implementation of docs.getdbt.com.
-labels: ["engineering"]
+name: Report a docs.getdbt.com site issue
+description: Report a problem about the technical implementation of docs.getdbt.com.
+labels: ["engineering","bug"]
 body:
   - type: markdown
     attributes:
@@ -39,4 +39,4 @@ body:
       label: Additional information
       description: Any additional information, configuration, or data that might be necessary to reproduce the issue.
     validations:
-      required: false
+      required: false

.github/ISSUE_TEMPLATE/zzz_add-adapter-to-trusted-list.yml

@@ -0,0 +1,62 @@
+name: Add adapter to Trusted list
+description: For adapter maintainers who wish to have theirs added to the list of Trusted adapters.
+title: "Trust dbt-myadapter"
+labels: ["adapter maintainers"]
+assignees:
+  - dataders
+body:
+  - type: markdown
+    attributes:
+      value: |
+        We're excited that you'd like to support your adapter formally as "Trusted"! This template will ensure that you are aware of the process and the guidelines. Additionally, that you can vouch that your adapter currently meets the standards of a Trusted adapter. For more information, see [Trusted adapters](https://docs.getdbt.com/docs/trusted-adapters)
+
+  - type: input
+    id: adapter-repo
+    attributes:
+      label: Link to adapter repo
+      description: Please link to the GitHub repo
+    validations:
+      required: true
+
+  - type: input
+    id: contact
+    attributes:
+      label: Contact Details
+      description: How can we get in touch with you?
+      placeholder: your preferred email and/or dbt Slack handle
+    validations:
+      required: true
+
+  - type: dropdown
+    id: author_type
+    attributes:
+      label: Which of these best describes you?
+      options:
+        - I am a dbt Community member
+        - I work for the vendor on top of which the dbt adapter functions
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: read-program-guide
+    attributes:
+      label: Please agree to the each of the following
+      options:
+        - label: I am a maintainer of the adapter being submited for Trusted status
+          required: true
+        - label: I have read both the [Trusted adapters](https://docs.getdbt.com/docs/trusted-adapters) and [Building a Trusted Adapter](https://docs.getdbt.com/guides/dbt-ecosystem/adapter-development/8-building-a-trusted-adapter) pages.
+          required: true
+        - label: I believe that the adapter currently meets the expectations given above
+          required: true
+        - label: I will ensure this adapter stays in compliance with the guidelines
+          required: true
+        - label: I understand that dbt Labs reserves the right to remove an adapter from the trusted adapter list at any time, should any of the below guidelines not be met
+          required: true
+
+  - type: textarea
+    id: icon
+    attributes:
+      label: What icon should be used?
+      description: |
+        Please share an svg image that you'd like to be displayed in for your adapter. Normally, this is the logo for the data platform on top of which your adapter works. If there's a dark mode version, please also share that.
+        Pasting the image from your clipboard will upload the file to GitHub and create markdown formatting for it to be rendered inline

.github/workflows/autogenerated_labeler.yml

@@ -0,0 +1,40 @@
+# **what?**
+# Labels issues autogenerated in dbt-core
+
+# **why?**
+# To organize autogenerated issues from dbt-core to make it easier to find and track them.
+
+# **when?**
+# When an issue is opened by the FishtownBuildBot
+
+name: Add Labels to Autogenerated Issues
+
+on:
+  issues:
+    types: [opened]
+
+jobs:
+  add_customized_labels:
+    if: github.event.issue.user.login == 'FishtownBuildBot'
+    permissions:
+      issues: write
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Determine appropriate labels by repo in title"
+        id: repo
+        env:
+          ISSUE_TITLE: ${{ github.event.issue.title }}
+        run: |
+          if [[ "$ISSUE_TITLE" == *"dbt-core"* ]]; then
+            echo "labels='content,improvement,dbt Core'" >> $GITHUB_OUTPUT
+          else
+            echo "labels='content,improvement,adapters'" >> $GITHUB_OUTPUT
+          fi
+
+      - name: "Add Labels to autogenerated Issues"
+        id: add-labels
+        run: |
+          gh issue edit ${{ github.event.issue.number }} --repo ${{ github.repository }} --add-label ${{ steps.repo.outputs.labels }}
+        env:
+          GH_TOKEN: ${{ secrets.DOCS_SECRET }}

contributing/single-sourcing-content.md

@@ -90,7 +90,7 @@ This component can be added directly to a markdown file in a similar way as othe
 Both properties can be used together to set a range where the content should show. In the example below, this content will only show if the selected version is between **0.21** and **1.0**:
 
 ```markdown
-<VersionBlock lastVersion="1.0">
+<VersionBlock lastVersion="1.6">
 
 	Versioned content here
 

website/dbt-versions.js

@@ -23,10 +23,6 @@ exports.versions = [
     version: "1.1",
     EOLDate: "2023-04-28",
   },
-  {
-    version: "1.0",
-    EOLDate: "2022-12-03"
-  },
 ]
 
 exports.versionedPages = [

website/docs/docs/build/derived-metrics.md

@@ -6,7 +6,7 @@ sidebar_label: Derived
 tags: [Metrics, Semantic Layer]
 ---
 
-In MetricFlow, derived metrics are metrics created by defining an expression using other metrics. They allow performing calculations on top of existing metrics. This proves useful for combining metrics and applying arithmetic functions to aggregated columns, such as, you can define a profit metric. 
+In MetricFlow, derived metrics are metrics created by defining an expression using other metrics. They enable you to perform calculations with existing metrics. This is helpful for combining metrics and doing math functions on aggregated columns, like creating a profit metric. 
 
  The parameters, description, and type for derived metrics are: 
 
@@ -21,7 +21,7 @@ In MetricFlow, derived metrics are metrics created by defining an expression usi
 | `metrics` |  The list of metrics used in the derived metrics. | Required  |
 | `alias` | Optional alias for the metric that you can use in the expr. | Optional |
 | `filter` | Optional filter to apply to the metric. | Optional |
-| `offset_window` | Set the period for the offset window, such as 1 month. This will return the value of the metric one month from the metric time. | Required |
+| `offset_window` | Set the period for the offset window, such as 1 month. This will return the value of the metric one month from the metric time.  | Required |
 
 The following displays the complete specification for derived metrics, along with an example.
 
@@ -37,7 +37,7 @@ metrics:
         - name: the name of the metrics. must reference a metric you have already defined # Required
           alias: optional alias for the metric that you can use in the expr # Optional
           filter: optional filter to apply to the metric # Optional
-          offset_window: set the period for the offset window i.e 1 month. This will return the value of the metric one month from the metric time. # Required
+          offset_window: set the period for the offset window, such as 1 month. This will return the value of the metric one month from the metric time. # Required
 ```
 
 ## Derived metrics example
@@ -85,17 +85,75 @@ metrics:
 
 ## Derived metric offset
 
-You may want to use an offset value of a metric in the definition of a derived metric. For example, you can model the retention rate by using a derived metric with an offset, which involves calculating (active customers at the end of the month/active customers at the beginning of the month).
+To perform calculations using a metric's value from a previous time period, you can add an offset parameter to a derived metric. For example, if you want to calculate period-over-period growth or track user retention, you can use this metric offset.
+
+**Note:** You must include the [`metric_time` dimension](/docs/build/dimensions#time) when querying a derived metric with an offset window.
+
+The following example displays how you can calculate monthly revenue growth using a 1-month offset window:
 
 ```yaml
-metrics:
-- name: user_retention
-  type: derived
+- name: customer_retention
+  description: Percentage of customers that are active now and those active 1 month ago
+  label: customer_retention
   type_params:
-    expr: active_customers/active_customers_t1m
+    expr: (active_customers/ active_customers_prev_month)
     metrics:
-      - name: active_customers # these are all metrics (can be a derived metric, meaning building a derived metric with derived metrics)
+      - name: active_customers
+        alias: current_active_customers
       - name: active_customers
         offset_window: 1 month
-        alias: active_customers_t1m
+        alias: active_customers_prev_month
 ```
+
+### Offset windows and granularity
+
+You can query any granularity and offset window combination. The following example queries a metric with a 7-day offset and a monthly grain:
+
+```yaml
+- name: d7_booking_change
+  description: Difference between bookings now and 7 days ago
+  type: derived
+  label: d7 Bookings Change
+  type_params:
+    expr: bookings - bookings_7_days_ago
+    metrics:
+      - name: bookings
+        alias: current_bookings
+      - name: bookings
+        offset_window: 7 days
+        alias: bookings_7_days_ago
+```
+
+When you run the query  `mf query --metrics d7_booking_change --group-by metric_time__month` for the metric, here's how it's calculated:
+
+1. We retrieve the raw, unaggregated dataset with the specified measures and dimensions at the smallest level of detail, which is currently 'day'.
+2. Then, we perform an offset join on the daily dataset, followed by performing a date trunc and aggregation to the requested granularity.
+   For example, to calculate `d7_booking_change` for July 2017: 
+   - First, we sum up all the booking values for each day in July to calculate the bookings metric.
+   - The following table displays the range of days that make up this monthly aggregation.
+
+|   | Orders | Metric_time |
+| - | ---- | -------- |
+|   | 330 | 2017-07-31 |
+|   | 7030 | 2017-07-30 to 2017-07-02 |
+|   | 78 | 2017-07-01 |
+| Total  | 7438 | 2017-07-01 |
+
+3. Next, we calculate July's bookings with a 7-day offset. The following table displays the range of days that make up this monthly aggregation. Note that the month begins 7 days later (offset by 7 days) on 2017-07-24.
+
+|   | Orders | Metric_time |
+| - | ---- | -------- |
+|   | 329 | 2017-07-24 |
+|   | 6840 | 2017-07-23  to 2017-06-30 |
+|   | 83 | 2017-06-24 |
+| Total  | 7252 | 2017-07-01 |
+
+4. Lastly, we calculate the derived metric and return the final result set:
+
+```bash
+bookings - bookings_7_days_ago would be compile as 7438 - 7252 = 186. 
+```
+
+| d7_booking_change | metric_time__month |
+| ----------------- | ------------------ |
+| 186 | 2017-07-01 |

website/docs/docs/build/groups.md

@@ -1,6 +1,6 @@
 ---
 title: "Add groups to your DAG"
-sidebar_title: "Groups"
+sidebar_label: "Groups"
 id: "groups"
 description: "When you define groups in dbt projects, you turn implicit relationships into an explicit grouping."
 keywords:

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

@@ -79,12 +79,6 @@ A `unique_key` enables updating existing rows instead of just appending new rows
 
 Not specifying a `unique_key` will result in append-only behavior, which means dbt inserts all rows returned by the model's SQL into the preexisting target table without regard for whether the rows represent duplicates.
 
-<VersionBlock lastVersion="1.0">
-
-The optional `unique_key` parameter specifies a field that can uniquely identify each row within your model. You can define `unique_key` in a configuration block at the top of your model. If your model doesn't contain a single field that is unique, but rather a combination of columns, we recommend that you create a single column that can serve as a unique identifier (by concatenating and hashing those columns), and pass it into your model's configuration.
-
-</VersionBlock>
-
 <VersionBlock firstVersion="1.1">
 
 The optional `unique_key` parameter specifies a field (or combination of fields) that define the grain of your model. That is, the field(s) identify a single unique row. You can define `unique_key` in a configuration block at the top of your model, and it can be a single column name or a list of column names.

website/docs/docs/build/packages.md

@@ -284,18 +284,35 @@ packages:
 </File>
 
 ### Local packages
-Packages that you have stored locally can be installed by specifying the path to the project, like so:
+A "local" package is a dbt project accessible from your local file system. You can install it by specifying the project's path. It works best when you nest the project within a subdirectory relative to your current project's directory.
 
 <File name='packages.yml'>
 
 ```yaml
 packages:
-  - local: /opt/dbt/redshift # use a local path
+  - local: relative/path/to/subdirectory
 ```
 
 </File>
 
-Local packages should only be used for specific situations, for example, when testing local changes to a package.
+Other patterns may work in some cases, but not always. For example, if you install this project as a package elsewhere, or try running it on a different system, the relative and absolute paths will yield the same results.
+
+<File name='packages.yml'>
+
+```yaml
+packages:
+  # not recommended - support for these patterns vary
+  - local: /../../redshift   # relative path to a parent directory
+  - local: /opt/dbt/redshift # absolute path on the system
+```
+
+</File>
+
+There are a few specific use cases where we recommend using a "local" package:
+1. **Monorepo** &mdash; When you have multiple projects, each nested in a subdirectory, within a monorepo. "Local" packages allow you to combine projects for coordinated development and deployment.
+2. **Testing changes** &mdash; To test changes in one project or package within the context of a downstream project or package that uses it. By temporarily switching the installation to a "local" package, you can make changes to the former and immediately test them in the latter for quicker iteration. This is similar to [editable installs](https://pip.pypa.io/en/stable/topics/local-project-installs/) in Python.
+3. **Nested project** &mdash; When you have a nested project that defines fixtures and tests for a project of utility macros, like [the integration tests within the `dbt-utils` package](https://github.com/dbt-labs/dbt-utils/tree/main/integration_tests).
+
 
 ## What packages are available?
 Check out [dbt Hub](https://hub.getdbt.com) to see the library of published dbt packages!

website/docs/docs/build/projects.md

@@ -18,6 +18,7 @@ At a minimum, all a project needs is the `dbt_project.yml` project configuration
 | [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. |
+| [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. |
 
 When building out the structure of your project, you should consider these impacts on your organization's workflow:

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

@@ -16,11 +16,15 @@ We encourage you to:
 
 dbt Python (`dbt-py`) models can help you solve use cases that can't be solved with SQL. You can perform analyses using tools available in the open-source Python ecosystem, including state-of-the-art packages for data science and statistics. Before, you would have needed separate infrastructure and orchestration to run Python transformations in production. Python transformations defined in dbt are models in your project with all the same capabilities around testing, documentation, and lineage.
 
+<VersionBlock lastVersion="1.2">
 
 Python models are supported in dbt Core 1.3 and higher.  Learn more about [upgrading your version in dbt Cloud](https://docs.getdbt.com/docs/dbt-cloud/cloud-configuring-dbt-cloud/cloud-upgrading-dbt-versions) and [upgrading dbt Core versions](https://docs.getdbt.com/docs/core-versions#upgrading-to-new-patch-versions).
 
 To read more about Python models, change the [docs version to 1.3](/docs/build/python-models?version=1.3) (or higher) in the menu bar.
 
+</VersionBlock>
+
+<VersionBlock firstVersion="1.3">
 
 <File name='models/my_python_model.py'>
 
@@ -711,3 +715,5 @@ You can also install packages at cluster creation time by [defining cluster prop
 </div>
 
 </WHCode>
+
+</VersionBlock>