Merge pull request #915 from dbt-labs/joellabes-patch-1

Add filter examples to metrics
dbt-labs · Jan 14, 2022 · 224c100 · 224c100
2 parents ad00c75 + 5c5d3ce
commit 224c100
Showing 1 changed file with 42 additions and 18 deletions.
diff --git a/website/docs/docs/building-a-dbt-project/metrics.md b/website/docs/docs/building-a-dbt-project/metrics.md
@@ -73,30 +73,54 @@ metrics:
 
     filters:
       - field: is_paying
-        value: true
+        operator: 'is'
+        value: 'true'
+      - field: lifetime_value
+        operator: '>='
+        value: '100'
+      - field: company_name
+        operator: '!='
+        value: "'Acme, Inc'"
+
 
     meta: {team: Finance}
 ```
 
 </File>
 
-### Metrics properties
-
-You can see how these properties are used in the [example YAML file](#declaring-a-metric).
-
-| Field       | Description                                               | Example                           | Required? |
-|-------------|-----------------------------------------------------------|-----------------------------------|-----------|
-| name        | Unique identifier for the metric                          | new_customers                     | Yes       |
-| model       | The dbt model that powers this metric                     | dim_customers                     | Yes       |
-| label       | A short name / label for the metric                       | New Customers                     | No        |
-| description | Long form, human-readable description for the metric      | "The number of paid customers..." | No        |
-| type        | Type of calculation to perform when evaluating a metric   | count_distinct                    | Yes       |
-| sql         | Expression to aggregate or calculate over                 | user_id                           | Yes       |
-| timestamp   | 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  | List of dimensions to group or filter the metric by       | plan <br/> country                | No        |
-| filters     | List of filters to apply before calculating the metric    | field: is_paying<br/>value: true  | No        |
-| meta        | Arbitrary key/value store                                 | {team: Finance}                   | No        |
+### Available properties
+
+| Field       | Description                                                 | Example                         | Required? |
+|-------------|-------------------------------------------------------------|---------------------------------|-----------|
+| name        | A unique identifier for the metric                          | new_customers                   | yes       |
+| model       | The dbt model that powers this metric                       | dim_customers                   | yes       |
+| 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        |
+| type        | The type of calculation to perform when evaluating a metric | count_distinct                  | yes       |
+| sql         | 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        |
+| meta        | Arbitrary key/value store                                   | {team: Finance}                 | no        |
+
+### Filters
+Filters should be defined as a list of dictionaries that define predicates for the metric. Filters are combined using AND clauses. For more control, users can (and should) include the complex logic in the model powering the metric.
+
+Note that `value` must be defined as a string in YAML, because it will be compiled into queries as part of a string. If your filter's value needs to be surrounded in quotes inside the query, use `"'nested'"` quotes:
+
+```yml
+    filters:
+      - field: is_paying
+        operator: 'is'
+        value: 'true'
+      - field: lifetime_value
+        operator: '>='
+        value: '100'
+      - field: company_name
+        operator: '!='
+        value: "'Acme, Inc'"
+```
 
 ## Ongoing discussions