fix(oracle): resolve bind parameter mismatch for generated time series

Refactor Oracle date/time casting logic to properly handle column
identifiers from generated time series (date_from/date_to) without
treating them as bind parameters.

Previously, all values passed to dateTimeCast/timeStampCast were
treated as bind parameters, causing Oracle NJS-098 errors when
queries with rolling windows generated 10 bind placeholders but only
6 parameter values.

Changes:
- Add helper methods isIdentifierToken() and toTimestampTz() to
  centralize casting logic
- Detect column identifiers vs bind parameters ('?')
- Use direct column references for generated series columns
- Preserve bind parameters for filter values only
- Add comprehensive JSDoc documentation

Fixes bind parameter count mismatch that caused NJS-098 errors.

Author: Tankilevitch

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

@@ -30,6 +30,42 @@ class OracleFilter extends BaseFilter {
 }
 
 export class OracleQuery extends BaseQuery {
+  private static readonly ORACLE_TZ_FORMAT_WITH_Z = 'YYYY-MM-DD"T"HH24:MI:SS.FF"Z"';
+
+  private static readonly ORACLE_TZ_FORMAT_NO_Z = 'YYYY-MM-DD"T"HH24:MI:SS.FF';
+
+  /**
+   * Determines if a value represents a SQL identifier (column name) rather than a bind parameter.
+   * Handles both unquoted identifiers (e.g., "date_from", "table.column") and quoted
+   * identifiers (e.g., "date_from", "table"."column").
+   */
+  private isIdentifierToken(value: string): boolean {
+    return (
+      /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(value) ||
+      /^"[^"]+"(\."[^"]+")*$/.test(value)
+    );
+  }
+
+  /**
+   * Generates Oracle TO_TIMESTAMP_TZ function call for timezone-aware timestamp conversion.
+   *
+   * @param value - Either '?' for bind parameters, a column identifier, or a SQL expression
+   * @param includeZFormat - Whether to include 'Z' suffix in format string (true for filter params)
+   * @returns Oracle SQL expression with appropriate bind placeholder or direct column reference
+   */
+  private toTimestampTz(value: string, includeZFormat: boolean): string {
+    const format = includeZFormat ? OracleQuery.ORACLE_TZ_FORMAT_WITH_Z : OracleQuery.ORACLE_TZ_FORMAT_NO_Z;
+    if (value === '?') {
+      return `TO_TIMESTAMP_TZ(:"?", '${format}')`;
+    }
+    if (this.isIdentifierToken(value)) {
+      // Column identifiers (e.g., date_from, date_to from generated time series) - use directly
+      return `TO_TIMESTAMP_TZ(${value}, '${format}')`;
+    }
+    // SQL expressions or literals - embed directly in TO_TIMESTAMP_TZ call
+    return `TO_TIMESTAMP_TZ(${value}, '${format}')`;
+  }
+
   /**
    * "LIMIT" on Oracle is illegal
    * TODO replace with limitOffsetClause override
@@ -75,15 +111,26 @@ export class OracleQuery extends BaseQuery {
     return field;
   }
 
+  /**
+   * Casts a value to Oracle DATE type using timezone-aware parsing.
+   * For bind parameters ('?'), includes 'Z' suffix in format string.
+   * For column identifiers (e.g., date_from/date_to from time series), omits 'Z'.
+   *
+   * @param value - Bind parameter placeholder '?', column identifier, or SQL expression
+   */
   public dateTimeCast(value) {
-    // Use timezone-aware parsing for ISO 8601 with milliseconds and trailing 'Z', then cast to DATE
-    // to preserve index-friendly comparisons against DATE columns.
-    return `CAST(TO_TIMESTAMP_TZ(:"${value}", 'YYYY-MM-DD"T"HH24:MI:SS.FF"Z"') AS DATE)`;
+    return `CAST(${this.toTimestampTz(value, value === '?')} AS DATE)`;
   }
 
+  /**
+   * Casts a value to Oracle TIMESTAMP WITH TIME ZONE.
+   * For bind parameters ('?'), includes 'Z' suffix in format string.
+   * For column identifiers (e.g., date_from/date_to from time series), omits 'Z'.
+   *
+   * @param value - Bind parameter placeholder '?', column identifier, or SQL expression
+   */
   public timeStampCast(value) {
-    // Return timezone-aware timestamp for TIMESTAMP comparisons
-    return `TO_TIMESTAMP_TZ(:"${value}", 'YYYY-MM-DD"T"HH24:MI:SS.FF"Z"')`;
+    return this.toTimestampTz(value, value === '?');
   }
 
   public timeStampParam(timeDimension) {

packages/cubejs-schema-compiler/test/unit/__snapshots__/error-reporter.test.ts.snap

@@ -6,8 +6,8 @@ Object {
     Object {
       "fileName": "test.js",
       "message": "Syntax Error: Duplicate error
-[0m[31m[1m>[22m[39m[90m 1 |[39m test content
- [90m   |[39m [31m[1m^[22m[39m[31m[1m^[22m[39m[31m[1m^[22m[39m [31m[1mDuplicate error[22m[39m[0m",
+> 1 | test content
+    | ^^^ Duplicate error",
       "plainMessage": "Syntax Error: Duplicate error",
     },
   ],
@@ -39,13 +39,13 @@ Validation error
 
 schema/users.js Errors:
 Syntax Error: Invalid measure definition
-[0m [90m 2 |[39m   sql[33m:[39m [32m\`SELECT * FROM users\`[39m[33m,[39m
- [90m 3 |[39m   measures[33m:[39m {
-[31m[1m>[22m[39m[90m 4 |[39m     count[33m:[39m {
- [90m   |[39m    [31m[1m^[22m[39m[31m[1m^[22m[39m[31m[1m^[22m[39m[31m[1m^[22m[39m[31m[1m^[22m[39m [31m[1mInvalid measure definition[22m[39m
- [90m 5 |[39m       type[33m:[39m [32m'count'[39m
- [90m 6 |[39m     }
- [90m 7 |[39m   }[0m
+  2 |   sql: \`SELECT * FROM users\`,
+  3 |   measures: {
+> 4 |     count: {
+    |    ^^^^^ Invalid measure definition
+  5 |       type: 'count'
+  6 |     }
+  7 |   }
 "
 `;
 
@@ -59,12 +59,12 @@ exports[`ErrorReporter should group and format errors and warnings from differen
 Array [
   "schema/users.js:
 Warning: Deprecated syntax
-[0m [90m 1 |[39m cube([32m'Users'[39m[33m,[39m {
-[31m[1m>[22m[39m[90m 2 |[39m   sql[33m:[39m [32m\`SELECT * FROM users\`[39m[33m,[39m
- [90m   |[39m  [31m[1m^[22m[39m[31m[1m^[22m[39m[31m[1m^[22m[39m [31m[1mDeprecated syntax[22m[39m
- [90m 3 |[39m   measures[33m:[39m {
- [90m 4 |[39m     count[33m:[39m {
- [90m 5 |[39m       type[33m:[39m [32m'count'[39m[0m",
+  1 | cube('Users', {
+> 2 |   sql: \`SELECT * FROM users\`,
+    |  ^^^ Deprecated syntax
+  3 |   measures: {
+  4 |     count: {
+  5 |       type: 'count'",
   "schema/orders.js:
 Consider adding indexes",
   "schema/analytics.js:

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

@@ -904,4 +904,36 @@ describe('OracleQuery', () => {
     expect(sql).toMatch(/GROUP BY\s+TRUNC/);
     expect(params).toEqual(['2024-01-01T00:00:00.000Z', '2024-12-31T23:59:59.999Z']);
   });
+
+  it('does not bind generated time series date_from/date_to', async () => {
+    await compiler.compile();
+
+    const query = new OracleQuery(
+      { joinGraph, cubeEvaluator, compiler },
+      {
+        measures: ['visitors.thisPeriod', 'visitors.priorPeriod'],
+        timeDimensions: [
+          {
+            dimension: 'visitors.createdAt',
+            dateRange: ['2023-01-01', '2024-12-31'],
+            granularity: 'year'
+          }
+        ],
+        filters: [
+          { member: 'visitors.source', operator: 'equals', values: ['web'] }
+        ],
+        timezone: 'UTC'
+      }
+    );
+
+    const [sql] = query.buildSqlAndParams();
+
+    // Ensure generated time series columns are not treated as bind params
+    expect(sql).not.toMatch(/:\s*"date_from"/);
+    expect(sql).not.toMatch(/:\s*"date_to"/);
+
+    // Ensure we cast series columns directly via TO_TIMESTAMP_TZ(..., '...FF') without binds
+    expect(sql).toMatch(/TO_TIMESTAMP_TZ\(date_from,\s*'YYYY-MM-DD"T"HH24:MI:SS\.FF'\)/);
+    expect(sql).toMatch(/TO_TIMESTAMP_TZ\(date_to,\s*'YYYY-MM-DD"T"HH24:MI:SS\.FF'\)/);
+  });
 });