Merge branch 'current' into ly-docs-fix-linter-behavior

contributing/adding-page-components.md

@@ -4,7 +4,7 @@ You can use the following components to provide code snippets for each supported
 
 Identify code by labeling with the warehouse names:
 
-```code
+```sql
         <WHCode>
 
         <div warehouse="warehouse#1">
@@ -32,7 +32,7 @@ You can use the following components to provide code snippets in a tabbed view.
 
 Identify code and code files by labeling with the component they are describing:
 
-```code
+```sql
         <Tabs
         defaultValue="models"
         values={[
@@ -91,11 +91,11 @@ Identify code and code files by labeling with the component they are describing:
 
 ### Link to tabbed content
 
-You can use the [queryString](https://docusaurus.io/docs/next/markdown-features/tabs?current-os=ios#query-string) prop in the `<Tabs>` tag. This allows you to share a link to a page with a pre-selected tab so that clicking on a tab creates a unique hyperlink for that tab. However, this feature doesn't provide an anchor link, which means the browser won't scroll to the tab. Additionally, you can define the search parameter name to use. If the tabs content is under a header, you can alternatively link to the header itself, instaed of the `queryString` prop.
+You can use the [queryString](https://docusaurus.io/docs/next/markdown-features/tabs?current-os=ios#query-string) prop in the `<Tabs>` tag. This allows you to share a link to a page with a pre-selected tab so that clicking on a tab creates a unique hyperlink for that tab. However, this feature doesn't provide an anchor link, which means the browser won't scroll to the tab. Additionally, you can define the search parameter name to use. If the tabs content is under a header, you can alternatively link to the header itself, instead of the `queryString` prop.
 
 In the following example, clicking a tab adds a search parameter to the end of the URL: `?current-os=android or ?current-os=ios`.
 
-```
+```sql
 <Tabs queryString="current-os">
   <TabItem value="android" label="Android">
     Android
@@ -105,3 +105,48 @@ In the following example, clicking a tab adds a search parameter to the end of t
   </TabItem>
 </Tabs>
 ```
+
+## Markdown Links
+
+Refer to the <a href="https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md#Links" target="_blank" rel="noreferrer">Links section</a> of the Content Style Guide to read about how you can use links in the dbt product documentation.
+
+## Collapsible header
+
+<Collapsible header="The header info">
+    <div>
+        <p>Shows and hides children elements</p>
+    </div>
+</Collapsible>
+
+```markdown
+<Collapsible header="The header info">
+<div>
+<p>Shows and hides children elements</p>
+</div>
+</Collapsible>
+</div>
+```
+
+## File component
+
+```yml
+<File name="~/.dbt/profiles.yml">
+
+```yaml
+password: hunter2
+```
+</File>
+```
+
+## LoomVideo component
+
+<pre>{`<LoomVideo id="09919ddb02e44015878c9e93e15fe792" />`}</pre>
+
+<LoomVideo id="09919ddb02e44015878c9e93e15fe792" />
+
+## YoutubeVideo component
+
+<pre>{`<YoutubeVideo id="5yyGT1k2xzY" />`}</pre>
+
+<YoutubeVideo id="5yyGT1k2xzY" />
+

website/docs/docs/build/data-tests.md

@@ -66,9 +66,25 @@ having total_amount < 0
 
 </File>
 
-The name of this test is the name of the file: `assert_total_payment_amount_is_positive`. Simple enough.
+The name of this test is the name of the file: `assert_total_payment_amount_is_positive`.
 
-Singular data tests are easy to write—so easy that you may find yourself writing the same basic structure over and over, only changing the name of a column or model. By that point, the test isn't so singular! In that case, we recommend...
+To add a data test to your project, add a `.yml` file to your `tests` directory, for example, `tests/schema.yml` with the following content:
+
+<File name='tests/schema.yml'>
+
+```yaml
+version: 2
+data_tests:
+  - name: assert_total_payment_amount_is_positive
+    description: >
+      Refunds have a negative amount, so the total amount should always be >= 0.
+      Therefore return records where total amount < 0 to make the test fail.
+
+```
+
+</File>
+
+Singular data tests are so easy that you may find yourself writing the same basic structure repeatedly, only changing the name of a column or model. By that point, the test isn't so singular! In that case, we recommend generic data tests.
 
 ## Generic data tests
 Certain data tests are generic: they can be reused over and over again. A generic data test is defined in a `test` block, which contains a parametrized query and accepts arguments. It might look like:

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

@@ -94,7 +94,7 @@ Not specifying a `unique_key` will result in append-only behavior, which means d
 
 The optional `unique_key` parameter specifies a field (or combination of fields) that defines 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.
 
-The `unique_key` should be supplied in your model definition as a string representing a single column or a list of single-quoted column names that can be used together, for example, `['col1', 'col2', …])`. Columns used in this way should not contain any nulls, or the incremental model run may fail. Either ensure that each column has no nulls (for example with `coalesce(COLUMN_NAME, 'VALUE_IF_NULL')`), or define a single-column [surrogate key](https://www.getdbt.com/blog/guide-to-surrogate-key) (for example with [`dbt_utils.generate_surrogate_key`](https://github.com/dbt-labs/dbt-utils#generate_surrogate_key-source)).
+The `unique_key` should be supplied in your model definition as a string representing a single column or a list of single-quoted column names that can be used together, for example, `['col1', 'col2', …])`. Columns used in this way should not contain any nulls, or the incremental model may fail to match rows and generate duplicate rows. Either ensure that each column has no nulls (for example with `coalesce(COLUMN_NAME, 'VALUE_IF_NULL')`) or define a single-column [surrogate key](https://www.getdbt.com/blog/guide-to-surrogate-key) (for example with [`dbt_utils.generate_surrogate_key`](https://github.com/dbt-labs/dbt-utils#generate_surrogate_key-source)).
 
 :::tip
 In cases where you need multiple columns in combination to uniquely identify each row, we recommend you pass these columns as a list (`unique_key = ['user_id', 'session_number']`), rather than a string expression (`unique_key = 'concat(user_id, session_number)'`).

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

@@ -107,6 +107,6 @@ You can read more about each of these behavior changes in the following links:
 We also made some quality-of-life improvements in Core 1.9, enabling you to:
 
 - Maintain data quality now that dbt returns an an error (versioned models) or warning (unversioned models) when someone [removes a contracted model by deleting, renaming, or disabling](/docs/collaborate/govern/model-contracts#how-are-breaking-changes-handled) it.
-- Document [singular data tests](/docs/build/data-tests#document-singular-tests).
+- Document [singular data tests](/docs/build/data-tests#singular-data-tests).
 - Use `ref` and `source` in [foreign key constraints](/reference/resource-properties/constraints).
 - Use `dbt test` with the `--resource-type` / `--exclude-resource-type` flag, making it possible to include or exclude data tests (`test`) or unit tests (`unit_test`).

website/docs/reference/commands/build.md

@@ -31,32 +31,9 @@ In DAG order, for selected resources or an entire project.
 
 The `build` command supports the `--empty` flag for building schema-only dry runs. The `--empty` flag limits the refs and sources to zero rows. dbt will still execute the model SQL against the target data warehouse but will avoid expensive reads of input data. This validates dependencies and ensures your models will build properly.
 
-#### SQL compilation error when running the `--empty` flag on a model
-
-If you encounter the error: `SQL compilation error: syntax error line 1 at position 21 unexpected '('.` when running a model with the `--empty` flag, explicitly call the `.render()` method on that relation.
-
-
-<File name='models.sql'>
-
-```Jinja
-
--- models/staging/stg_sys__customers.sql
-{{ config(
-    pre_hook = [
-        "alter external table {{ source('sys', 'customers').render() }} refresh"
-    ]
-) }}
-
-with cus as (
-    select * from {{ source("sys", "customers") }} -- leave this as is!
-)
-
-select * from cus
-
-```
-
-</File>
+import SQLCompilationError from '/snippets/_render-method.md';
 
+<SQLCompilationError />
 
 ## Tests
 

website/docs/reference/resource-configs/bigquery-configs.md

@@ -265,7 +265,7 @@ If your model has `partition_by` configured, you may optionally specify two addi
 
 </File>
 
-### Clustering Clause
+### Clustering clause
 
 BigQuery tables can be [clustered](https://cloud.google.com/bigquery/docs/clustered-tables) to colocate related data.
 
@@ -286,7 +286,7 @@ select * from ...
 
 </File>
 
-Clustering on a multiple columns:
+Clustering on multiple columns:
 
 <File name='bigquery_table.sql'>
 
@@ -303,11 +303,11 @@ select * from ...
 
 </File>
 
-## Managing KMS Encryption
+## Managing KMS encryption
 
 [Customer managed encryption keys](https://cloud.google.com/bigquery/docs/customer-managed-encryption) can be configured for BigQuery tables using the `kms_key_name` model configuration.
 
-### Using KMS Encryption
+### Using KMS encryption
 
 To specify the KMS key name for a model (or a group of models), use the `kms_key_name` model configuration. The following example sets the `kms_key_name` for all of the models in the `encrypted/` directory of your dbt project.
 
@@ -328,7 +328,7 @@ models:
 
 </File>
 
-## Labels and Tags
+## Labels and tags
 
 ### Specifying labels
 
@@ -373,8 +373,6 @@ models:
 
 </File>
 
-
-
 <Lightbox src="/img/docs/building-a-dbt-project/building-models/73eaa8a-Screen_Shot_2020-01-20_at_12.12.54_PM.png" title="Viewing labels in the BigQuery console"/>
 
 ### Specifying tags
@@ -434,7 +432,7 @@ The `incremental_strategy` config can be set to one of two values:
 ### Performance and cost
 
 The operations performed by dbt while building a BigQuery incremental model can
-be made cheaper and faster by using [clustering keys](#clustering-keys) in your
+be made cheaper and faster by using a [clustering clause](#clustering-clause) in your
 model configuration. See [this guide](https://discourse.getdbt.com/t/benchmarking-incremental-strategies-on-bigquery/981) for more information on performance tuning for BigQuery incremental models.
 
 **Note:** These performance and cost benefits are applicable to incremental models
@@ -673,7 +671,7 @@ select ...
 
 </File>
 
-## Authorized Views
+## Authorized views
 
 If the `grant_access_to` config is specified for a model materialized as a
 view, dbt will grant the view model access to select from the list of datasets

website/docs/reference/resource-configs/pre-hook-post-hook.md

@@ -154,6 +154,10 @@ Pre- and post-hooks can also call macros that return SQL statements. If your mac
 
 dbt aims to provide all the boilerplate SQL you need (DDL, DML, and DCL) via out-of-the-box functionality, which you can configure quickly and concisely. In some cases, there may be SQL that you want or need to run, specific to functionality in your data platform, which dbt does not (yet) offer as a built-in feature. In those cases, you can write the exact SQL you need, using dbt's compilation context, and pass it into a `pre-` or `post-` hook to run before or after your model, seed, or snapshot.
 
+import SQLCompilationError from '/snippets/_render-method.md';
+
+<SQLCompilationError />
+
 ## Examples
 
 <Snippet path="hooks-to-grants" />

website/docusaurus.config.js

@@ -205,6 +205,7 @@ var siteSettings = {
             src="https://solve-widget.forethought.ai/embed.js" id="forethought-widget-embed-script" data-api-key="9d421bf3-96b8-403e-9900-6fb059132264" 
             data-ft-workflow-tag="docs" 
             config-ft-greeting-message="Welcome to dbt Product docs! Ask a question."
+            config-ft-widget-header-title = "Ask a question"
           ></script>
 
           <div class='footer__items'>

website/snippets/_render-method.md

@@ -0,0 +1,17 @@
+#### The render method
+
+The `.render()` method is generally used to resolve or evaluate Jinja expressions (such as `{{ source(...) }}`) during runtime. 
+
+When using the `--empty flag`, dbt may skip processing `ref()` or `source()` for optimization. To avoid compilation errors and to explicitly tell dbt to process a specific relation (`ref()` or `source()`), use the `.render()` method in your model file. For example:
+
+
+<File name='models.sql'>
+
+```Jinja
+{{ config(
+    pre_hook = [
+        "alter external table {{ source('sys', 'customers').render() }} refresh"
+    ]
+```
+
+</File>