diff --git a/docs/pages/guides/style-guide.mdx b/docs/pages/guides/style-guide.mdx index 69ddbd0a6f12b..1e4bc38e62ea1 100644 --- a/docs/pages/guides/style-guide.mdx +++ b/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 diff --git a/docs/pages/product/apis-integrations.mdx b/docs/pages/product/apis-integrations.mdx index a08973eb41a82..ebd26c51a323e 100644 --- a/docs/pages/product/apis-integrations.mdx +++ b/docs/pages/product/apis-integrations.mdx @@ -48,6 +48,16 @@ for an unofficial, community-maintained [client library for Python](https://gith +### 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]
✅ Cube Cloud for Excel
✅ [Cube Cloud for Sheets][ref-cube-cloud-for-sheets] | ❌ All other tools | +| [Folders][ref-folders] | ✅ [Tableau][ref-tableau] via [Semantic Layer Sync][ref-sls]
✅ Cube Cloud for Excel
✅ [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 \ No newline at end of file +[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 \ No newline at end of file diff --git a/docs/pages/product/apis-integrations/mdx-api.mdx b/docs/pages/product/apis-integrations/mdx-api.mdx index c766a7ab6673a..2e5de9ffd9c9b 100644 --- a/docs/pages/product/apis-integrations/mdx-api.mdx +++ b/docs/pages/product/apis-integrations/mdx-api.mdx @@ -60,6 +60,14 @@ views: - city ``` + + +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. + + + ### 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 ``` + + +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. + + + ## 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 \ No newline at end of file diff --git a/docs/pages/product/caching/matching-pre-aggregations.mdx b/docs/pages/product/caching/matching-pre-aggregations.mdx index 59bfc15c177b5..9916c05b63dd0 100644 --- a/docs/pages/product/caching/matching-pre-aggregations.mdx +++ b/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 \ No newline at end of file +[ref-custom-granularity]: /reference/data-model/dimensions#granularities +[ref-views]: /product/data-modeling/concepts#views \ No newline at end of file diff --git a/docs/pages/product/data-modeling/concepts.mdx b/docs/pages/product/data-modeling/concepts.mdx index 41710996828a3..2cb3282c1215c 100644 --- a/docs/pages/product/data-modeling/concepts.mdx +++ b/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. -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: 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: -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: +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 \ No newline at end of file +[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 \ No newline at end of file diff --git a/docs/pages/product/workspace/playground.mdx b/docs/pages/product/workspace/playground.mdx index b21803fc75fe7..77a266e280882 100644 --- a/docs/pages/product/workspace/playground.mdx +++ b/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. diff --git a/docs/pages/reference/data-model/_meta.js b/docs/pages/reference/data-model/_meta.js index 06cb280f924c8..781d8f47f4df7 100644 --- a/docs/pages/reference/data-model/_meta.js +++ b/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", diff --git a/docs/pages/reference/data-model/cube.mdx b/docs/pages/reference/data-model/cube.mdx index 17800085be3b0..24ee25cd3a71e 100644 --- a/docs/pages/reference/data-model/cube.mdx +++ b/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]. @@ -277,13 +278,7 @@ cube(`extended_order_facts`, { ### `public` - - -Prior to v0.33, this property was called `shown`. - - - -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 diff --git a/docs/pages/reference/data-model/dimensions.mdx b/docs/pages/reference/data-model/dimensions.mdx index 4410229a4b465..7c35bb09898ac 100644 --- a/docs/pages/reference/data-model/dimensions.mdx +++ b/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` - - -Prior to v0.33, this property was called `shown`. - - - -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 \ No newline at end of file +[ref-custom-granularity-recipe]: /guides/recipes/data-modeling/custom-granularity +[ref-ref-hierarchies]: /reference/data-model/hierarchies \ No newline at end of file diff --git a/docs/pages/reference/data-model/hierarchies.mdx b/docs/pages/reference/data-model/hierarchies.mdx new file mode 100644 index 0000000000000..92212b49388bd --- /dev/null +++ b/docs/pages/reference/data-model/hierarchies.mdx @@ -0,0 +1,305 @@ +# Hierarchies + +The `hierarchies` property contains a set of hierarchies. You can think about a +hierarchy as a means to group [dimensions][ref-ref-dimensions] together and organize +them into levels of granularity, allowing users to drill down or roll up for analysis. + + + +Hierarchies display is subject to support in [visualization tools][ref-viz-tools]. +Check [APIs & Integrations][ref-apis-support] for details. +You can also preview hierarchies in [Playground][ref-playground]. + + + +Any hierarchy should have the following parameters: [`name`](#name) and [`levels`](#levels). + +## Parameters + +### `name` + +The `name` parameter serves as the identifier of a hierarchy. It must be unique +among all members within a cube and follow the [naming conventions][ref-naming]. + + + +```javascript +cube(`users`, { + sql_table: `users`, + + // ... + + hierarchies: { + location: { + title: `User Location`, + levels: [ + state, + city + ] + } + } +}) +``` + +```yaml +cubes: + - name: users + sql_table: users + + # ... + + hierarchies: + - name: location + title: User Location + levels: + - state + - city +``` + + + +### `title` + +You can use the `title` parameter to set the human-readable name of a hierarchy: + + + +```javascript +cube(`users`, { + sql_table: `users`, + + // ... + + hierarchies: { + location: { + title: `User Location`, + levels: [ + state, + city + ] + } + } +}) +``` + +```yaml +cubes: + - name: users + sql_table: users + + # ... + + hierarchies: + - name: location + title: User Location + levels: + - state + - city +``` + + + +### `levels` + +The `levels` parameter is used to define the levels of the hierarchy. You can do so +by listing the dimensions included in the hierarchy, from less granular to more +granular ones: + + + +```javascript +cube(`users`, { + sql_table: `users`, + + dimensions: { + state: { + sql: `state`, + type: `string` + }, + + city: { + sql: `city`, + type: `string` + } + }, + + hierarchies: { + location: { + title: `User Location`, + levels: [ + state, + city + ] + } + } +}) +``` + +```yaml +cubes: + - name: users + sql_table: users + + dimensions: + - name: state + sql: state + type: string + + - name: city + sql: city + type: string + + hierarchies: + - name: location + title: User Location + levels: + - state + - city +``` + + + +You can include the same dimension in multiple hierarchies. It is also possible to +include a dimension from a joined cube into a hierarchy: + + + +```javascript +cube(`users`, { + sql_table: `users`, + + joins: { + orders: { + sql: `${CUBE.id} = ${orders.user_id}`, + relationship: `one_to_many` + } + }, + + dimensions: { + state: { + sql: `state`, + type: `string` + }, + + city: { + sql: `city`, + type: `string` + }, + + status: { + sql: `status`, + type: `string` + } + }, + + hierarchies: { + location: { + title: `User Location`, + levels: [ + state, + city + ] + }, + + statuses: { + title: `User & Order Statuses`, + levels: [ + status, + orders.status + ] + } + } +}) +``` + +```yaml +cubes: + - name: users + sql_table: users + + joins: + - name: orders + sql: "{CUBE.id} = {orders.user_id}" + relationship: one_to_many + + dimensions: + - name: state + sql: state + type: string + + - name: city + sql: city + type: string + + - name: status + sql: status + type: string + + hierarchies: + - name: details + title: User Details + levels: + - status + - state + - city + + - name: statuses + title: User & Order Statuses + levels: + - status + - orders.status +``` + + + +### `public` + +The `public` parameter is used to manage the visibility of a hierarchy. Valid +values for `public` are `true` and `false`. When set to `false`, this hierarchy +**cannot** be queried through the API. Defaults to `true`. + + + +```javascript +cube(`users`, { + sql_table: `users`, + + // ... + + hierarchies: { + location: { + title: `User Location`, + levels: [ + state, + city + ], + public: false + } + } +}) +``` + +```yaml +cubes: + - name: users + sql_table: users + + # ... + + hierarchies: + - name: location + title: User Location + levels: + - state + - city + public: false +``` + + + + +[ref-ref-dimensions]: /reference/data-model/dimensions +[ref-naming]: /product/data-modeling/syntax#naming +[ref-apis-support]: /product/apis-integrations#support-for-data-modeling +[ref-playground]: /product/workspace/playground#viewing-the-data-model +[ref-viz-tools]: /product/configuration/visualization-tools \ No newline at end of file diff --git a/docs/pages/reference/data-model/measures.mdx b/docs/pages/reference/data-model/measures.mdx index 654a4b258dd23..64d378c23a02a 100644 --- a/docs/pages/reference/data-model/measures.mdx +++ b/docs/pages/reference/data-model/measures.mdx @@ -9,7 +9,7 @@ redirect_from: The `measures` parameter contains a set of measures and each measure is an aggregation over a certain column in your database table. -Any measure should have the following properties: `name`, `sql` and `type`. +Any measure should have the following parameters: `name`, `sql` and `type`. ## Parameters @@ -339,13 +339,7 @@ cubes: ### `public` - - -Prior to v0.33, this property was called `shown`. - - - -The `public` property is used to manage the visibility of a measure. Valid +The `public` parameter is used to manage the visibility of a measure. Valid values for `public` are `true` and `false`. When set to `false`, this measure **cannot** be queried through the API. Defaults to `true`. diff --git a/docs/pages/reference/data-model/segments.mdx b/docs/pages/reference/data-model/segments.mdx index 6eec5b30930ff..2c074f5aaddd5 100644 --- a/docs/pages/reference/data-model/segments.mdx +++ b/docs/pages/reference/data-model/segments.mdx @@ -170,7 +170,7 @@ cubes: ### `public` -The `public` property is used to manage the visibility of a segment. Valid +The `public` parameter is used to manage the visibility of a segment. Valid values for `public` are `true` and `false`. When set to `false`, this segment **cannot** be queried through the API. Defaults to `true`. diff --git a/docs/pages/reference/data-model/view.mdx b/docs/pages/reference/data-model/view.mdx index 8841740202a75..800bdb98b7eee 100644 --- a/docs/pages/reference/data-model/view.mdx +++ b/docs/pages/reference/data-model/view.mdx @@ -5,11 +5,13 @@ redirect_from: # Views -Views sit on top of the data graph of cubes and create a facade of your whole +Views sit on top of the data graph of [cubes][ref-ref-cubes] and create a facade of your whole data model with which data consumers can interact. They are useful for defining metrics, managing governance and data access, and controlling ambiguous join paths. +Any view should have the following parameters: [`name`](#name) and [`cubes`](#cubes). + ## Parameters ### `name` @@ -57,30 +59,6 @@ views: -### `meta` - -Custom metadata. Can be used to pass any information to the frontend. - - - -```javascript -view(`active_users`, { - meta: { - any: `value` - } -}); -``` - -```yaml -views: - - name: active_users - meta: - any: value - -``` - - - ### `cubes` Use `cubes` parameter in view to include exposed cubes in bulk. You can build @@ -190,15 +168,99 @@ with the cube name, you can use the `prefix: true` parameter. It will prefix them with the cube name, e.g. `users_city`. You can use the `alias` parameter to specify a custom prefix. -### `public` +### `folders` + +The `folders` parameter is used to organize members of a view (e.g., dimensions, +hierarchies, measures, etc.) into logical groups. Folders can contain non-overlapping +subsets of members from a view. -Prior to v0.33, this parameter was called `shown`. +Folders display is subject to support in [visualization tools][ref-viz-tools]. +Check [APIs & Integrations][ref-apis-support] for details. +You can also preview folders in [Playground][ref-playground]. -The `public` property is used to manage the visibility of a view. Valid values +Each folder should specify a human-readable name via the `name` parameter and list +included members via the `includes` parameter: + + + +```javascript +view(`customers`, { + cubes: [ + { + join_path: `users`, + includes: `*` + }, + { + join_path: `users.orders`, + prefix: true, + includes: [ + `status`, + `price`, + `count` + ] + } + ], + + folders: [ + { + name: `Basic Details`, + includes: [ + `created_at`, + `location`, + `orders_status`, + `orders_count` + ] + }, + + { + name: `Sensitive Details`, + includes: [ + `name`, + `gender` + ] + } + ] +}) +``` + +```yaml +views: + - name: customers + + cubes: + - join_path: users + includes: "*" + + - join_path: users.orders + prefix: true + includes: + - status + - price + - count + + folders: + - name: Basic Details + includes: + - created_at + - location + - orders_status + - orders_count + + - name: Sensitive Details + includes: + - name + - gender +``` + + + +### `public` + +The `public` parameter is used to manage the visibility of a view. Valid values for `public` are `true` and `false`. When set to `false`, this view **cannot** be queried through the API. Defaults to `true`. @@ -254,6 +316,30 @@ To learn more about using `public` to control visibility based on security context, read the [Controlling access to cubes and views recipe][ref-recipe-control-access-cubes-views]. +### `meta` + +Custom metadata. Can be used to pass any information to the frontend. + + + +```javascript +view(`active_users`, { + meta: { + any: `value` + } +}); +``` + +```yaml +views: + - name: active_users + meta: + any: value + +``` + + + ### `includes` (deprecated) @@ -297,19 +383,14 @@ views: -## Using views with pre-aggregations - -Pre-aggregations defined for original Cube members would still work when used in -view queries. Please note that pre-aggregations use the same leaf members -matching algorithm used for Cubes. As a consequence, all measures and dimensions -included in pre-aggregation should be leaf members in order to be matched by -view query. - [ref-recipe-control-access-cubes-views]: /guides/recipes/access-control/controlling-access-to-cubes-and-views [ref-schema-joins-direction]: /product/data-modeling/concepts/working-with-joins#directions-of-joins [ref-naming]: /product/data-modeling/syntax#naming -[ref-playground]: /product/workspace/playground -[ref-apis]: /product/apis-integrations \ No newline at end of file +[ref-apis]: /product/apis-integrations +[ref-ref-cubes]: /reference/data-model/cube +[ref-apis-support]: /product/apis-integrations#support-for-data-modeling +[ref-playground]: /product/workspace/playground#viewing-the-data-model +[ref-viz-tools]: /product/configuration/visualization-tools \ No newline at end of file diff --git a/docs/styles/typography.css b/docs/styles/typography.css index bae058933d0ed..d026ec60f930f 100644 --- a/docs/styles/typography.css +++ b/docs/styles/typography.css @@ -88,7 +88,8 @@ h3, h4, h5, h6, -p { +p, +li { color: var(--dark_01); }