feat(schema-compiler): expose custom granularities via meta API (#8703)

* Add DimensionGranularity to Meta OpenAPI Spec

* feat(schema-compiler): expose custom granularities via meta API

* add unit test for custom granularities in meta

* add an optional title to custom granularity

* Add tests for granularities with and w/o title in meta

Author: KSDaemon

packages/cubejs-api-gateway/openspec.yml

@@ -98,6 +98,16 @@ components:
           type: "string"
         shortTitle:
           type: "string"
+    V1CubeMetaDimensionGranularity:
+      type: "object"
+      required:
+        - name
+        - title
+      properties:
+        name:
+          type: "string"
+        title:
+          type: "string"
     V1CubeMetaDimension:
       type: "object"
       required:
@@ -110,6 +120,10 @@ components:
           type: "string"
         type:
           type: "string"
+        granularities:
+          type: array
+          items:
+            $ref: "#/components/schemas/V1CubeMetaDimensionGranularity"
     V1CubeMetaMeasure:
       type: "object"
       required:

packages/cubejs-schema-compiler/src/compiler/CubeToMetaTransformer.js

@@ -39,7 +39,7 @@ export class CubeToMetaTransformer {
    */
   transform(cube) {
     const cubeTitle = cube.title || this.titleize(cube.name);
-    
+
     const isCubeVisible = this.isVisible(cube, true);
 
     return {
@@ -80,6 +80,13 @@ export class CubeToMetaTransformer {
               ? this.isVisible(nameToDimension[1], !nameToDimension[1].primaryKey)
               : false,
             primaryKey: !!nameToDimension[1].primaryKey,
+            granularities:
+              nameToDimension[1].granularities
+                ? R.compose(R.map((g) => ({
+                  name: g[0],
+                  title: this.title(cubeTitle, g, true),
+                })), R.toPairs)(nameToDimension[1].granularities)
+                : undefined,
           })),
           R.toPairs
         )(cube.dimensions || {}),

packages/cubejs-schema-compiler/src/compiler/CubeValidator.ts

@@ -111,6 +111,7 @@ const BaseDimensionWithoutSubQuery = {
     then: Joi.object().pattern(identifierRegex,
       Joi.alternatives([
         Joi.object().keys({
+          title: Joi.string(),
           interval: GranularityInterval.required(),
           origin: Joi.string().required().custom((value, helpers) => {
             const date = new Date(value);
@@ -122,6 +123,7 @@ const BaseDimensionWithoutSubQuery = {
           }),
         }),
         Joi.object().keys({
+          title: Joi.string(),
           interval: GranularityInterval.required().custom((value, helper) => {
             const intParsed = value.split(' ');
             const msg = { custom: 'Arbitrary intervals cannot be used without origin point specified' };

packages/cubejs-schema-compiler/test/unit/cube-validator.test.ts

@@ -603,7 +603,8 @@ describe('Cube Validation', () => {
       {
         const cube = newCube({
           half_year: {
-            interval: '6 months'
+            interval: '6 months',
+            title: 'Half year intervals'
           }
         });
 
@@ -675,6 +676,7 @@ describe('Cube Validation', () => {
           half_year: {
             interval: '6 months',
             offset: '4 weeks 5 days 6 hours',
+            title: 'Half year intervals title'
           }
         });
 
@@ -794,6 +796,7 @@ describe('Cube Validation', () => {
           half_year: {
             interval: '15 days',
             offset: '1 hours 7 minutes 8 seconds',
+            title: 'Just title'
           }
         });
 
@@ -884,6 +887,7 @@ describe('Cube Validation', () => {
           half_year: {
             interval: '10 months',
             origin: '2024-04',
+            title: 'Someone loves number 10'
           }
         });
 

packages/cubejs-schema-compiler/test/unit/schema.test.ts

@@ -1,5 +1,5 @@
 import { prepareCompiler } from './PrepareCompiler';
-import { createCubeSchema } from './utils';
+import { createCubeSchema, createCubeSchemaWithCustomGranularities } from './utils';
 
 describe('Schema Testing', () => {
   const schemaCompile = async () => {
@@ -294,6 +294,33 @@ describe('Schema Testing', () => {
     expect(segments.find((segment) => segment.name === 'CubeA.sfUsers').description).toBe('SF users segment from createCubeSchema');
   });
 
+  it('custom granularities in meta', async () => {
+    const { compiler, metaTransformer } = prepareCompiler([
+      createCubeSchemaWithCustomGranularities('orders')
+    ]);
+    await compiler.compile();
+
+    const { dimensions } = metaTransformer.cubes[0].config;
+
+    expect(dimensions).toBeDefined();
+    expect(dimensions.length).toBeGreaterThan(0);
+
+    const dg = dimensions.find((dimension) => dimension.name === 'orders.createdAt');
+    expect(dg).toBeDefined();
+    expect(dg.granularities).toBeDefined();
+    expect(dg.granularities.length).toBeGreaterThan(0);
+
+    // Granularity defined with title
+    let gr = dg.granularities.find(g => g.name === 'half_year');
+    expect(gr).toBeDefined();
+    expect(gr.title).toBe('6 month intervals');
+
+    // // Granularity defined without title -> titlize()
+    gr = dg.granularities.find(g => g.name === 'half_year_by_1st_june');
+    expect(gr).toBeDefined();
+    expect(gr.title).toBe('Half Year By1 St June');
+  });
+
   it('join types', async () => {
     const { compiler, cubeEvaluator } = prepareCompiler([
       createCubeSchema({

packages/cubejs-schema-compiler/test/unit/utils.ts

@@ -88,8 +88,10 @@ export function createCubeSchemaWithCustomGranularities(name: string): string {
             granularities: {
               half_year: {
                 interval: '6 months',
+                title: '6 month intervals'
               },
               half_year_by_1st_april: {
+                title: 'Half year from Apr to Oct',
                 interval: '6 months',
                 offset: '3 months'
               },

packages/cubejs-schema-compiler/test/unit/yaml-schema.test.ts

@@ -324,10 +324,12 @@ describe('Yaml Schema Testing', () => {
               granularities:
                 - name: six_months
                   interval: 6 months
+                  title: 6 month intervals
                 - name: three_months_offset
                   interval: 3 months
                   offset: 2 weeks
                 - name: fiscal_year_1st_april
+                  title: Fiscal year by Apr
                   interval: 1 year
                   origin: >
                     2024-04-01