v1.2 docs omnibus (#1698)

* Add itertools module #1368

* Manifest v6 #1667

* Add set + zip #1635

* File selector method #1627

* Selector inheritance #1628

* Global config for target-path, log-path #1687

* Update website/docs/reference/dbt-jinja-functions/zip.md

Co-authored-by: Anders <[email protected]>

* Update website/docs/reference/dbt-jinja-functions/set.md

Co-authored-by: Anders <[email protected]>

* PR feedback

Co-authored-by: Anders <[email protected]>

website/docs/guides/migration/versions/06-upgrading-to-v1.2.md

@@ -13,14 +13,24 @@ title: "Upgrading to v1.2 (prerelease)"
 
 There are no breaking changes for end users of dbt. We are committed to providing backwards compatibility for all versions 1.x. If you encounter an error upon upgrading, please let us know by [opening an issue](https://github.com/dbt-labs/dbt-core/issues/new).
 
+### For consumers of dbt artifacts (metadata)
+
+The manifest schema version has been updated to `v6`. The relevant changes are:
+- Change to `config` default, which includes a new `grants` property with default value `{}`
+- Addition of a `metrics` property, to any node which could reference metrics using the `metric()` function
+
+For users of [state-based selection](understanding-state): This release also includes new logic declaring forwards compatibility for older manifest versions. While running dbt Coree v1.2, it should be possible to use `state:modified --state ...` selection against a manifest produced by dbt Core v1.0 or v1.1.
+
 ## For maintainers of adapter plugins
 
 See GitHub discussion [dbt-labs/dbt-core#5468](https://github.com/dbt-labs/dbt-core/discussions/5468) for detailed information
 
 ## New and changed documentation
 
-- **[Grants](/reference/resource-configs/grants)**: You should now manage access to the datasets you're producing with dbt by using grants instead of using hooks.  If you already use post-hook to apply simple grants, moving to the grants feature will allow you to [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) up your duplicated or boilerplate code.
-
+- **[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.
+- **[dbt-Jinja functions](reference/dbt-jinja-functions)** now include the [`itertools` Python module](dbt-jinja-functions/modules#itertools), as well as the [set](dbt-jinja-functions/set) and [zip](dbt-jinja-functions/zip) functions.
+- **[Node selection](node-selection/syntax)** includes a [file selection method](node-selection/methods#the-file-method) (`-s model.sql`), and [yaml selector](node-selection/yaml-selectors) inheritance.
+- **[Global configs](global-configs)** now include CLI flag and environment variable settings for [`target-path`](target-path) and [`log-path`](log-path), which can be used to override the values set in `dbt_project.yml`
 - **[Metrics](building-a-dbt-project/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 how to use expression metrics, please reference the [**`dbt_metrics` package**](https://github.com/dbt-labs/dbt_metrics)
 
 

website/docs/reference/artifacts/dbt-artifacts.md

@@ -43,9 +43,4 @@ In the manifest, the `metadata` may also include:
 
 #### Notes:
 - The structure of dbt artifacts is canonized by [JSON schemas](https://json-schema.org/), which are hosted at **schemas.getdbt.com**.
-- As of v0.20.0, the current schema for each artifact is:
-    - https://schemas.getdbt.com/dbt/manifest/v4.json
-    - https://schemas.getdbt.com/dbt/run-results/v4.json
-    - https://schemas.getdbt.com/dbt/catalog/v1.json
-    - https://schemas.getdbt.com/dbt/sources/v3.json
-- Artifact versions may change in any minor version of dbt (`v0.x.0`). Each artifact is versioned independently.
+- Artifact versions may change in any minor version of dbt (`v1.x.0`). Each artifact is versioned independently.

website/docs/reference/artifacts/manifest-json.md

@@ -2,7 +2,7 @@
 title: Manifest
 ---
 
-_Current schema_: [`v5`](https://schemas.getdbt.com/dbt/manifest/v5/index.html)
+_Current schema_: [`v6`](https://schemas.getdbt.com/dbt/manifest/v6/index.html)
 
 _Produced by:_
 - `dbt compile`

website/docs/reference/dbt-jinja-functions/modules.md

@@ -48,3 +48,46 @@ This variable is a pointer to the Python [re](https://docs.python.org/3/library/
     ) -%}
 {% endif %}
 ```
+
+<VersionBlock firstVersion="1.2">
+
+## itertools
+This variable is a pointer to the Python [itertools](https://docs.python.org/3/library/itertools.html) module, which includes useful functions for working with iterators (loops, lists, and the like).
+
+The supported functions are:
+- `count`
+- `cycle`
+- `repeat`
+- `accumulate`
+- `chain`
+- `compress`
+- `islice`
+- `starmap`
+- `tee`
+- `zip_longest`
+- `product`
+- `permutations`
+- `combinations`
+- `combinations_with_replacement`
+
+**Usage**
+
+```
+{%- set A = [1, 2] -%}
+{%- set B = ['x', 'y', 'z'] -%}
+{%- set AB_cartesian = modules.itertools.product(A, B) -%}
+
+{%- for item in AB_cartesian %}
+  {{ item }}
+{%- endfor -%}
+```
+```
+  (1, 'x')
+  (1, 'y')
+  (1, 'z')
+  (2, 'x')
+  (2, 'y')
+  (2, 'z')
+```
+
+</VersionBlock>

website/docs/reference/dbt-jinja-functions/set.md

@@ -0,0 +1,50 @@
+---
+title: "set"
+id: "set"
+---
+
+### set
+
+_Not to be confused with the `{% set foo = "bar" ... %}` expression in Jinja!_
+
+The `set` context method can be used to convert any iterable to a sequence of iterable elements that are unique (a set).
+
+__Args__:
+- `value`: The iterable to convert (e.g. a list)
+- `default`: A default value to return if the `value` argument is not a valid iterable
+
+### Usage
+
+```
+{% set my_list = [1, 2, 2, 3] %}
+{% set my_set = set(my_list) %}
+{% do log(my_set) %}  {# {1, 2, 3} #}
+```
+
+```
+{% set my_invalid_iterable = 1234 %}
+{% set my_set = set(my_invalid_iterable) %}
+{% do log(my_set) %}  {# None #}
+```
+
+### try_set
+
+The `try_set` context method can be used to convert any iterable to a sequence of iterable elements that are unique (a set). The difference to the `set` context method is that the `try_set` method will raise an exception on a `TypeError`, if the provided value is not a valid iterable and cannot be converted to a set.
+
+__Args__:
+- `value`: The iterable to convert (e.g. a list)
+
+```
+{% set my_list = [1, 2, 2, 3] %}
+{% set my_set = set(my_list) %}
+{% do log(my_set) %}  {# {1, 2, 3} #}
+```
+
+```
+{% set my_invalid_iterable = 1234 %}
+{% set my_set = try_set(my_invalid_iterable) %}
+{% do log(my_set) %}
+
+Compilation Error in ... (...)
+  'int' object is not iterable
+```

website/docs/reference/dbt-jinja-functions/zip.md

@@ -0,0 +1,53 @@
+---
+title: "zip"
+id: "zip"
+---
+
+### zip
+
+The `zip` context method can be used to used to return an iterator of tuples, where the i-th tuple contains the i-th element from each of the argument iterables. ([Python docs](https://docs.python.org/3/library/functions.html#zip))
+        :param 
+        :param 
+
+__Args__:
+- `*args`: Any number of iterables
+- `default`: A default value to return if `*args` is not iterable
+
+### Usage
+
+```
+{% set my_list_a = [1, 2] %}
+{% set my_list_b = ['alice', 'bob'] %}
+{% set my_zip = zip(my_list_a, my_list_b) | list %}
+{% do log(my_zip) %}  {# [(1, 'alice'), (2, 'bob')] #}
+```
+
+```
+{% set my_list_a = 12 %}
+{% set my_list_b = ['alice', 'bob'] %}
+{% set my_zip = zip(my_list_a, my_list_b, default = []) | list %}
+{% do log(my_zip) %}  {# [] #}
+```
+
+### try_zip
+
+The `try_zip` context method can be used to used to return an iterator of tuples, just like `zip`. The difference to the `zip` context method is that the `try_zip` method will raise an exception on a `TypeError`, if one of the provided values is not a valid iterable.
+
+__Args__:
+- `value`: The iterable to convert (e.g. a list)
+
+```
+{% set my_list_a = [1, 2] %}
+{% set my_list_b = ['alice', 'bob'] %}
+{% set my_zip = try_zip(my_list_a, my_list_b) | list %}
+{% do log(my_zip) %}  {# [(1, 'alice'), (2, 'bob')] #}
+```
+
+```
+{% set my_list_a = 12 %}
+{% set my_list_b = ['alice', 'bob'] %}
+{% set my_zip = try_zip(my_list_a, my_list_b) %}
+
+Compilation Error in ... (...)
+  'int' object is not iterable
+```

website/docs/reference/global-configs.md

@@ -5,13 +5,11 @@ id: "global-configs"
 
 ## About Global Configs
 
-Global configs enable you to fine-tune how dbt runs projects on your machine—whether your personal laptop, an orchestration tool running remotely, or (in some cases) dbt Cloud. They differ from [project configs](reference/dbt_project.yml) and [resource configs](reference/configs-and-properties), which tell dbt _what_ to run.
+Global configs enable you to fine-tune _how_ dbt runs projects on your machine—whether your personal laptop, an orchestration tool running remotely, or (in some cases) dbt Cloud. In general, they differ from most [project configs](reference/dbt_project.yml) and [resource configs](reference/configs-and-properties), which tell dbt _what_ to run.
 
-Global configs control things like the visual output of logs, the manner in which dbt parses your project, and what to do when dbt finds a version mismatch or a failing model.
+Global configs control things like the visual output of logs, the manner in which dbt parses your project, and what to do when dbt finds a version mismatch or a failing model. These configs are "global" because they are available for all dbt commands, and because they can be set for all projects running on the same machine or in the same environment.
 
-These configs are "global" because they are available for all dbt commands, and because they apply across all projects run on the same machine.
-
-Starting in v1.0, you can set global configs in three places. When all three are set, command line flags take precedence, then environment variables, and last profile configs.
+Starting in v1.0, you can set global configs in three places. When all three are set, command line flags take precedence, then environment variables, and last yaml configs (usually `profiles.yml`).
 
 ## Command line flags
 
@@ -88,9 +86,9 @@ $ dbt run
 
 </File>
 
-## Profile (or user) configurations
+## Yaml configurations
 
-You can set profile (or user) configurations in the `config:` block of `profiles.yml`. You would use the profile config to set defaults for all projects running on your local machine.
+For most global configurations, you can set "user profile" configurations in the `config:` block of `profiles.yml`. This style of configuration sets default values for all projects using this profile directory—usually, all projects running on your local machine.
 
 <File name='profiles.yml'>
 
@@ -103,6 +101,12 @@ config:
 
 </File>
 
+<VersionBlock firstVersion="1.2">
+
+The exception: Some global configurations are actually set in `dbt_project.yml`, instead of `profiles.yml`, because they control where dbt places logs and artifacts. Those file paths are always relative to the location of `dbt_project.yml`. For more details, see ["Log and target paths"](#log-and-target-paths) below.
+
+</VersionBlock>
+
 <VersionBlock firstVersion="1.1">
 
 ### Cache database objects for selected resource
@@ -269,6 +273,27 @@ config:
 
 </File>
 
+<VersionBlock firstVersion="1.2">
+
+### Log and target paths
+
+By default, dbt will write logs to a directory named `logs/`, and all other artifacts to a directory named `target/`. Both of those directories are located relative to `dbt_project.yml` of the active project—that is, the root directory from which dbt is run.
+
+Just like other global configs, it is possible to override these values for your environment or invocation by using CLI flags (`--target-path`, `--log-path`) or environment variables (`DBT_TARGET_PATH`, `DBT_LOG_PATH`).
+
+Unlike the other global configs documented on this page, which can be set in `profiles.yml`, the project paths are configured in `dbt_project.yml`. This is because `profiles.yml` and `dbt_project.yml` are most often located in separate file systems on your machine, and the log and artifact paths are always defined relative to the location of `dbt_project.yml`.
+
+<File name='dbt_project.yml'>
+
+```yaml
+[target-path](target-path): "other-target"
+[log-path](log-path): "other-logs"
+```
+
+</File>
+
+</VersionBlock>
+
 ### Send anonymous usage stats
 
 We want to build the best version of dbt possible, and a crucial part of that is understanding how users work with dbt. To this end, we've added some simple event tracking to dbt (using Snowplow). We do not track credentials, model contents or model names (we consider these private, and frankly none of our business).

website/docs/reference/node-selection/methods.md

@@ -73,6 +73,19 @@ selectors unambiguous.
 
 </VersionBlock>
 
+<VersionBlock firstVersion="1.2">
+
+### The "file" method
+The `file` method can be used to select a model by its filename, including the file extension (`.sql`).
+
+```bash
+# These are equivalent
+dbt run --select some_model.sql
+dbt run --select some_model
+```
+
+</VersionBlock>
+
 ### The "package" method
 <Changelog>New in v0.18.0</Changelog>
 

website/docs/reference/node-selection/yaml-selectors.md

@@ -261,3 +261,31 @@ selectors:
     default: "{{ target.name == 'prod' | as_bool }}"
     definition: ...
 ```
+
+<VersionBlock firstVersion="1.2">
+
+### Selector inheritance
+
+Selectors can reuse and extend definitions from other selectors, via the `selector` method.
+
+```yml
+selectors:
+  - name: foo_and_bar
+    definition:
+      intersection:
+        - tag: foo
+        - tag: bar
+
+  - name: foo_bar_less_buzz
+    definition:
+      intersection:
+        # reuse the definition from above
+        - method: selector
+          value: foo_and_bar
+        # with a modification!
+        - exclude:
+            - method: tag
+              value: buzz
+```
+
+</VersionBlock>

website/docs/reference/project-configs/log-path.md

@@ -16,6 +16,18 @@ Optionally specify a custom directory where dbt will write logs.
 ## Default
 By default, dbt will write to the `logs` directory, i.e. `log-path: logs`
 
+<VersionBlock firstVersion="1.2">
+## Configuration
+
+In the manner of a ["global" config](global-configs), the log path can be set in three places:
+1. `--log-path` CLI flag
+2. `DBT_LOG_PATH` environment variable
+3. `log-path` in `dbt_project.yml`
+
+The precedence order is: CLI flag > env var > `dbt_project.yml`
+
+</VersionBlock>
+
 ## Examples
 ### Write logs to a subdirectory named `dbt_logs` instead of `logs`
 

website/docs/reference/project-configs/target-path.md

@@ -17,6 +17,18 @@ Optionally specify a custom directory where compiled files (e.g. compiled models
 ## Default
 By default, dbt will write compiled files to the `target` directory, i.e. `target-path: target`
 
+<VersionBlock firstVersion="1.2">
+## Configuration
+
+In the manner of a ["global" config](global-configs), the target path can be set in three places:
+1. `--target-path` CLI flag
+2. `DBT_TARGET_PATH` environment variable
+3. `target-path` in `dbt_project.yml`
+
+The precedence order is: CLI flag > env var > `dbt_project.yml`
+
+</VersionBlock>
+
 ## Examples
 ### Use a subdirectory named `compiled` for compiled files