[v1.4][ATSCALE-27469] added uda`s in the composite model

README.md

@@ -1,12 +1,13 @@
 ![logo](images/sml-logo-large.png)
 
-# SML version 1.3
+# SML version 1.4
 
-This is documentation for SML spec version `1.3`. For earlier versions browse the repository tags. Examples:
+This is documentation for SML spec version `1.4`. For earlier versions browse the repository tags. Examples:
 
 - [SML version 1.0](https://github.com/semanticdatalayer/SML/tree/v1.0)
 - [SML version 1.1](https://github.com/semanticdatalayer/SML/tree/v1.1)
 - [SML version 1.2](https://github.com/semanticdatalayer/SML/tree/v1.2)
+- [SML version 1.3](https://github.com/semanticdatalayer/SML/tree/v1.3)
 
 # What is SML?
 

sml-reference/composite-model.md

@@ -3,7 +3,7 @@
 Composite models are made up of multiple other models that all share a dimension, as well as calculations specific to the composite model itself. They are defined by `composite_model` files in SML.
 
 When you deploy a composite model, all of its referenced objects are deployed as a single model. Note, however, that deployed composite models do not include the following objects from their referenced models:
-- User defined aggregates
+
 - Partitions
 - Perspectives
 - Drill-throughs
@@ -16,7 +16,7 @@ object_type: composite_model
 label: TPCDS - Composite
 description: This is a composite model that combines TPC-DS subject-area models.
 
-models: 
+models:
   - TPC-DS Catalog Sales
   - TPC-DS Inventory
   - TPC-DS Store Promotion
@@ -39,13 +39,16 @@ metrics:
 classDiagram
     CompositeModel ..> ModelReference
     CompositeModel ..> MetricReference
+    CompositeModel *-- Aggregate
+    Aggregate *-- AttributeReference
 namespace CompositeModels{
     class CompositeModel{
       String unique_name
       const object_type
       String label
       Array~ModelReference~ models
       Array~MetricReference~ metrics
+      Array~Aggregate~ aggregates
     }
     class ModelReference{
       String unique_name
@@ -97,7 +100,6 @@ A list of the models that make up the composite model. These must meet the follo
 - They cannot be other composite models.
 - They must all have at least one dimension in common.
 
-
 ## metrics
 
 - **Type:** array
@@ -112,3 +114,117 @@ The `metrics` property supports the following properties:
 
 - `unique_name`: String, required. The unique name of the calculation.
 - `folder`: String, optional. The name of the folder in which this calculation appears in BI tools.
+
+## aggregates
+
+- **Type:** array
+- **Required:** N
+- **Added in** v1.4
+
+> [!WARNING]
+> Any UDA's defined on the models referenced by the composite will not be used. They will not be automatically added
+
+The `aggregates` property in a composite model file enables you to add
+user-defined aggregates (UDAs).They include metrics or attributes from different
+models within the composite model.
+
+In general, we recommend relying on the aggregate tables
+automatically generated by the semantic engine. However, there are cases
+that are not covered by system-defined aggregates. For example:
+
+- **Metrics on dimensions:** The semantic engine does not generate
+  aggregate tables for metrics that are local to a dimension only (a
+  secondary metrical attribute in the composite model).
+- **Non-additive metrics:** The semantic engine does not generate
+  aggregate tables for non-additive metrics, which are useful for
+  distinct counts. This is because such an aggregate table defined for
+  one query would not be usable by other queries.
+
+If you require aggregate tables that contain these types of dimensional
+attributes or metrics, you should define your own manually using the
+`aggregates` property.
+
+The `aggregates` property in a composite model file supports the following
+properties.
+
+### unique_name
+
+- **Type:** string
+- **Required:** Y
+
+The unique name of the aggregate. This must be unique within the composite model
+file.
+
+Aggregate table names used by the query engine are system-generated, but
+they include the first 14 characters of the user-supplied name at the
+end of the internal ID name. This name can help you identify when a
+user-defined aggregate is used in a query. For example:
+`as_agg_internal-id_my-uda-name`
+
+### label
+
+- **Type:** string
+- **Required:** Y
+
+The name of the aggregate, as it appears in the consunmption tool. This value does not
+need to be unique.
+
+### caching
+
+- **Type:** enum
+- **Required:** N
+
+This setting will control whether the aggregate is pinned in local cache.
+
+Supported values:
+
+- `engine-memory`
+
+### metrics
+
+- **Type:** array
+- **Required:** Y
+
+A list of the metrics and calculations to include in the aggregate
+definition. This is the data that is summarized in the resulting
+aggregate table.
+
+### attributes
+
+- **Type:** array
+- **Required:** N
+
+A list of the dimension attributes to include in the aggregate
+definition.
+
+Supported properties:
+
+- `name`: String, required. The name of the dimension attribute to
+  include. These values are used to group the summarized metric data in
+  the resulting aggregate table. Note that user-defined aggregate
+  definitions are fixed: they do not include every level of a hierarchy
+  unless they are explicitly defined.
+
+- `dimension`: String, required. The dimension to which the attribute
+  defined by `name` belongs.
+
+- `partition`: String, optional. Adds a partition to the aggregate, and
+  determines whether it should be defined on the key column, name
+  column, or both. Supported values: `name`, `key`, `name+key`
+
+  When the engine builds an instance of this aggregate, it creates
+  a partition for each combination of values in the dimensional
+  attributes. The number of partitions depends on the
+  left-to-right order of the attributes, as well as the number of
+  values for each attribute.
+
+  Essentially, the partitioning key functions as a `GROUP BY`
+  column. Queries against the aggregate must use this dimensional
+  attribute in a `WHERE` clause. A good candidate for a
+  partitioning key is a set of dimensional attributes that
+  together have a few hundred to under 1000 value combinations.
+
+- `distribution`: String, optional. The distribution keys to use when
+  creating the aggregate table. If your aggregate data warehouse
+  supports distribution keys, then the semantic engine uses the specified keys when
+  creating the aggregate table.