feat: Links in the data model

docs-mintlify/reference/data-modeling/context-variables.mdx

@@ -113,7 +113,7 @@ values from the Cube query during SQL generation.
 
 This is useful for hinting your database optimizer to use a specific index
 or filter out partitions or shards in your cloud data warehouse so you won't
-be billed for scanning those.
+be billed for scanning those. It can also be useful for constructing [links][ref-links].
 
 <Warning>
 
@@ -816,4 +816,5 @@ cube(`orders`, {
 [ref-dynamic-data-models]: /docs/data-modeling/dynamic/jinja
 [ref-query-filter]: /reference/rest-api/query-format#query-properties
 [ref-dynamic-jinja]: /docs/data-modeling/dynamic/jinja
-[ref-filter-boolean]: /reference/rest-api/query-format#boolean-logical-operators
+[ref-filter-boolean]: /reference/rest-api/query-format#boolean-logical-operators
+[ref-links]: /reference/data-modeling/dimensions#links

docs-mintlify/reference/data-modeling/dimensions.mdx

@@ -426,9 +426,125 @@ Using it with other dimension types will result in a validation error.
 
 </Info>
 
+### `links`
+
+The `links` parameter allows you to define links associated with a dimension.
+They can be rendered as HTML links by supporting tools, e.g., [Workbooks][ref-workbooks].
+
+Links are useful to let users navigate to related external resources (e.g., Google
+search), internal tools (e.g., Salesforce), or other pages in a BI tool.
+
+Each link must have a `label` and a `url`. The `url` should be a valid absolute URL and it
+can [reference][ref-references] column and dimension values.
+
+Optionally, a link might use the `icon` parameter to reference an icon from a [supported
+icon set][link-tabler] to be displayed alongside the link label.
+
+Optionally, a link might use the `target` parameter to specify [where to open it][link-target]:
+`blank` (default) to open in a new tab/window or `self` to open in the same tab/window.
+
+```yaml
+cubes:
+  - name: users
+
+    dimensions:
+      # Definitions of dimensions such as `email`, etc.
+
+      - name: full_name
+        sql: full_name
+        type: string
+        links:
+          - label: Search on Google
+            # You can reference the dimension value in the URL
+            url: "https://www.google.com/search?q={full_name}"
+            icon: brand-google
+            target: blank
+
+          - label: Search in Salesforce
+            # You can reference values of other dimensions in the URL as well
+            url: "https://your-company.salesforce.com/search/results/?q={email}"
+            target: blank
+
+          - label: Write an email
+            # Use URL schema to hint the application, e.g., 'mailto:' for email clients
+            url: "mailto:{email}"
+            icon: send
+```
+
+#### `params`
+
+The optional `params` parameter can be used to add additional query parameters to the
+URL. It accepts a map of key-value pairs, where keys are parameter names and values are
+parameter values.
+
+Values in `params` can [reference][ref-references] columns and dimension values.
+Additionally, values in `params` can reference filters applied to the current query using
+the [`FILTER_PARAMS` context variable][ref-filter-params].
+
+Conveniently, the `propagate_filters_to_params` parameter, `true` by default, can be used
+to pass all filters from the current query as an additional parameter. Filters will use
+the same format as the [`filters` query parameter][ref-rest-filters] in the REST API.
+The `param_name_for_filters` parameter, `filters` by default, can be used to customize
+the name of this additional parameter.
+
+All parameter keys and values will be [URL-encoded][link-encode-uri-component]
+when the full URL is constructed.
+
+```yaml
+cubes:
+  - name: users
+
+    dimensions:
+      # Definitions of dimensions such as `id`, `country`, etc.
+
+      - name: full_name
+        sql: full_name
+        type: string
+        links:
+          - label: Check performance dashboard
+            url: "https://my-account.cubecloud.dev/new/d/123/dashboards/KSqDYdUz6Ble"
+            params:
+              # Pass dimension values as query parameters
+              filter_user_id: "{id}"
+              # Pass filters from the current query as query parameters
+              filter_country: "{FILTER_PARAMS.users.country}"
+              # Pass additional parameters, if needed
+              utm_source: cube
+
+          - label: Check another dashboard
+            url: "https://my-account.cubecloud.dev/new/d/456/dashboards/iuZjHd8h5mKLe"
+            # Don't pass any filters from the current query
+            propagate_filters_to_params: false
+
+          - label: Check one more dashboard
+            url: "https://my-account.cubecloud.dev/new/d/456/dashboards/iuZjHd8h5mKLe"
+            # Pass all filters from the current query as the `my_precious_filters` query parameter
+            param_name_for_filters: my_precious_filters
+```
+
+#### Dimensions
+
+Each link will be rendered as a few additional [synthetic](#synthetic) dimensions in the
+result set, with the following naming convention, where `<id>` is a zero-based index of
+the link in the `links` array:
+
+- `<dimension_name>___link_<id>_label`
+- `<dimension_name>___link_<id>_url`
+- `<dimension_name>___link_<id>_target`
+- `<dimension_name>___link_<id>_icon`
+
+<Info>
+
+All references in link URLs and parameters must resolve to a single value for a given
+value of the dimension on which the link is defined. Otherwise, it will result in
+duplicate rows in the result set.
+
+</Info>
+
 ### `meta`
 
-Custom metadata. Can be used to pass any information to the frontend.
+The `meta` parameter allows you to attach arbitrary information to a dimension.
+It can be consumed and interpreted by supporting tools.
 
 You can also use the `ai_context` key to provide context to the
 [AI agent][ref-ai-context] without exposing it in the user interface.
@@ -902,6 +1018,13 @@ cube(`orders`, {
 
 </CodeGroup>
 
+### `synthetic`
+
+The `synthetic` parameter can't be set by a user directly. It is used to mark dimensions
+that are automatically created by Cube, e.g., for [links](#links).
+
+You can check if a dimension is synthetic via the [`/v1/meta` API endpoint][ref-meta-api].
+
 ### `granularities`
 
 By default, the following granularities are available for time dimensions:
@@ -1222,4 +1345,11 @@ cube(`fiscal_calendar`, {
 [link-tesseract]: https://cube.dev/blog/introducing-next-generation-data-modeling-engine
 [ref-case-measures]: /reference/data-modeling/measures#case
 [ref-meta-api]: /reference/rest-api/reference#base_pathv1meta
-[ref-string-time-dims]: /recipes/data-modeling/string-time-dimensions
+[ref-string-time-dims]: /recipes/data-modeling/string-time-dimensions
+[ref-workbooks]: /docs/explore-analyze/workbooks
+[link-target]: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a#target
+[link-tabler]: https://tabler.io/icons
+[ref-references]: /docs/data-modeling/syntax#references
+[ref-filter-params]: /reference/data-modeling/context-variables#filter_params
+[link-encode-uri-component]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent
+[ref-rest-filters]: /reference/rest-api/query-format#query-properties

docs/content/product/data-modeling/reference/context-variables.mdx

@@ -113,7 +113,7 @@ values from the Cube query during SQL generation.
 
 This is useful for hinting your database optimizer to use a specific index
 or filter out partitions or shards in your cloud data warehouse so you won't
-be billed for scanning those.
+be billed for scanning those. It can also be useful for constructing [links][ref-links].
 
 <WarningBox>
 
@@ -816,4 +816,5 @@ cube(`orders`, {
 [ref-dynamic-data-models]: /product/data-modeling/dynamic/jinja
 [ref-query-filter]: /product/apis-integrations/rest-api/query-format#query-properties
 [ref-dynamic-jinja]: /product/data-modeling/dynamic/jinja
-[ref-filter-boolean]: /product/apis-integrations/rest-api/query-format#boolean-logical-operators
+[ref-filter-boolean]: /product/apis-integrations/rest-api/query-format#boolean-logical-operators
+[ref-links]: /product/data-modeling/reference/dimensions#links

docs/content/product/data-modeling/reference/dimensions.mdx

@@ -293,9 +293,125 @@ cubes:
 
 </CodeTabs>
 
+### `links`
+
+The `links` parameter allows you to define links associated with a dimension.
+They can be rendered as HTML links by supporting tools, e.g., [Workbooks][ref-workbooks].
+
+Links are useful to let users navigate to related external resources (e.g., Google
+search), internal tools (e.g., Salesforce), or other pages in a BI tool.
+
+Each link must have a `label` and a `url`. The `url` should be a valid absolute URL and it
+can [reference][ref-references] column and dimension values.
+
+Optionally, a link might use the `icon` parameter to reference an icon from a [supported
+icon set][link-tabler] to be displayed alongside the link label.
+
+Optionally, a link might use the `target` parameter to specify [where to open it][link-target]:
+`blank` (default) to open in a new tab/window or `self` to open in the same tab/window.
+
+```yaml
+cubes:
+  - name: users
+
+    dimensions:
+      # Definitions of dimensions such as `email`, etc.
+
+      - name: full_name
+        sql: full_name
+        type: string
+        links:
+          - label: Search on Google
+            # You can reference the dimension value in the URL
+            url: "https://www.google.com/search?q={full_name}"
+            icon: brand-google
+            target: blank
+
+          - label: Search in Salesforce
+            # You can reference values of other dimensions in the URL as well
+            url: "https://your-company.salesforce.com/search/results/?q={email}"
+            target: blank
+
+          - label: Write an email
+            # Use URL schema to hint the application, e.g., 'mailto:' for email clients
+            url: "mailto:{email}"
+            icon: send
+```
+
+#### `params`
+
+The optional `params` parameter can be used to add additional query parameters to the
+URL. It accepts a map of key-value pairs, where keys are parameter names and values are
+parameter values.
+
+Values in `params` can [reference][ref-references] columns and dimension values.
+Additionally, values in `params` can reference filters applied to the current query using
+the [`FILTER_PARAMS` context variable][ref-filter-params].
+
+Conveniently, the `propagate_filters_to_params` parameter, `true` by default, can be used
+to pass all filters from the current query as an additional parameter. Filters will use
+the same format as the [`filters` query parameter][ref-rest-filters] in the REST API.
+The `param_name_for_filters` parameter, `filters` by default, can be used to customize
+the name of this additional parameter.
+
+All parameter keys and values will be [URL-encoded][link-encode-uri-component]
+when the full URL is constructed.
+
+```yaml
+cubes:
+  - name: users
+
+    dimensions:
+      # Definitions of dimensions such as `id`, `country`, etc.
+
+      - name: full_name
+        sql: full_name
+        type: string
+        links:
+          - label: Check performance dashboard
+            url: "https://my-account.cubecloud.dev/new/d/123/dashboards/KSqDYdUz6Ble"
+            params:
+              # Pass dimension values as query parameters
+              filter_user_id: "{id}"
+              # Pass filters from the current query as query parameters
+              filter_country: "{FILTER_PARAMS.users.country}"
+              # Pass additional parameters, if needed
+              utm_source: cube
+
+          - label: Check another dashboard
+            url: "https://my-account.cubecloud.dev/new/d/456/dashboards/iuZjHd8h5mKLe"
+            # Don't pass any filters from the current query
+            propagate_filters_to_params: false
+
+          - label: Check one more dashboard
+            url: "https://my-account.cubecloud.dev/new/d/456/dashboards/iuZjHd8h5mKLe"
+            # Pass all filters from the current query as the `my_precious_filters` query parameter
+            param_name_for_filters: my_precious_filters
+```
+
+#### Dimensions
+
+Each link will be rendered as a few additional [synthetic](#synthetic) dimensions in the
+result set, with the following naming convention, where `<id>` is a zero-based index of
+the link in the `links` array:
+
+- `<dimension_name>___link_<id>_label`
+- `<dimension_name>___link_<id>_url`
+- `<dimension_name>___link_<id>_target`
+- `<dimension_name>___link_<id>_icon`
+
+<InfoBox>
+
+All references in link URLs and parameters must resolve to a single value for a given
+value of the dimension on which the link is defined. Otherwise, it will result in
+duplicate rows in the result set.
+
+</InfoBox>
+
 ### `meta`
 
-Custom metadata. Can be used to pass any information to the frontend.
+The `meta` parameter allows you to attach arbitrary information to a dimension.
+It can be consumed and interpreted by supporting tools.
 
 <CodeTabs>
 
@@ -701,6 +817,13 @@ cubes:
 
 </CodeTabs>
 
+### `synthetic`
+
+The `synthetic` parameter can't be set by a user directly. It is used to mark dimensions
+that are automatically created by Cube, e.g., for [links](#links).
+
+You can check if a dimension is synthetic via the [`/v1/meta` API endpoint][ref-meta].
+
 ### `granularities`
 
 By default, the following granularities are available for time dimensions:
@@ -1015,3 +1138,11 @@ cube(`fiscal_calendar`, {
 [ref-cube-calendar]: /product/data-modeling/reference/cube#calendar
 [ref-measure-time-shift]: /product/data-modeling/reference/measures#time_shift
 [ref-data-masking]: /product/auth/data-access-policies#data-masking
+[ref-workbooks]: /product/exploration/workbooks
+[link-target]: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a#target
+[link-tabler]: https://tabler.io/icons
+[ref-references]: /product/data-modeling/syntax#references
+[ref-filter-params]: /product/data-modeling/reference/context-variables#filter_params
+[link-encode-uri-component]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent
+[ref-rest-filters]: /product/apis-integrations/rest-api/query-format#query-properties
+[ref-meta]: /product/apis-integrations/rest-api/reference#base_pathv1meta