Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add required and type to sm and metrics #6534

Merged
merged 18 commits into from
Nov 25, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 23 additions & 23 deletions website/docs/docs/build/conversion-metrics.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,28 +20,28 @@ The specification for conversion metrics is as follows:
Note that we use the double colon (::) to indicate whether a parameter is nested within another parameter. So for example, `query_params::metrics` means the `metrics` parameter is nested under `query_params`.
:::

| Parameter | Description | Type |
| --- | --- | --- |
| `name` | The name of the metric. | Required |
| `description` | The description of the metric. | Optional |
| `type` | The type of metric (such as derived, ratio, and so on.). In this case, set as 'conversion' | Required |
| `label` | Required string that defines the display value in downstream tools. Accepts plain text, spaces, and quotes (such as `orders_total` or `"orders_total"`). | Required |
| `type_params` | Specific configurations for each metric type. | Required |
| `conversion_type_params` | Additional configuration specific to conversion metrics. | Required |
| `entity` | The entity for each conversion event. | Required |
| `calculation` | Method of calculation. Either `conversion_rate` or `conversions`. Defaults to `conversion_rate`. | Optional |
| `base_measure` | A list of base measure inputs | Required |
| `base_measure:name` | The base conversion event measure. | Required |
| `base_measure:fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | Optional |
| `base_measure:join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional |
| `conversion_measure` | A list of conversion measure inputs. | Required |
| `conversion_measure:name` | The base conversion event measure.| Required |
| `conversion_measure:fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | Optional |
| `conversion_measure:join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional |
| `window` | The time window for the conversion event, such as 7 days, 1 week, 3 months. Defaults to infinity. | Optional |
| `constant_properties` | List of constant properties. | Optional |
| `base_property` | The property from the base semantic model that you want to hold constant. | Optional |
| `conversion_property` | The property from the conversion semantic model that you want to hold constant. | Optional |
| Parameter | Description | Required | Type |
| --- | --- | --- | --- |
| `name` | The name of the metric. | Required | String |
| `description` | The description of the metric. | Optional | String |
| `type` | The type of metric (such as derived, ratio, and so on.). In this case, set as 'conversion'. | Required | String |
| `label` | Required string that defines the display value in downstream tools. Accepts plain text, spaces, and quotes (such as `orders_total` or `"orders_total"`). | Required | String |
| `type_params` | Specific configurations for each metric type. | Required | Dict |
| `conversion_type_params` | Additional configuration specific to conversion metrics. | Required | Dict |
| `entity` | The entity for each conversion event. | Required | String |
| `calculation` | Method of calculation. Either `conversion_rate` or `conversions`. Defaults to `conversion_rate`. | Optional | String |
| `base_measure` | A list of base measure inputs. | Required | Dict |
| `base_measure:name` | The base conversion event measure. | Required | String |
| `base_measure:fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | Optional | String |
| `base_measure:join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | Boolean |
| `conversion_measure` | A list of conversion measure inputs. | Required | Dict |
| `conversion_measure:name` | The base conversion event measure.| Required | String |
| `conversion_measure:fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | Optional | String |
| `conversion_measure:join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | Boolean |
| `window` | The time window for the conversion event, such as 7 days, 1 week, 3 months. Defaults to infinity. | Optional | String |
| `constant_properties` | List of constant properties. | Optional | List |
| `base_property` | The property from the base semantic model that you want to hold constant. | Optional | String |
| `conversion_property` | The property from the conversion semantic model that you want to hold constant. | Optional | String |

Refer to [additional settings](#additional-settings) to learn how to customize conversion metrics with settings for null values, calculation type, and constant properties.

Expand Down Expand Up @@ -111,7 +111,7 @@ Next, define a conversion metric as follows:
base_measure:
name: visits
fill_nulls_with: 0
conversion_measure: sellers
conversion_measure:
name: sellers
entity: user
window: 7 days
Expand Down
30 changes: 15 additions & 15 deletions website/docs/docs/build/cumulative-metrics.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,21 +18,21 @@ Note that we use the double colon (::) to indicate whether a parameter is nested

<VersionBlock firstVersion="1.9">

| Parameter | <div style={{width:'350px'}}>Description</div> | Type |
|-------------|---------------------------------------------------|-----------|
| `name` | The name of the metric. | Required |
| `description` | The description of the metric. | Optional |
| `type` | The type of the metric (cumulative, derived, ratio, or simple). | Required |
| `label` | Required string that defines the display value in downstream tools. Accepts plain text, spaces, and quotes (such as `orders_total` or `"orders_total"`). | Required |
| `type_params` | The type parameters of the metric. Supports nested parameters indicated by the double colon, such as `type_params::measure`. | Required |
| `type_params::measure` | The measure associated with the metric. Supports both shorthand (string) and object syntax. The shorthand is used if only the name is needed, while the object syntax allows specifying additional attributes. | Required |
| `measure::name` | The name of the measure being referenced. Required if using object syntax for `type_params::measure`. | Optional |
| `measure::fill_nulls_with` | Sets a value (for example, 0) to replace nulls in the metric definition. | Optional |
| `measure::join_to_timespine` | Boolean indicating if the aggregated measure should be joined to the time spine table to fill in missing dates. Default is `false`. | Optional |
| `type_params::cumulative_type_params` | Configures the attributes like `window`, `period_agg`, and `grain_to_date` for cumulative metrics. | Optional |
| `cumulative_type_params::window` | Specifies the accumulation window, such as `1 month`, `7 days`, or `1 year`. Cannot be used with `grain_to_date`. | Optional |
| `cumulative_type_params::grain_to_date` | Sets the accumulation grain, such as `month`, restarting accumulation at the beginning of each specified grain period. Cannot be used with `window`. | Optional |
| `cumulative_type_params::period_agg` | Defines how to aggregate the cumulative metric when summarizing data to a different granularity: `first`, `last`, or `average`. Defaults to `first` if `window` is not specified. | Optional |
| Parameter | <div style={{width:'350px'}}>Description</div> | Required | Type |
|-------------|---------------------------------------------------|----------|-----------|
| `name` | The name of the metric. | Required | String |
| `description` | The description of the metric. | Optional | String |
| `type` | The type of the metric (cumulative, derived, ratio, or simple). | Required | String |
| `label` | Required string that defines the display value in downstream tools. Accepts plain text, spaces, and quotes (such as `orders_total` or `"orders_total"`). | Required | String |
| `type_params` | The type parameters of the metric. Supports nested parameters indicated by the double colon, such as `type_params::measure`. | Required | Dict |
| `type_params::measure` | The measure associated with the metric. Supports both shorthand (string) and object syntax. The shorthand is used if only the name is needed, while the object syntax allows specifying additional attributes. | Required | Dict |
| `measure::name` | The name of the measure being referenced. Required if using object syntax for `type_params::measure`. | Optional | String |
| `measure::fill_nulls_with` | Sets a value (for example, 0) to replace nulls in the metric definition. | Optional | Integer or string |
| `measure::join_to_timespine` | Boolean indicating if the aggregated measure should be joined to the time spine table to fill in missing dates. Default is `false`. | Optional | Boolean |
| `type_params::cumulative_type_params` | Configures the attributes like `window`, `period_agg`, and `grain_to_date` for cumulative metrics. | Optional | Dict |
| `cumulative_type_params::window` | Specifies the accumulation window, such as `1 month`, `7 days`, or `1 year`. Cannot be used with `grain_to_date`. | Optional | String |
| `cumulative_type_params::grain_to_date` | Sets the accumulation grain, such as `month`, restarting accumulation at the beginning of each specified grain period. Cannot be used with `window`. | Optional | String |
| `cumulative_type_params::period_agg` | Defines how to aggregate the cumulative metric when summarizing data to a different granularity: `first`, `last`, or `average`. Defaults to `first` if `window` is not specified. | Optional | String |

</VersionBlock>

Expand Down
24 changes: 12 additions & 12 deletions website/docs/docs/build/derived-metrics.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,18 +10,18 @@ In MetricFlow, derived metrics are metrics created by defining an expression usi

The parameters, description, and type for derived metrics are:

| Parameter | Description | Type |
| --------- | ----------- | ---- |
| `name` | The name of the metric. | Required |
| `description` | The description of the metric. | Optional |
| `type` | The type of the metric (cumulative, derived, ratio, or simple). | Required |
| `label` | Required string that defines the display value in downstream tools. Accepts plain text, spaces, and quotes (such as `orders_total` or `"orders_total"`). | Required |
| `type_params` | The type parameters of the metric. | Required |
| `expr` | The derived expression. You see validation warnings when the derived metric is missing an `expr` or the `expr` does not use all the input metrics. | Required |
| `metrics` | The list of metrics used in the derived metrics. | Required |
| `alias` | Optional alias for the metric that you can use in the expr. | Optional |
| `filter` | Optional filter to apply to the metric. | Optional |
| `offset_window` | Set the period for the offset window, such as 1 month. This will return the value of the metric one month from the metric time. | Optional |
| Parameter | Description | Required | Type |
| --------- | ----------- | ---- | ---- |
| `name` | The name of the metric. | Required | String |
| `description` | The description of the metric. | Optional | String |
| `type` | The type of the metric (cumulative, derived, ratio, or simple). | Required | String |
| `label` | Defines the display value in downstream tools. Accepts plain text, spaces, and quotes (such as `orders_total` or `"orders_total"`). | Required | String |
| `type_params` | The type parameters of the metric. | Required | Dict |
| `expr` | The derived expression. You'll see validation warnings when the derived metric is missing an `expr` or the `expr` does not use all the input metrics. | Required | String |
| `metrics` | The list of metrics used in the derived metrics. Each entry can include optional fields like `alias`, `filter`, or `offset_window`. | Required | List |
| `alias` | Optional alias for the metric that you can use in the `expr`. | Optional | String |
| `filter` | Optional filter to apply to the metric. | Optional | String |
| `offset_window` | Set the period for the offset window, such as 1 month. This will return the value of the metric one month from the metric time. | Optional | String |


The following displays the complete specification for derived metrics, along with an example.
Expand Down
16 changes: 8 additions & 8 deletions website/docs/docs/build/dimensions.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,14 @@ Groups are defined within semantic models, alongside entities and measures, and

All dimensions require a `name`, `type`, and can optionally include an `expr` parameter. The `name` for your Dimension must be unique within the same semantic model.

| Parameter | Description | Type |
| --------- | ----------- | ---- |
| `name` | Refers to the name of the group that will be visible to the user in downstream tools. It can also serve as an alias if the column name or SQL query reference is different and provided in the `expr` parameter. <br /><br /> Dimension names should be unique within a semantic model, but they can be non-unique across different models as MetricFlow uses [joins](/docs/build/join-logic) to identify the right dimension. | Required |
| `type` | Specifies the type of group created in the semantic model. There are two types:<br /><br />- **Categorical**: Describe attributes or features like geography or sales region. <br />- **Time**: Time-based dimensions like timestamps or dates. | Required |
| `type_params` | Specific type params such as if the time is primary or used as a partition | Required |
| `description` | A clear description of the dimension | Optional |
| `expr` | Defines the underlying column or SQL query for a dimension. If no `expr` is specified, MetricFlow will use the column with the same name as the group. You can use the column name itself to input a SQL expression. | Optional |
| `label` | A recommended string that defines the display value in downstream tools. Accepts plain text, spaces, and quotes (such as `orders_total` or `"orders_total"`). | Optional |
| Parameter | Description | Required | Type |
| --------- | ----------- | ---- | ---- |
| `name` | Refers to the name of the group that will be visible to the user in downstream tools. It can also serve as an alias if the column name or SQL query reference is different and provided in the `expr` parameter. <br /><br /> Dimension names should be unique within a semantic model, but they can be non-unique across different models as MetricFlow uses [joins](/docs/build/join-logic) to identify the right dimension. | Required | String |
| `type` | Specifies the type of group created in the semantic model. There are two types:<br /><br />- **Categorical**: Describe attributes or features like geography or sales region. <br />- **Time**: Time-based dimensions like timestamps or dates. | Required | String |
| `type_params` | Specific type params such as if the time is primary or used as a partition. | Required | Dict |
| `description` | A clear description of the dimension. | Optional | String |
| `expr` | Defines the underlying column or SQL query for a dimension. If no `expr` is specified, MetricFlow will use the column with the same name as the group. You can use the column name itself to input a SQL expression. | Optional | String |
| `label` | Defines the display value in downstream tools. Accepts plain text, spaces, and quotes (such as `orders_total` or `"orders_total"`). | Optional | String |

Refer to the following for the complete specification for dimensions:

Expand Down
Loading
Loading