feat: Add query-time offset parameter for predefined granularities

Adds support for a query-time `offset` parameter on timeDimensions that
allows shifting time boundaries for predefined granularities (day, week,
month, etc.). This enables use cases like:
- Days running 2am-2am instead of midnight-midnight
- Weeks starting on Wednesday instead of Monday

The offset parameter:
- Only works with predefined granularities (day, week, month, etc.)
- Throws a validation error if used with custom granularities
- Uses SQL interval syntax (e.g., "2 hours", "-30 minutes", "2 days")
- Is supported in REST API and GraphQL API

Includes comprehensive unit and integration tests demonstrating the
day-shifting and week-shifting use cases.

Author: hank-sq

packages/cubejs-api-gateway/src/graphql.ts

@@ -426,9 +426,11 @@ export function getJsonQuery(metaConfig: any, args: Record<string, any>, infos:
             if (granularityName === 'value') {
               dimensions.push(key);
             } else {
+              const offsetArg = getArgumentValue(granularityNode, 'offset', infos.variableValues);
               timeDimensions.push({
                 dimension: key,
                 granularity: granularityName,
+                ...(offsetArg ? { offset: offsetArg } : null),
                 ...(dateRangeFilters[key] ? {
                   dateRange: dateRangeFilters[key],
                 } : null)

packages/cubejs-api-gateway/src/query.js

@@ -172,12 +172,18 @@ const querySchema = Joi.object().keys({
   timeDimensions: Joi.array().items(Joi.object().keys({
     dimension: id.required(),
     granularity: Joi.string().max(128, 'utf8'), // Custom granularities may have arbitrary names
+    offset: Joi.string().max(128, 'utf8'), // Query-time granularity offset
     dateRange: [
       Joi.array().items(Joi.string()).min(1).max(2),
       Joi.string()
     ],
     compareDateRange: Joi.array()
-  }).oxor('dateRange', 'compareDateRange')),
+  }).oxor('dateRange', 'compareDateRange').custom((value, helpers) => {
+    if (value.offset && !value.granularity) {
+      return helpers.error('any.invalid', { message: 'offset can only be specified when granularity is also specified' });
+    }
+    return value;
+  })),
   order: Joi.alternatives(
     Joi.object().pattern(idOrMemberExpressionName, Joi.valid('asc', 'desc')),
     Joi.array().items(Joi.array().min(2).ordered(idOrMemberExpressionName, Joi.valid('asc', 'desc')))

packages/cubejs-api-gateway/src/types/query.ts

@@ -111,6 +111,7 @@ interface QueryTimeDimension {
   dateRange?: string[] | string;
   compareDateRange?: string[];
   granularity?: QueryTimeDimensionGranularity;
+  offset?: string;
 }
 
 type SubqueryJoins = {

packages/cubejs-client-core/src/types.ts

@@ -41,6 +41,7 @@ export interface TimeDimensionBase {
   dimension: string;
   granularity?: TimeDimensionGranularity;
   dateRange?: DateRange;
+  offset?: string;
 }
 
 export interface TimeDimensionComparison extends TimeDimensionBase {

packages/cubejs-client-dx/index.d.ts

@@ -25,6 +25,9 @@ declare module "@cubejs-client/core" {
 
   export interface TimeDimensionBase {
     dimension: IntrospectedTimeDimensionName;
+    granularity?: TimeDimensionGranularity;
+    dateRange?: DateRange;
+    offset?: string;
   }
 
   export interface BinaryFilter {

packages/cubejs-client-ngx/src/query-builder/query-members.ts

@@ -130,6 +130,10 @@ export class TimeDimensionMember {
     this.updateTimeDimension(by, { granularity });
   }
 
+  setOffset(by: string | number, offset: string) {
+    this.updateTimeDimension(by, { offset });
+  }
+
   asArray(): any[] {
     return (this.query.asCubeQuery().timeDimensions || []).map((td) => {
       return {

packages/cubejs-schema-compiler/src/adapter/Granularity.ts

@@ -34,8 +34,23 @@ export class Granularity {
     this.queryTimezone = query.timezone || 'UTC';
     this.origin = moment.tz(query.timezone).startOf('year'); // Defaults to current year start
 
+    // Query-time offset takes precedence over data model offset
+    const queryTimeOffset = timeDimension.offset;
+
     if (this.predefinedGranularity) {
       this.granularityInterval = `1 ${this.granularity}`;
+      // Support query-time offset for predefined granularities
+      if (queryTimeOffset) {
+        this.fixOriginForWeeksIfNeeded();
+        // Validate offset format
+        try {
+          const parsedOffset = parseSqlInterval(queryTimeOffset);
+          this.granularityOffset = queryTimeOffset;
+          this.origin = addInterval(this.origin, parsedOffset);
+        } catch (e) {
+          throw new Error(`Invalid offset format "${queryTimeOffset}". Expected SQL interval format like "2 hours", "-30 minutes", or "1 day 2 hours"`);
+        }
+      }
     } else {
       const customGranularity = this.query.cacheValue(
         ['customGranularity', timeDimension.dimension, this.granularity],
@@ -51,6 +66,8 @@ export class Granularity {
 
       if (customGranularity.origin) {
         this.origin = moment.tz(customGranularity.origin, query.timezone);
+      } else if (queryTimeOffset) {
+        throw new Error(`Query-time offset parameter cannot be used with custom granularity "${this.granularity}". Offset is only supported with predefined granularities (day, week, month, etc.)`);
       } else if (customGranularity.offset) {
         // Needed because if interval is week-based, offset is expected to be relative to the start of a week
         this.fixOriginForWeeksIfNeeded();

packages/cubejs-schema-compiler/test/integration/clickhouse/custom-granularities.test.ts

@@ -49,6 +49,9 @@ describe('Custom Granularities', () => {
             - name: two_weeks_by_friday
               interval: 2 weeks
               origin: '2024-08-23'
+            - name: one_week_by_friday_by_offset
+              interval: 1 week
+              offset: 4 days
             - name: one_hour_by_5min_offset
               interval: 1 hour
               offset: 5 minutes
@@ -564,4 +567,147 @@ describe('Custom Granularities', () => {
     ],
     { joinGraph, cubeEvaluator, compiler }
   ));
+
+  // Query-time offset tests
+  
+  // Test demonstrating day boundaries shifted to 2am-2am
+  it('works with query-time offset shifting day boundary (2am-2am)', async () => {
+    const { compiler: offsetCompiler, joinGraph: offsetJoinGraph, cubeEvaluator: offsetCubeEvaluator } = prepareYamlCompiler(`
+      cubes:
+        - name: events
+          sql: >
+            SELECT *
+            FROM (
+              SELECT 1 as event_id, toDateTime('2024-01-01 00:00:00') as event_time UNION ALL
+              SELECT 2, toDateTime('2024-01-01 01:00:00') UNION ALL
+              SELECT 3, toDateTime('2024-01-01 01:30:00') UNION ALL
+              SELECT 4, toDateTime('2024-01-02 00:00:00') UNION ALL
+              SELECT 5, toDateTime('2024-01-02 01:00:00') UNION ALL
+              SELECT 6, toDateTime('2024-01-02 01:30:00')
+            )
+
+          dimensions:
+            - name: event_id
+              sql: event_id
+              type: number
+              primary_key: true
+
+            - name: eventTime
+              sql: event_time
+              type: time
+
+          measures:
+            - name: count
+              type: count
+    `);
+    
+    await dbRunner.runQueryTest(
+      {
+        measures: ['events.count'],
+        timeDimensions: [{
+          dimension: 'events.eventTime',
+          granularity: 'day',
+          offset: '2 hours',
+          dateRange: ['2024-01-01', '2024-01-03']
+        }],
+        dimensions: [],
+        timezone: 'UTC',
+        order: [['events.eventTime', 'asc']],
+      },
+      [
+        {
+          events__event_time_day: '2023-12-31T02:00:00.000',
+          events__count: '3',
+        },
+        {
+          events__event_time_day: '2024-01-01T02:00:00.000',
+          events__count: '3',
+        },
+      ],
+      { joinGraph: offsetJoinGraph, cubeEvaluator: offsetCubeEvaluator, compiler: offsetCompiler }
+    );
+  });
+
+  // Test demonstrating week boundaries shifted to Wednesday-Wednesday
+  it('works with query-time offset shifting week to start on Wednesday', async () => {
+    const { compiler: weekCompiler, joinGraph: weekJoinGraph, cubeEvaluator: weekCubeEvaluator } = prepareYamlCompiler(`
+      cubes:
+        - name: activities
+          sql: >
+            SELECT *
+            FROM (
+              SELECT 1 as activity_id, toDateTime('2024-01-01 10:00:00') as activity_time UNION ALL
+              SELECT 2, toDateTime('2024-01-02 10:00:00') UNION ALL
+              SELECT 3, toDateTime('2024-01-03 10:00:00') UNION ALL
+              SELECT 4, toDateTime('2024-01-04 10:00:00') UNION ALL
+              SELECT 5, toDateTime('2024-01-08 10:00:00') UNION ALL
+              SELECT 6, toDateTime('2024-01-10 10:00:00')
+            )
+
+          dimensions:
+            - name: activity_id
+              sql: activity_id
+              type: number
+              primary_key: true
+
+            - name: activityTime
+              sql: activity_time
+              type: time
+
+          measures:
+            - name: count
+              type: count
+    `);
+    
+    await dbRunner.runQueryTest(
+      {
+        measures: ['activities.count'],
+        timeDimensions: [{
+          dimension: 'activities.activityTime',
+          granularity: 'week',
+          offset: '2 days',
+          dateRange: ['2024-01-01', '2024-01-15']
+        }],
+        dimensions: [],
+        timezone: 'UTC',
+        order: [['activities.activityTime', 'asc']],
+      },
+      [
+        {
+          activities__activity_time_week: '2024-01-03T00:00:00.000',
+          activities__count: '3',
+        },
+        {
+          activities__activity_time_week: '2024-01-10T00:00:00.000',
+          activities__count: '1',
+        },
+        {
+          activities__activity_time_week: '2023-12-27T00:00:00.000',
+          activities__count: '2',
+        },
+      ],
+      { joinGraph: weekJoinGraph, cubeEvaluator: weekCubeEvaluator, compiler: weekCompiler }
+    );
+  });
+
+  it('rejects query-time offset with custom granularity', async () => {
+    await expect(
+      dbRunner.runQueryTest(
+        {
+          measures: ['orders.count'],
+          timeDimensions: [{
+            dimension: 'orders.createdAt',
+            granularity: 'one_week_by_friday_by_offset',
+            offset: '2 days',
+            dateRange: ['2024-01-01', '2024-02-28']
+          }],
+          dimensions: [],
+          timezone: 'UTC',
+          order: [['orders.createdAt', 'asc']],
+        },
+        [],
+        { joinGraph, cubeEvaluator, compiler }
+      )
+    ).rejects.toThrow('Query-time offset parameter cannot be used with custom granularity');
+  });
 });