From c164aab31ec106bcff8dd26c305c3129a205f851 Mon Sep 17 00:00:00 2001
From: Pavel Tiunov <pavel.tiunov@gmail.com>
Date: Sat, 16 May 2026 20:26:04 -0700
Subject: [PATCH] fix(schema-compiler): resolve time dimension granularity
 columns in pre-aggregation indexes (#10894)

---
 .../data-modeling/pre-aggregations.mdx        |  55 ++++++-
 .../reference/pre-aggregations.mdx            |  55 ++++++-
 .../src/adapter/BaseQuery.js                  |  11 ++
 .../src/compiler/CubeEvaluator.ts             |   6 +-
 .../test/unit/pre-aggregations.test.ts        | 144 ++++++++++++++++++
 .../smoke/schema/OrdersPAIndexGranularity.js  |  61 ++++++++
 .../test/smoke-postgres.test.ts               |  69 +++++++++
 7 files changed, 388 insertions(+), 13 deletions(-)
 create mode 100644 packages/cubejs-testing/birdbox-fixtures/smoke/schema/OrdersPAIndexGranularity.js

diff --git a/docs-mintlify/reference/data-modeling/pre-aggregations.mdx b/docs-mintlify/reference/data-modeling/pre-aggregations.mdx
index 04eded6b6d99d..46e983ee14ee1 100644
--- a/docs-mintlify/reference/data-modeling/pre-aggregations.mdx
+++ b/docs-mintlify/reference/data-modeling/pre-aggregations.mdx
@@ -1571,9 +1571,8 @@ cube(`orders`, {
 
 </CodeGroup>
 
-In the case that you want to reference the time dimension in the index,
-the column name as a string in the following format can be used:
-`<cube name>__<time dimension name>_<granularity>`:
+To reference a time dimension column with its granularity in the index,
+use the `CUBE.<time_dimension>.<granularity>` syntax:
 
 <CodeGroup>
 
@@ -1594,8 +1593,7 @@ cubes:
           - name: category_created_at_index
             columns:
               - CUBE.category
-              # special syntax needed
-              - "{'orders__created_at_day'}"
+              - CUBE.created_at.day
     # ...
 ```
 
@@ -1613,6 +1611,53 @@ cube(`orders`, {
       ],
       time_dimension: CUBE.created_at,
       granularity: `day`,
+      indexes: {
+        category_created_at_index: {
+          columns: [
+            CUBE.category,
+            CUBE.created_at.day
+          ]
+        }
+      }
+    }
+  },
+
+  // ...
+})
+```
+
+</CodeGroup>
+
+Alternatively, you can reference the time dimension column as a string
+using the `<cube_name>__<time_dimension_name>_<granularity>` format:
+
+<CodeGroup>
+
+```yaml title="YAML"
+cubes:
+  - name: orders
+    # ...
+
+    pre_aggregations:
+      - name: category_and_date
+        # ...
+
+        indexes:
+          - name: category_created_at_index
+            columns:
+              - CUBE.category
+              - "{'orders__created_at_day'}"
+    # ...
+```
+
+```javascript title="JavaScript"
+cube(`orders`, {
+  // ...
+
+  pre_aggregations: {
+    category_and_date: {
+      // ...
+
       indexes: {
         category_created_at_index: {
           columns: [
diff --git a/docs/content/product/data-modeling/reference/pre-aggregations.mdx b/docs/content/product/data-modeling/reference/pre-aggregations.mdx
index 867a466168a2b..4172e88618a9b 100644
--- a/docs/content/product/data-modeling/reference/pre-aggregations.mdx
+++ b/docs/content/product/data-modeling/reference/pre-aggregations.mdx
@@ -1571,9 +1571,8 @@ cubes:
 
 </CodeTabs>
 
-In the case that you want to reference the time dimension in the index,
-the column name as a string in the following format can be used:
-`<cube name>__<time dimension name>_<granularity>`:
+To reference a time dimension column with its granularity in the index,
+use the `CUBE.<time_dimension>.<granularity>` syntax:
 
 <CodeTabs>
 
@@ -1595,7 +1594,7 @@ cube(`orders`, {
         category_created_at_index: {
           columns: [
             CUBE.category,
-            `orders__created_at_day`
+            CUBE.created_at.day
           ]
         }
       }
@@ -1623,7 +1622,53 @@ cubes:
           - name: category_created_at_index
             columns:
               - CUBE.category
-              # special syntax needed
+              - CUBE.created_at.day
+    # ...
+```
+
+</CodeTabs>
+
+Alternatively, you can reference the time dimension column as a string
+using the `<cube_name>__<time_dimension_name>_<granularity>` format:
+
+<CodeTabs>
+
+```javascript
+cube(`orders`, {
+  // ...
+
+  pre_aggregations: {
+    category_and_date: {
+      // ...
+
+      indexes: {
+        category_created_at_index: {
+          columns: [
+            CUBE.category,
+            `orders__created_at_day`
+          ]
+        }
+      }
+    }
+  },
+
+  // ...
+})
+```
+
+```yaml
+cubes:
+  - name: orders
+    # ...
+
+    pre_aggregations:
+      - name: category_and_date
+        # ...
+
+        indexes:
+          - name: category_created_at_index
+            columns:
+              - CUBE.category
               - "{'orders__created_at_day'}"
     # ...
 ```
diff --git a/packages/cubejs-schema-compiler/src/adapter/BaseQuery.js b/packages/cubejs-schema-compiler/src/adapter/BaseQuery.js
index 24bc94423b54b..e96753f27c589 100644
--- a/packages/cubejs-schema-compiler/src/adapter/BaseQuery.js
+++ b/packages/cubejs-schema-compiler/src/adapter/BaseQuery.js
@@ -4273,6 +4273,17 @@ export class BaseQuery {
           this.cubeEvaluator.isSegment(path)
         )
       ) {
+        if (path.length === 3 && this.cubeEvaluator.isDimension(path.slice(0, 2))) {
+          const dimensionDef = this.cubeEvaluator.dimensionByPath(path.slice(0, 2));
+          if (dimensionDef.type === 'time' &&
+            this.cubeEvaluator.resolveGranularity([path[0], path[1], 'granularities', path[2]])) {
+            const td = this.newTimeDimension({
+              dimension: `${path[0]}.${path[1]}`,
+              granularity: path[2],
+            });
+            return td.unescapedAliasName();
+          }
+        }
         return this.aliasName(column);
       } else {
         return column;
diff --git a/packages/cubejs-schema-compiler/src/compiler/CubeEvaluator.ts b/packages/cubejs-schema-compiler/src/compiler/CubeEvaluator.ts
index 2866c6f5d29a0..6e4a98d397db4 100644
--- a/packages/cubejs-schema-compiler/src/compiler/CubeEvaluator.ts
+++ b/packages/cubejs-schema-compiler/src/compiler/CubeEvaluator.ts
@@ -832,15 +832,15 @@ export class CubeEvaluator extends CubeSymbols {
     return this.isInstanceOfType('segments', path);
   }
 
-  public measureByPath(measurePath: string): MeasureDefinition {
+  public measureByPath(measurePath: string | string[]): MeasureDefinition {
     return this.byPath('measures', measurePath) as MeasureDefinition;
   }
 
-  public dimensionByPath(dimensionPath: string): DimensionDefinition {
+  public dimensionByPath(dimensionPath: string | string[]): DimensionDefinition {
     return this.byPath('dimensions', dimensionPath) as DimensionDefinition;
   }
 
-  public segmentByPath(segmentPath: string): SegmentDefinition {
+  public segmentByPath(segmentPath: string | string[]): SegmentDefinition {
     return this.byPath('segments', segmentPath) as SegmentDefinition;
   }
 
diff --git a/packages/cubejs-schema-compiler/test/unit/pre-aggregations.test.ts b/packages/cubejs-schema-compiler/test/unit/pre-aggregations.test.ts
index 634d3ad49c2b5..9e39b56c84f6b 100644
--- a/packages/cubejs-schema-compiler/test/unit/pre-aggregations.test.ts
+++ b/packages/cubejs-schema-compiler/test/unit/pre-aggregations.test.ts
@@ -364,6 +364,150 @@ describe('pre-aggregations', () => {
     expect(indexesSql[1].indexName).toEqual('orders_indexes_orders_by_day_with_day_by_status_agg_index');
   });
 
+  it('pre-aggregation index with time dimension granularity column', async () => {
+    const { compiler, cubeEvaluator, joinGraph } = prepareJsCompiler(
+      `
+        cube('Orders', {
+          sql: \`SELECT * FROM orders\`,
+
+          measures: {
+            count: {
+              type: 'count',
+            },
+          },
+
+          dimensions: {
+            created_at: {
+              sql: \`created_at\`,
+              type: 'time',
+            },
+            status: {
+              sql: \`status\`,
+              type: 'string',
+            },
+          },
+
+          preAggregations: {
+            ordersByHour: {
+              measures: [CUBE.count],
+              dimensions: [CUBE.status],
+              timeDimension: CUBE.created_at,
+              granularity: 'hour',
+              indexes: {
+                time_index: {
+                  columns: [CUBE.created_at.hour],
+                },
+                time_and_status_index: {
+                  columns: [CUBE.created_at.hour, CUBE.status],
+                },
+              },
+            },
+          },
+        });
+      `
+    );
+
+    await compiler.compile();
+
+    const query = new PostgresQuery({ joinGraph, cubeEvaluator, compiler }, {
+      measures: ['Orders.count'],
+      timeDimensions: [{
+        dimension: 'Orders.created_at',
+        granularity: 'hour',
+        dateRange: ['2023-01-01', '2023-01-10']
+      }],
+      dimensions: ['Orders.status']
+    });
+
+    const preAggregationsDescription: any = query.preAggregations?.preAggregationsDescription();
+    expect(preAggregationsDescription.length).toBeGreaterThan(0);
+
+    const { indexesSql, createTableIndexes } = preAggregationsDescription[0];
+    expect(indexesSql.length).toEqual(2);
+
+    const [timeIndexSql] = indexesSql[0].sql;
+    expect(timeIndexSql).toContain('"orders__created_at_hour"');
+    expect(timeIndexSql).not.toContain('"orders__created_at__hour"');
+
+    const [timeAndStatusIndexSql] = indexesSql[1].sql;
+    expect(timeAndStatusIndexSql).toContain('"orders__created_at_hour"');
+    expect(timeAndStatusIndexSql).toContain('"orders__status"');
+
+    expect(createTableIndexes[0].columns).toContain('"orders__created_at_hour"');
+    expect(createTableIndexes[1].columns).toContain('"orders__created_at_hour"');
+    expect(createTableIndexes[1].columns).toContain('"orders__status"');
+  });
+
+  it('pre-aggregation index with time dimension granularity column (YAML)', async () => {
+    const { compiler, cubeEvaluator, joinGraph } = prepareYamlCompiler(
+      createSchemaYaml({
+        cubes: [
+          {
+            name: 'orders',
+            sql_table: 'orders',
+            measures: [{
+              name: 'count',
+              type: 'count',
+            }],
+            dimensions: [
+              {
+                name: 'created_at',
+                sql: 'created_at',
+                type: 'time',
+              },
+              {
+                name: 'status',
+                sql: 'status',
+                type: 'string',
+              }
+            ],
+            preAggregations: [
+              {
+                name: 'orders_by_hour',
+                measures: ['count'],
+                dimensions: ['status'],
+                timeDimension: 'created_at',
+                granularity: 'hour',
+                indexes: [
+                  {
+                    name: 'time_granularity_index',
+                    columns: ['created_at.hour', 'status']
+                  }
+                ]
+              }
+            ]
+          },
+        ]
+      })
+    );
+
+    await compiler.compile();
+
+    const query = new PostgresQuery({ joinGraph, cubeEvaluator, compiler }, {
+      measures: ['orders.count'],
+      timeDimensions: [{
+        dimension: 'orders.created_at',
+        granularity: 'hour',
+        dateRange: ['2023-01-01', '2023-01-10']
+      }],
+      dimensions: ['orders.status']
+    });
+
+    const preAggregationsDescription: any = query.preAggregations?.preAggregationsDescription();
+    expect(preAggregationsDescription.length).toBeGreaterThan(0);
+
+    const { indexesSql, createTableIndexes } = preAggregationsDescription[0];
+    expect(indexesSql.length).toEqual(1);
+
+    const [indexSql] = indexesSql[0].sql;
+    expect(indexSql).toContain('"orders__created_at_hour"');
+    expect(indexSql).not.toContain('"orders__created_at__hour"');
+    expect(indexSql).toContain('"orders__status"');
+
+    expect(createTableIndexes[0].columns).toContain('"orders__created_at_hour"');
+    expect(createTableIndexes[0].columns).toContain('"orders__status"');
+  });
+
   it('pre-aggregation with FILTER_PARAMS', async () => {
     const { compiler, cubeEvaluator, joinGraph } = prepareYamlCompiler(
       createSchemaYaml({
diff --git a/packages/cubejs-testing/birdbox-fixtures/smoke/schema/OrdersPAIndexGranularity.js b/packages/cubejs-testing/birdbox-fixtures/smoke/schema/OrdersPAIndexGranularity.js
new file mode 100644
index 0000000000000..6f211f2dba6bb
--- /dev/null
+++ b/packages/cubejs-testing/birdbox-fixtures/smoke/schema/OrdersPAIndexGranularity.js
@@ -0,0 +1,61 @@
+cube(`OrdersPAIndexGranularity`, {
+  sql: `
+    select 1 as id, 100 as amount, 'new' status, '2024-01-01T10:00:00'::timestamp as created_at
+    UNION ALL
+    select 2 as id, 200 as amount, 'new' status, '2024-01-01T11:00:00'::timestamp as created_at
+    UNION ALL
+    select 3 as id, 300 as amount, 'processed' status, '2024-01-02T10:00:00'::timestamp as created_at
+    UNION ALL
+    select 4 as id, 500 as amount, 'processed' status, '2024-01-02T11:00:00'::timestamp as created_at
+    UNION ALL
+    select 5 as id, 600 as amount, 'shipped' status, '2024-01-03T10:00:00'::timestamp as created_at
+  `,
+
+  preAggregations: {
+    ordersByDay: {
+      measures: [CUBE.count, CUBE.totalAmount],
+      dimensions: [CUBE.status],
+      timeDimension: CUBE.createdAt,
+      granularity: `day`,
+      indexes: {
+        time_index: {
+          columns: [CUBE.createdAt.day],
+        },
+        time_and_status_index: {
+          columns: [CUBE.createdAt.day, CUBE.status],
+        },
+      },
+      refreshKey: {
+        every: `1 hour`,
+      },
+    },
+  },
+
+  measures: {
+    count: {
+      type: `count`,
+    },
+
+    totalAmount: {
+      sql: `amount`,
+      type: `sum`,
+    },
+  },
+
+  dimensions: {
+    id: {
+      sql: `id`,
+      type: `number`,
+    },
+
+    status: {
+      sql: `status`,
+      type: `string`,
+    },
+
+    createdAt: {
+      sql: `created_at`,
+      type: `time`,
+    },
+  },
+});
diff --git a/packages/cubejs-testing/test/smoke-postgres.test.ts b/packages/cubejs-testing/test/smoke-postgres.test.ts
index 1d466e91fcc01..c97d78ee0e7a9 100644
--- a/packages/cubejs-testing/test/smoke-postgres.test.ts
+++ b/packages/cubejs-testing/test/smoke-postgres.test.ts
@@ -72,6 +72,75 @@ describe('postgres pa', () => {
     ]);
   });
 
+  test('query pre-aggregation with granularity-based index', async () => {
+    const query: Query = {
+      measures: ['OrdersPAIndexGranularity.count', 'OrdersPAIndexGranularity.totalAmount'],
+      dimensions: ['OrdersPAIndexGranularity.status'],
+      timeDimensions: [{
+        dimension: 'OrdersPAIndexGranularity.createdAt',
+        granularity: 'day',
+        dateRange: ['2024-01-01', '2024-01-03'],
+      }],
+      order: {
+        'OrdersPAIndexGranularity.createdAt': 'asc',
+        'OrdersPAIndexGranularity.status': 'asc',
+      },
+    };
+    const result = await client.load(query);
+    expect(result.rawData()).toEqual([
+      {
+        'OrdersPAIndexGranularity.count': '2',
+        'OrdersPAIndexGranularity.createdAt': '2024-01-01T00:00:00.000',
+        'OrdersPAIndexGranularity.createdAt.day': '2024-01-01T00:00:00.000',
+        'OrdersPAIndexGranularity.status': 'new',
+        'OrdersPAIndexGranularity.totalAmount': '300',
+      },
+      {
+        'OrdersPAIndexGranularity.count': '2',
+        'OrdersPAIndexGranularity.createdAt': '2024-01-02T00:00:00.000',
+        'OrdersPAIndexGranularity.createdAt.day': '2024-01-02T00:00:00.000',
+        'OrdersPAIndexGranularity.status': 'processed',
+        'OrdersPAIndexGranularity.totalAmount': '800',
+      },
+      {
+        'OrdersPAIndexGranularity.count': '1',
+        'OrdersPAIndexGranularity.createdAt': '2024-01-03T00:00:00.000',
+        'OrdersPAIndexGranularity.createdAt.day': '2024-01-03T00:00:00.000',
+        'OrdersPAIndexGranularity.status': 'shipped',
+        'OrdersPAIndexGranularity.totalAmount': '600',
+      },
+    ]);
+  });
+
+  test('pre-aggregation index with granularity has correct SQL', async () => {
+    const id = 'OrdersPAIndexGranularity.ordersByDay';
+
+    const partitionsResponse = await (await fetch(`${birdbox.configuration.systemUrl}/pre-aggregations/partitions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        query: {
+          preAggregations: [{ id }]
+        }
+      }),
+    })).json();
+
+    const partitions = partitionsResponse.preAggregationPartitions;
+    expect(partitions.length).toEqual(1);
+    expect(partitions[0].partitions.length).toBeGreaterThan(0);
+
+    const partition = partitions[0].partitions[0];
+    expect(partition.indexesSql.length).toEqual(2);
+
+    const [timeIndexSql] = partition.indexesSql[0].sql;
+    expect(timeIndexSql).toContain('orders_p_a_index_granularity__created_at_day');
+    expect(timeIndexSql).not.toContain('orders_p_a_index_granularity__created_at__day');
+
+    const [timeAndStatusIndexSql] = partition.indexesSql[1].sql;
+    expect(timeAndStatusIndexSql).toContain('orders_p_a_index_granularity__created_at_day');
+    expect(timeAndStatusIndexSql).toContain('orders_p_a_index_granularity__status');
+  });
+
   test('preview', async () => {
     const id = 'OrdersPA.ordersByStatus';