docs: Hierarchies and folders in the data model (#9106)

* Hierarchies reference

* All the rest

* Fix

* Fix

Author: igorlukanin

docs/pages/guides/style-guide.mdx

@@ -73,6 +73,8 @@ cube_project
   - `pre_aggregations`
   - `joins`
   - `dimensions`
+  - `hierarchies`
+  - `segments`
   - `measures`
 
 ### Dimensions & measures
@@ -136,8 +138,9 @@ cubes:
 - Applicable [view parameters][ref-view-params] should be ordered as follows:
   - `name`
   - `description`
-  - `includes`
+  - `public`
   - `cubes`
+  - `folders`
 
 ### Example view
 
@@ -316,7 +319,7 @@ cube(`users`, {
 
 This style guide was inspired in part by:
 
-- [Brooklyn Data' SQL style guide](https://github.com/brooklyn-data/co/blob/main/sql_style_guide.md)
+- [Brooklyn Data Co. SQL style guide](https://github.com/brooklyn-data/co/blob/main/sql_style_guide.md)
 - [LAMS Style Guide](https://looker-open-source.github.io/look-at-me-sideways/rules.html)
 
 [cpn]: https://cube.dev/consulting/cube-partner-network

docs/pages/product/apis-integrations.mdx

@@ -48,6 +48,16 @@ for an unofficial, community-maintained [client library for Python](https://gith
 
 </ReferenceBox>
 
+### Support for data modeling
+
+Support for data modeling features differ across APIs, integrations, and [visualization
+tools][ref-viz-tools]. Some of the features with partial support are listed below:
+
+| Feature | Supported in | Not supported in |
+| --- | --- | --- |
+| [Hierarchies][ref-hierarchies] | ✅ [Tableau][ref-tableau] via [Semantic Layer Sync][ref-sls]<br/>✅ Cube Cloud for Excel<br/>✅ [Cube Cloud for Sheets][ref-cube-cloud-for-sheets] | ❌ All other tools |
+| [Folders][ref-folders] | ✅ [Tableau][ref-tableau] via [Semantic Layer Sync][ref-sls]<br/>✅ Cube Cloud for Excel<br/>✅ [Cube Cloud for Sheets][ref-cube-cloud-for-sheets] | ❌ All other tools |
+
 ## Management APIs
 
 In case you'd like Cube to work with data orchestration tools and let them push
@@ -69,4 +79,8 @@ API][ref-orchestration-api].
 [ref-sql-syntax]: /product/apis-integrations/sql-api#querying-fundamentals
 [ref-json-syntax]: /product/apis-integrations/rest-api/query-format
 [ref-graphql-syntax]: /product/apis-integrations/graphql-api#getting-started
-[ref-cube-cloud-for-sheets]: /product/apis-integrations/google-sheets
+[ref-cube-cloud-for-sheets]: /product/apis-integrations/google-sheets
+[ref-viz-tools]: /product/configuration/visualization-tools
+[ref-hierarchies]: /reference/data-model/hierarchies
+[ref-folders]: /reference/data-model/view#folders
+[ref-tableau]: /product/configuration/visualization-tools/tableau

docs/pages/product/apis-integrations/mdx-api.mdx

@@ -60,6 +60,14 @@ views:
             - city
 ```
 
+<InfoBox>
+
+For historical reasons, the syntax shown above differ from how
+[hierarchies][ref-hierarchies] are supposed to be defined in the data model.
+This is going to be harmonized in the future. 
+
+</InfoBox>
+
 ### Dimension keys
 
 You can define a member that will be used as a key for a dimension in the cube's model file.
@@ -143,6 +151,18 @@ views:
               - completed_percentage
 ```
 
+<InfoBox>
+
+For historical reasons, the syntax shown above differ from how
+[folders][ref-folders] are supposed to be defined in the data model.
+This is going to be harmonized in the future. 
+
+</InfoBox>
+
 ## Authentication and authorization
 
 Authentication and authorization work the same as for the [SQL API](/product/apis-integrations/sql-api/security).
+
+
+[ref-hierarchies]: /reference/data-model/hierarchies
+[ref-folders]: /reference/data-model/view#folders

docs/pages/product/caching/matching-pre-aggregations.mdx

@@ -21,14 +21,18 @@ If you don't know why a query doesn't match a pre-aggregation, check
 
 ## Eligible pre-aggregations
 
-Cube will search for matching pre-aggregations in all cubes that define
-members in the query.
-
-Pre-aggregations are tested in the order they are defined in the data model
+Cube goes through the following steps to determine if there are any pre-aggregations
+matching a query:
+- **Members (e.g., dimensions, measures, etc.) are extracted from the query.**
+If the query contains members of a [view][ref-views], they are substituted by
+respective members of cubes where they are defined. It means that pre-aggregations
+defined for cube members would also match queries with view members. There's no need
+to define additional pre-aggregations for views.
+- Cube looks for pre-aggregations in all cubes that define members in the query.
+- Pre-aggregations are tested in the order they are defined in the data model
 file. However, `rollup` pre-aggregations are tested before `original_sql`
 pre-aggregations.
-
-The first pre-aggregation that matches a query is used.  
+- The first pre-aggregation that [matches](#matching-algorithm) a query is used.  
 
 ## Matching algorithm
 
@@ -129,4 +133,5 @@ configuration option.
 [ref-conf-scheduled-refresh-time-zones]: /reference/configuration/config#scheduled_refresh_time_zones
 [ref-ungrouped-queries]: /product/apis-integrations/queries#ungrouped-query
 [ref-primary-key]: /reference/data-model/dimensions#primary_key
-[ref-custom-granularity]: /reference/data-model/dimensions#granularities
+[ref-custom-granularity]: /reference/data-model/dimensions#granularities
+[ref-views]: /product/data-modeling/concepts#views

docs/pages/product/data-modeling/concepts.mdx

@@ -5,7 +5,7 @@ redirect_from:
 
 # Concepts
 
-Cube borrows a lot of terminology from data science and [OLAP
+Cube borrows a lot of terminology from [OLAP
 theory][wiki-olap], and this document is intended for both newcomers and regular
 users to refresh their understanding.
 
@@ -109,8 +109,10 @@ paths.
 
 <Diagram src="https://ucarecdn.com/bfc3e04a-b690-40bc-a6f8-14a9175fb4fd/" />
 
-Views can **not** have their own members. Instead, use the `cubes` or `includes`
-parameters to include measures and dimensions from other cubes into the view.
+Views can **not** have their own members. Instead, they use the `cubes`
+parameter to include members of cubes. Optionally, you can also group members of a view
+into [folders][ref-ref-folders].
+
 In the example below, we create the `orders` view which includes select members
 from `base_orders`, `products`, and `users` cubes:
 
@@ -178,7 +180,7 @@ views:
 </CodeTabs>
 
 Views do **not** define any [pre-aggregations](#pre-aggregations). Instead,
-they reuse pre-aggregations from underlying cubes.
+they [reuse][ref-matching-preaggs] pre-aggregations from underlying cubes.
 
 View may not only be defined statically; you can actually build
 [dynamic data models][ref-dynamic-data-models].
@@ -282,7 +284,9 @@ cubes:
 
 </CodeTabs>
 
-Also, [subquery dimensions][ref-subquery-dimensions] can be used to join cubes
+If needed, dimensions can be organized into [hierarchies][ref-ref-hierarchies].
+Also, [proxy dimensions][ref-proxy-dimensions] are helpful for code reusability
+and [subquery dimensions][ref-subquery-dimensions] can be used to join cubes
 implicitly.
 
 ### Dimension types
@@ -434,6 +438,9 @@ cubes:
 
 </CodeTabs>
 
+Also, [calculated measures][ref-calculated-measures] can be used to perform calculations
+on other measures.
+
 ### Measure types
 
 Measures can be of different types. See the [measure type
@@ -719,6 +726,7 @@ Pre-Aggregations][ref-caching-preaggs-intro].
 [ref-polymorphic-cubes]: /product/data-modeling/concepts/polymorphic-cubes
 [ref-data-blending]: /product/data-modeling/concepts/data-blending
 [ref-dynamic-data-models]: /product/data-modeling/dynamic
+[ref-proxy-dimensions]: /product/data-modeling/concepts/calculated-members#proxy-dimensions
 [ref-subquery-dimensions]: /product/data-modeling/concepts/calculated-members#subquery-dimensions
 [ref-working-with-joins]: /product/data-modeling/concepts/working-with-joins
 [self-dimensions]: #dimensions
@@ -735,4 +743,6 @@ Pre-Aggregations][ref-caching-preaggs-intro].
 [ref-ref-dimension-granularities]: /reference/data-model/dimensions#granularities
 [ref-ref-primary-key]: /reference/data-model/dimensions#primary_key
 [ref-custom-granularity-recipe]: /guides/recipes/data-modeling/custom-granularity
-[ref-proxy-granularity]: /product/data-modeling/concepts/calculated-members#time-dimension-granularity
+[ref-proxy-granularity]: /product/data-modeling/concepts/calculated-members#time-dimension-granularity
+[ref-ref-hierarchies]: /reference/data-model/hierarchies
+[ref-ref-folders]: /reference/data-model/view#folders

docs/pages/product/workspace/playground.mdx

@@ -42,7 +42,8 @@ on a cube or a view to view a list of its members.
   src="https://ucarecdn.com/08d5cc69-431d-43d9-8da4-804029adf1fa/"
 />
 
-Measures, dimensions, and segments are shown using distinct colors. If a member has
+Members of cubes and views (i.e., measures, dimensions, hierarchies, etc.) are shown
+using distinct colors and icons. If a member has
 a [title][ref-data-model-title] or a [description][ref-data-model-description] set
 in the data model, they will be shown in a tooltip. If a member is not
 [public][ref-data-model-public], you will see a lock sign next to it.

docs/pages/reference/data-model/_meta.js

@@ -3,6 +3,7 @@ module.exports = {
   "view": "Views",
   "measures": "Measures",
   "dimensions": "Dimensions",
+  "hierarchies": "Hierarchies",
   "segments": "Segments",
   "joins": "Joins",
   "pre-aggregations": "Pre-aggregations",

docs/pages/reference/data-model/cube.mdx

@@ -10,8 +10,9 @@ A `cube` represents a table of data in Cube.
 
 Cubes are typically declared in separate files with one cube per file.
 Within each cube are definitions of [measures][ref-ref-measures],
-[dimensions][ref-ref-dimensions], [segments][ref-ref-segments],
-[joins][ref-ref-joins] between cubes, and [pre-aggregations][ref-ref-pre-aggs].
+[dimensions][ref-ref-dimensions], [hierarchies][ref-ref-hierarchies],
+[segments][ref-ref-segments], [joins][ref-ref-joins] between cubes,
+and [pre-aggregations][ref-ref-pre-aggs].
 
 <CodeTabs>
 
@@ -277,13 +278,7 @@ cube(`extended_order_facts`, {
 
 ### `public`
 
-<InfoBox>
-
-Prior to v0.33, this property was called `shown`.
-
-</InfoBox>
-
-The `public` property is used to manage the visibility of a cube. Valid values
+The `public` parameter is used to manage the visibility of a cube. Valid values
 for `public` are `true` and `false`. When set to `false`, this cube **cannot**
 be queried through the API. Defaults to `true`.
 
@@ -599,6 +594,7 @@ cubes:
 [ref-apis]: /product/apis-integrations
 [ref-ref-measures]: /reference/data-model/measures
 [ref-ref-dimensions]: /reference/data-model/dimensions
+[ref-ref-hierarchies]: /reference/data-model/hierarchies
 [ref-ref-segments]: /reference/data-model/segments
 [ref-ref-joins]: /reference/data-model/joins
 [ref-ref-pre-aggs]: /reference/data-model/pre-aggregations

docs/pages/reference/data-model/dimensions.mdx

@@ -10,7 +10,9 @@ The `dimensions` property contains a set of dimensions. You can think about a
 dimension as an attribute related to a measure, e.g. the measure `user_count`
 can have dimensions like `country`, `age`, `occupation`, etc.
 
-Any dimension should have the following properties: `name`, `sql` and `type`.
+Any dimension should have the following parameters: `name`, `sql` and `type`.
+
+Dimensions can be also organized into [hierarchies][ref-ref-hierarchies].
 
 ## Parameters
 
@@ -425,13 +427,7 @@ cubes:
 
 ### `public`
 
-<InfoBox>
-
-Prior to v0.33, this property was called `shown`.
-
-</InfoBox>
-
-The `public` property is used to manage the visibility of a dimension. Valid
+The `public` parameter is used to manage the visibility of a dimension. Valid
 values for `public` are `true` and `false`. When set to `false`, this dimension
 **cannot** be queried through the API. Defaults to `true`.
 
@@ -715,4 +711,5 @@ cube(`orders`, {
 [ref-apis]: /product/apis-integrations
 [ref-time-dimensions]: /reference/data-model/types-and-formats#time-1
 [link-date-time-string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format
-[ref-custom-granularity-recipe]: /guides/recipes/data-modeling/custom-granularity
+[ref-custom-granularity-recipe]: /guides/recipes/data-modeling/custom-granularity
+[ref-ref-hierarchies]: /reference/data-model/hierarchies