Add filter examples to metrics

[joellabes]

Description & motivation

This metrics documentation is largely a copy-paste from the parent GH spec, and said "see below" for filter examples but there was no below. Now there is.

@drewbanin a couple of questions where the implementation diverged from the spec:

• Is operator always required, or is it assumed to be "=" if not specified?
• for is_paying is true, is "is" required as an operator, and would it need to be " is "? (The latter in particular would be icky)
• 1.0.0-rc1 rejected true without quotes because True is not of type 'string'. Likewise for ltv >= 100. Is that overly aggressive type expectations? (cc @jtcohen6 - I can open an issue on the core repo if so)

Pre-release docs

Is this change related to an unreleased version of dbt?

• Yes: please
  • update the base branch to next
  • add Changelog components: <Changelog>[New/Changed] in v0.x.0</Changelog>
  • add links to the "New and changed documentation" section of the latest Migration Guide
• No: please ensure the base branch is current
• Unsure: we'll let you know!

[jtcohen6]

@joellabes Thanks for playing around with metrics, and for the great feedback!

This metrics documentation is largely a copy-paste from the parent GH spec, and said "see below" for filter examples but there was no below.

You caught me :)

Quick answers from my perspective:

Is operator always required, or is it assumed to be "=" if not specified?

There's no default defined within dbt, and this is a required property, so it will raise an error if not provided. A downstream tool or macro which leverages this metric definition could assume a default operator when not provided, but I could also imagine a filter like this, given that (on many databases) where is_bool_col is valid shorthand for where is_bool_col is true:

      filters:
        - field: is_bool_col
          operator: ""
          value: ""

for is_paying is true, is "is" required as an operator, and would it need to be " is "? (The latter in particular would be icky)

I think the spacing would be the responsibility of the downstream tool / macro. Hopefully they'd be kind enough to template the query with lenient whitespace:

where
{% for filter in filters %}
    {{ filter.field }} {{ filter.operator }} {{ filter.value }}
    {{ "and" if not loop.last }}
{% endfor %}

1.0.0-rc1 rejected true without quotes because True is not of type 'string'. Likewise for ltv >= 100. Is that overly aggressive type expectations?

Yes, that's an open TODO right now. I think we encountered validation issues with making this accept absolutely Anything, but I think we could change it to accept any reasonable data type:

    value: Union[str, int, float, bool]  # others i'm not thinking of right now

It's definitely workable to just use strings ('true', '100') in the meantime, but I think this would be an uncontroversial improvement. Mind opening an issue for it? (Note to self: this would constitute an artifact schema change, and require us to update manifest v4 at schemas.getdbt.com.)

[joellabes]

There's no default defined within dbt, and this is a required property, so it will raise an error if not provided

Lovely! I'll update these docs accordingly.

It's definitely workable to just use strings ('true', '100') in the meantime, but I think this would be an uncontroversial improvement

Yeah it'd be good to open it up ASAP, because otherwise we'll need to document it as "put everything in quotes, and your strings in "'double quotes'" so that one set of quotes makes it through to Jinja", right?

Mind opening an issue for it?

dbt-labs/dbt-core#4294

[runleonarun]

Just a few tiny comments/questions.

[runleonarun]

Hi @joellabes just some fly by questions here!

Filters are ANDed together

Does this mean that when you provide multiple filters they will use AND logic, meaning all criteria must be met? It might help newer users and users who aren't native English speakers to expand this sentence just a bit! (Although I do appreciate how efficient this sentence is. ❤️ )

...pushing that logic down into the underlying model.

I'm also curious about this phrase. Do we talk more anywhere on how to do this? Can we link people to this?

[joellabes]

Does this mean that when you provide multiple filters they will use AND logic

Yep! happy to have it changed to anything else - none of this is my writing so I'm even less precious about it than normal 😉

I'm also curious about this phrase
Basically, instead of trying to implement more complex filters in the metric definition, we're expecting people to do their complex filtering inside of the model (in this example, ref('dim_customers')). I don't know if there's prior art we can link people out to :(

[netlify]

✔️ Deploy Preview for docs-getdbt-com ready!

🔨 Explore the source changes: 5c5d3ce

🔍 Inspect the deploy log: https://app.netlify.com/sites/docs-getdbt-com/deploys/61e0c1e4db5ce1000745d640

😎 Browse the preview: https://deploy-preview-915--docs-getdbt-com.netlify.app

[joellabes]

@runleonarun could you have a peek at this too please?

[runleonarun]

LGTM!