Update metrics + exposures #2052

website/docs/docs/building-a-dbt-project/exposures.md

@@ -82,7 +82,3 @@ When we generate our documentation site, you'll see the exposure appear:
 
 <Lightbox src="/img/docs/building-a-dbt-project/dbt-docs-exposures.png" title="Dedicated page in dbt-docs for each exposure"/>
 <Lightbox src="/img/docs/building-a-dbt-project/dag-exposures.png" title="Exposures appear as orange-y nodes in the DAG"/>
-
-## Exposures are new!
-
-Exposures were introduced in dbt v0.18.1, with a limited set of supported types and properties. If you're interested in requesting or contributing additional properties, check out issue [dbt#2835](https://github.com/dbt-labs/dbt-core/issues/2835).

website/docs/docs/building-a-dbt-project/metrics.md

@@ -33,7 +33,12 @@ As with Exposures, you can see everything that rolls up into a metric (`dbt ls -
 
 ## Defining a metric
 
-You can define metrics in `.yml` files nested under a `metrics:` key.
+You can define metrics in `.yml` files nested under a `metrics:` key. Metric names must:
+- contain only letters, numbers, and underscores (no spaces or special characters)
+- begin with a letter
+- contain no more than 250 characters
+
+For a short human-friendly name with title casing, spaces, and special characters, use the `label` property.
 
 ### Example definition
 
@@ -54,7 +59,7 @@ metrics:
   - name: rolling_new_customers
     label: New Customers
     model: ref('dim_customers')
-    description: "The 14 day rolling count of paying customers using the product"
+    [description](description): "The 14 day rolling count of paying customers using the product"
 
     calculation_method: count_distinct
     expression: user_id # superfluous here, but shown as an example
@@ -81,9 +86,13 @@ metrics:
       - field: signup_date
         operator: '>='
         value: "'2020-01-01'"
+
+    # general properties
+    [config](resource-properties/config):
+      enabled: true | false
+      treat_null_values_as_zero: true | false
 
-
-    meta: {team: Finance}
+    [meta](resource-configs/meta): {team: Finance}
 ```
 </VersionBlock> 
 
@@ -128,7 +137,6 @@ metrics:
         operator: '>='
         value: "'2020-01-01'"
 
-
     meta: {team: Finance}
 ```
 </VersionBlock> 
@@ -147,12 +155,13 @@ Metrics can have many declared **properties**, which define aspects of your metr
 | model       | The dbt model that powers this metric                       | dim_customers                   | yes (no for `derived` metrics)|
 | label       | A short for name / label for the metric                     | New Customers                   | no        |
 | description | Long form, human-readable description for the metric        | The number of customers who.... | no        |
-|calculation_method | The method of calculation (aggregation or derived) that is applied to the expression  | count_distinct | yes       |
+| calculation_method | The method of calculation (aggregation or derived) that is applied to the expression  | count_distinct | yes       |
 | expression | The expression to aggregate/calculate over | user_id | yes       |
 | timestamp   | The time-based component of the metric                      | signup_date                     | yes       |
 | time_grains | One or more "grains" at which the metric can be evaluated   | [day, week, month]              | yes       |
 | dimensions  | A list of dimensions to group or filter the metric by       | [plan, country]                 | no        |
 | filters     | A list of filters to apply before calculating the metric    | See below                       | no        |
+| config      | [Optional configurations](https://github.com/dbt-labs/dbt_metrics#accepted-metric-configurations) for calculating this metric         | {treat_null_values_as_zero: true} | no      |
 | meta        | Arbitrary key/value store                                   | {team: Finance}                 | no        |
 
 </VersionBlock>
@@ -420,8 +429,8 @@ from {{ metrics.develop(
 
 **Important caveat** - The metric list input for the `metrics.develop` macro takes in the metric names themselves, not the `metric('name')` statement that the `calculate` macro uses. Using the example above:
 
-✅ `['develop_metric']`
-❌ `[metric('develop_metric')]`
+- ✅ `['develop_metric']`
+- ❌ `[metric('develop_metric')]`
 
 </VersionBlock>
 

website/docs/reference/exposure-properties.md

@@ -17,13 +17,19 @@ Exposures are defined in `.yml` files nested under an `exposures:` key. You may
 
 You can name these files `whatever_you_want.yml`, and nest them arbitrarily deeply in subfolders within the `models/` directory.
 
+<VersionBlock firstVersion="1.3">
+
+Exposure names must contain only letters, numbers, and underscores (no spaces or special characters). For a short human-friendly name with title casing, spaces, and special characters, use the `label` property.
+
+</VersionBlock>
+
 <File name='models/<filename>.yml'>
 
 ```yml
 version: 2
 
 exposures:
-  - name: <string>
+  - name: <string_with_underscores>
     [description](description): <markdown_string>
     type: {dashboard, notebook, analysis, ml, application}
     url: <string>
@@ -38,6 +44,11 @@ exposures:
       - ref('model')
       - ref('seed')
       - source('name', 'table')
+
+    # added in dbt Core v1.3
+    label: "Human-Friendly Name for this Exposure!"
+    [config](resource-properties/config):
+      enabled: true | false
 
   - name: ... # declare properties of additional exposures
 ```
@@ -52,6 +63,7 @@ exposures:
 exposures:
 
   - name: weekly_jaffle_metrics
+    label: Jaffles by the Week              # optional, new in dbt Core v1.3
     type: dashboard                         # required
     maturity: high                          # optional
     url: https://bi.tool/dashboards/1       # optional

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

@@ -11,6 +11,9 @@ default_value: true
     { label: 'Seeds', value: 'seeds', },
     { label: 'Snapshots', value: 'snapshots', },
     { label: 'Tests', value: 'tests', },
+    { label: 'Sources', value: 'sources', },
+    { label: 'Metrics', value: 'metrics', },
+    { label: 'Exposures', value: 'exposures', },
   ]
 }>
 <TabItem value="models">
@@ -133,6 +136,121 @@ tests:
 
 </TabItem>
 
+<TabItem value="sources">
+
+<File name='dbt_project.yml'>
+
+```yaml
+sources:
+  [<resource-path>](resource-path):
+    [+](plus-prefix)enabled: true | false
+
+```
+
+</File>
+
+<VersionBlock firstVersion="1.1">
+
+<File name='models/properties.yml'>
+
+```yaml
+version: 2
+
+sources:
+  - name: [<source-name>]
+    [config](resource-properties/config):
+      enabled: true | false
+    tables:
+      - name: [<source-table-name>]
+        [config](resource-properties/config):
+          enabled: true | false
+
+```
+
+</File>
+
+</VersionBlock>
+
+</TabItem>
+
+<TabItem value="metrics">
+
+<VersionBlock lastVersion="1.2">
+
+Support for disabling metrics was added in dbt Core v1.3
+
+</VersionBlock>
+
+<VersionBlock firstVersion="1.3">
+
+<File name='dbt_project.yml'>
+
+```yaml
+metrics:
+  [<resource-path>](resource-path):
+    [+](plus-prefix)enabled: true | false
+
+```
+
+</File>
+
+<File name='models/metrics.yml'>
+
+```yaml
+version: 2
+
+metrics:
+  - name: [<metric-name>]
+    [config](resource-properties/config):
+      enabled: true | false
+
+```
+
+</File>
+
+</VersionBlock>
+
+</TabItem>
+
+<TabItem value="exposures">
+
+<VersionBlock lastVersion="1.2">
+
+Support for disabling exposures was added in dbt Core v1.3
+
+</VersionBlock>
+
+<VersionBlock firstVersion="1.3">
+
+<File name='dbt_project.yml'>
+
+```yaml
+exposures:
+  [<resource-path>](resource-path):
+    [+](plus-prefix)enabled: true | false
+
+```
+
+</File>
+
+<File name='models/exposures.yml'>
+
+```yaml
+version: 2
+
+exposures:
+  - name: [<exposure-name>]
+    [config](resource-properties/config):
+      enabled: true | false
+
+```
+
+</File>
+
+</VersionBlock>
+
+</TabItem>
+
 </Tabs>
 
 ## Definition

website/docs/reference/resource-properties/config.md

@@ -1,5 +1,5 @@
 ---
-resource_types: [models, seeds, snapshots, tests]
+resource_types: [models, seeds, snapshots, tests, sources, metrics, exposures]
 datatype: "{dictionary}"
 ---
 
@@ -14,6 +14,9 @@ datatype: "{dictionary}"
     { label: 'Seeds', value: 'seeds', },
     { label: 'Snapshots', value: 'snapshots', },
     { label: 'Tests', value: 'tests', },
+    { label: 'Sources', value: 'sources', },
+    { label: 'Metrics', value: 'metrics', },
+    { label: 'Exposures', value: 'exposures', },
   ]
 }>
 
@@ -104,6 +107,91 @@ version: 2
 
 </TabItem>
 
+<TabItem value="sources">
+
+<VersionBlock lastVersion="1.0">
+
+Support for the `config` property on sources was added in dbt Core v1.1
+
+</VersionBlock>
+
+<VersionBlock firstVersion="1.1">
+
+<File name='models/<filename>.yml'>
+
+```yml
+version: 2
+
+sources:
+  - name: <source_name>
+    config:
+      [<source_config>](source-configs): <config_value>
+    tables:
+      - name: <table_name>
+        config:
+          [<source_config>](source-configs): <config_value>
+```
+
+</File>
+
+</VersionBlock>
+
+</TabItem>
+
+<TabItem value="metrics">
+
+<VersionBlock lastVersion="1.2">
+
+Support for the `config` property on metrics was added in dbt Core v1.3
+
+</VersionBlock>
+
+<VersionBlock firstVersion="1.3">
+
+<File name='models/<filename>.yml'>
+
+```yml
+version: 2
+
+metrics:
+  - name: <metric_name>
+    config:
+      enabled: true | false
+```
+
+</File>
+
+</VersionBlock>
+
+</TabItem>
+
+<TabItem value="exposures">
+
+<VersionBlock lastVersion="1.2">
+
+Support for the `config` property on `metrics` was added in dbt Core v1.3
+
+</VersionBlock>
+
+<VersionBlock firstVersion="1.3">
+
+<File name='models/<filename>.yml'>
+
+```yml
+version: 2
+
+exposures:
+  - name: <exposure_name>
+    config:
+      enabled: true | false
+```
+
+</File>
+
+</VersionBlock>
+
+</TabItem>
+
 </Tabs>
 
 The `config` property allows you to configure resources at the same time you're defining properties in yaml files.