feat: Links in the data model#10852
Conversation
Add documentation for the new `links`, `html`, and `synthetic` parameters on dimensions. Links allow defining navigable URLs associated with dimension values, rendered as synthetic dimensions in the result set. HTML fragments enable rich formatting beyond the `format` parameter. The `synthetic` parameter marks auto-generated dimensions. Also update the `meta` parameter description and add a cross-reference from the FILTER_PARAMS context variable documentation to the new links feature. Changes applied to both the Next.js docs (docs/content/) and the Mintlify docs (docs-mintlify/reference/). Co-authored-by: Pavel Tiunov <pavel.tiunov@gmail.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Claude finished @paveltiunov's task in 3m 3s —— View job Review: Documentation for
|
Co-authored-by: Pavel Tiunov <pavel.tiunov@gmail.com>
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| param_name_for_filters: my_precious_filters | ||
| ``` | ||
|
|
||
| #### Dimensions |
There was a problem hiding this comment.
Suggestion: Ambiguous heading. The #### Dimensions heading is used as a sub-section under both links and html to describe the synthetic dimensions generated in the result set. Since this appears inside a page titled "Dimensions," the heading reads like a circular reference. Consider a more descriptive title like #### Generated dimensions or #### Synthetic dimensions in the result set to make it immediately clear what this sub-section covers.
- Add links validation schema to CubeValidator.ts (label, url, icon, target, params, propagate_filters_to_params, param_name_for_filters) - Add LinkDefinition type to CubeEvaluator.ts - Add links to DimensionConfig and ExtendedCubeSymbolDefinition types in CubeToMetaTransformer.ts for /v1/meta exposure - Generate synthetic link URL columns in BaseQuery.js when includeLinks option is set (only url is rendered as SQL; label/icon/target are constant metadata exposed via /v1/meta) - Add includeLinks flag to Query type and query validation schema - Wire includeLinks through /v1/cubesql endpoint via request options stored on SQLServer, injected into the sql callback query - Add unit tests for links feature Co-authored-by: Pavel Tiunov <pavel.tiunov@gmail.com>
github-actions
Bot
added
the
javascript
The url field in links is now a SQL function (like mask.sql) that gets
evaluated through the standard evaluateSql/autoPrefixAndEvaluateSql
pipeline. This means:
- url uses standard {CUBE}.column and {dimension} references
- url supports any SQL expression (CONCAT, CASE, etc.)
- No custom template parsing is needed
The url is no longer exposed in /v1/meta (it's a server-side SQL
expression). Only constant metadata (label, icon, target, params config)
is exposed in meta. The computed URL value appears only as a SQL column
in query results when includeLinks is set.
Co-authored-by: Pavel Tiunov <pavel.tiunov@gmail.com>
- Add include_links to BaseQueryOptionsStatic and pass it through BaseQuery → QueryTools - Create LinkItem bridge (cube_bridge/link_item.rs) with url sql field - Add links() method to DimensionDefinition bridge trait - Compile link url SQL calls in DimensionSymbolFactory and store them as link_url_sqls on DimensionSymbol - Add includeLinks to buildSqlAndParamsRust query params in BaseQuery.js The link URL SQL expressions are compiled and stored on DimensionSymbol, ready to be projected as additional columns when the query processor handles include_links. The actual projection in the physical plan builder will emit these as synthetic columns alongside their parent dimension. Co-authored-by: Pavel Tiunov <pavel.tiunov@gmail.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #10852 +/- ##
===========================================
+ Coverage 58.36% 83.47% +25.11%
===========================================
Files 216 254 +38
Lines 16939 75350 +58411
Branches 3435 0 -3435
===========================================
+ Hits 9887 62901 +53014
- Misses 6550 12449 +5899
+ Partials 502 0 -502
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
2 participants
Check List
Description of Changes Made
Implements the
linksfeature for dimensions in the data model, as specified in #10203.Documentation Changes
linksparameter (in bothdocs/content/anddocs-mintlify/reference/):urlis a standard SQL expression (likemask.sql) — uses{CUBE}.columnand{dimension}referenceslabel,icon,target,params,propagate_filters_to_params,param_name_for_filters/v1/metasyntheticparameter: Documents the internal marker for auto-generated dimensions.Context variables cross-reference: Updated
FILTER_PARAMSto mention link construction.Code Changes — JS (BaseQuery / Legacy Path)
Schema Compiler (
packages/cubejs-schema-compiler):CubeValidator.ts: Addedlinksvalidation schema.urlisJoi.func()— a SQL function evaluated through the standard pipeline, same asmask.sqlCubeEvaluator.ts: AddedLinkDefinitiontype toDimensionDefinitionCubeToMetaTransformer.ts: Links metadata exposed via/v1/meta(label, icon, target, params config — NOT the raw sql url)BaseQuery.js: WhenincludeLinks: true, generates synthetic SQL columns usingautoPrefixAndEvaluateSql(cubeName, link.url)— the exact same mechanism used formask.sqlAPI Gateway (
packages/cubejs-api-gateway):query.ts/query.js: AddedincludeLinksto theQuerytype and validation schemagateway.ts:/v1/cubesqlendpoint acceptsincludeLinksin request bodysql-server.ts: Request option storage; injectsincludeLinksinto the Cube query in thesqlcallbackCode Changes — Rust (Tesseract / Native SQL Planner)
cubesqlplannercrate:cube_bridge/link_item.rs: NewLinkItembridge trait withurl(MemberSql) and staticlabel/icon/targetcube_bridge/dimension_definition.rs: Addedlinks()method returningVec<Rc<dyn LinkItem>>cube_bridge/base_query_options.rs: Addedinclude_linkstoBaseQueryOptionsStaticplanner/query_tools.rs: Addedinclude_linksfield and getterplanner/base_query.rs: Passesinclude_linksthrough toQueryToolsplanner/symbols/dimension_symbol.rs: Addedlink_url_sqls: Vec<Rc<SqlCall>>field, compiled from link definitions inDimensionSymbolFactory::build, with getter onDimensionSymbolDesign
urlis a standard SQL function, just likemask.sql— no custom template parsingurl: "CONCAT('https://www.google.com/search?q=', {CUBE}.full_name)"autoPrefixAndEvaluateSql(JS) /compile_sql_call(Rust)<dim>___link_<id>_url); other fields (label, icon, target) are constants in/v1/metaincludeLinksflag works for both/v1/load(JSON API) and/v1/cubesql(SQL-over-REST)