Merge branch 'main' into ATSCALE-25338-add-precedence-in-calc-group

Author: stanimir-atscale

README.md

@@ -22,7 +22,7 @@ We are or will be open-sourcing the following:
 2. **Pre-built Semantic Models**: The GitHub repository contains pre-built semantic models that incorporate standard data models, such as TPC-DS, common training models like Worldwide Importers and AdventureWorks, and marketplace models like Snowplow and CRISP. We expect to add semantic models for SaaS applications such as Salesforce, Google Analytics, and Jira soon.
 3. **SML SDK**: An SDK that facilitates the programmatic reading and writing of SML syntax.
 4. **SML CLIs**: Command line interfaces (CLIs) for installing SML dependencies and validating SML syntax. This includes a reference CLI for deploying SML models to a proprietary semantic layer platform.
-5. **Semantic Translators**: A CLI for translating other semantic modeling languages to and from SML, including Snowflake Cortex semantic models, Databricks UC Metrics, and Power BI semantic models.
+5. **Semantic Converters**: A CLI for translating other semantic modeling languages to and from SML, including Snowflake Cortex semantic models, Databricks UC Metrics, and Power BI semantic models.
 
 ## SML Example
 The following is an example of an SML `model` object:
@@ -95,6 +95,10 @@ as the properties available for each:
 - [Connection](sml-reference/connection.md) - Defines a database and schema for connecting datasets to the physical data platform.
 - [Composite Model](sml-reference/composite-model.md) - Defines a model made up of multiple other models.
 
+## SML Converters
+
+[SML Converters and Tooling](https://github.com/semanticdatalayer/sml-converters) - Library of bi-directional SML converters and tooling for different semantic layer platforms.
+
 ## Model Library
 
 ### Tutorial Models

sml-reference/catalog.md

@@ -6,7 +6,8 @@ repository name and settings for building aggregates. Each repository
 must contain a file called `catalog.yml` at the root level.
 
 Sample `catalog` file:
-```
+
+```yaml
 unique_name: sml-models
 object_type: catalog
 label: SML Model Library
@@ -113,12 +114,14 @@ Supported properties:
 - `allow_peer_aggs`: Boolean, optional. Enables aggregation on data
   derived from datasets in data warehouses that are different from the
   source dataset.
+- `allow_preferred_aggs`: Boolean, optional. Allow aggregates to be built 
+  in preferred storage.
 
 Specify the `unique_name` of the dataset followed by the properties and
 values you want to set for it at the repository level. For example:
 
     dataset1:
-        create_hinted_aggregate: true
+        allow_peer_aggs: true
 
 **Note:** Datasets are typically defined at the repository level, in
 `catalog.yml`; however, datasets used by a specific model (typically

sml-reference/composite-model.md

@@ -10,7 +10,7 @@ When you deploy a composite model, all of its referenced objects are deployed as
 
 Sample `composite_model` file:
 
-```
+```yaml
 unique_name: TPCDS - Composite
 object_type: composite_model
 label: TPCDS - Composite

sml-reference/model.md

@@ -465,37 +465,36 @@ file.
 - **Type:** array
 - **Required:** N
 
-A list of the specific metrics and calculations available in the
+A list of the specific metrics and calculations to be hidden in the
 perspective.
 
 ### dimensions
 
 - **Type:** array
 - **Required:** N
 
-A list of the specific dimensions and their hierarchies available in the
+A list of the specific dimensions and their hierarchies to be hidden in the
 perspective.
 
-By default, all objects within a dimension are visible. Hiding a level
-in a hierarchy hides all levels below it, as well as their secondary
-attributes.
+By default, all objects within a dimension are visible. The lowest granularity objects specified are 
+hidden and the objects above it are not. Hiding a level in a hierarchy hides all levels below it. 
+Hiding a hierarchy hides all levels in it. Hiding a dimension hides all objects within it including hierarchies 
+and secondary attributes. If a dimension is not hidden, secondary attributes can be hidden individually.
 
 Supported properties:
 
-- `name`: String, required. The name of the dimension to include in the
+- `name`: String, required. The name of the dimension to be hidden in the
   perspective.
 
 - `hierarchies`: Array, optional. A list of the specific hierarchies
-  within the `name` dimension to include in the perspective. Supported
-  properties:
+  within the dimension to hide in the perspective. Supported properties:
     - `name`: String, required. The name of the hierarchy.
-    - `levels`: Array, optional. A list of the levels within the
-    hierarchy to include in the perspective.
+    - `levels`: Array, optional. Defines a single level in the hierarchy to be hidden in the perspective. All levels below the specified level will also be hidden. Only one level should be provided.
 
 - `secondary_attributes`: Array, optional. A list of the dimension's
-  secondary attributes to include in the perspective.
+  secondary attributes to hide in the perspective.
 
-- `relationships_path`: Array, optional. A list of relationships path.
+- `relationships_path`: Array, optional. A list of relationships used to specify role-playing.
 
 ## drillthroughs
 
@@ -734,6 +733,8 @@ Supported properties:
 - `allow_peer_aggs`: Boolean, optional. Enables aggregation on data
   derived from datasets in data warehouses that are different from the
   source dataset.
+- `allow_preferred_aggs`: Boolean, optional. Allow aggregates to be built 
+  in preferred storage.
 - `create_hinted_aggregate`: Boolean, options. Enables the creation of
   hinted aggregates for the dataset.
 

sml-reference/package.md

@@ -6,7 +6,7 @@ individual objects (such as dimensions) across multiple models.
 
 Sample `package` file:
 
-```
+```yaml
 packages:
   - name: shared
     url: https://github.com/company/shared