feat(data-marts): unified column identifiers for output control filters (#1329)

* feat(data-marts): unified column identifiers for output control filters

Slice (pre-join) filters now reference a column by the same fully qualified identifier as post-join filters (e.g. category_details__item_event_count) instead of a raw column name plus a separate aliasPath. A single blended-field index resolves the unified name to its source/CTE/raw column for both validation and SQL generation across all storages; the wire schema and OpenAPI contract drop aliasPath, and a TypeORM migration converts existing reports. The frontend slice UI emits the unified identifier.

* style(web): wrap long line in FilterRow to satisfy prettier

Author: zapolsky

.changeset/unified-column-identifiers.md

@@ -0,0 +1,11 @@
+---
+'owox': minor
+---
+
+# Unified column identifiers for output control filters
+
+Slice (pre-join) filters now reference a column by the same fully qualified identifier as
+regular output filters — for example `category_details__item_event_count` — instead of a raw
+column name plus a separate `aliasPath`. This makes every filter, slice, and sort refer to a
+column the same way across the API and the Web/Extension report editor. Existing saved reports
+are migrated automatically, so no manual changes are needed.

apps/backend/src/data-marts/controllers/spec/report-openapi.ts

@@ -127,7 +127,11 @@ export class ReportRelativeDateFilterValueApiDto {
 }
 
 export class ReportFilterRuleApiDto {
-  @ApiProperty({ minLength: 1 })
+  @ApiProperty({
+    minLength: 1,
+    description:
+      'Output column name. For slice filters (placement=pre-join), use the fully qualified blended column identifier, e.g. category_details__item_event_count.',
+  })
   column: string;
 
   @ApiProperty({
@@ -156,14 +160,6 @@ export class ReportFilterRuleApiDto {
     description: 'Use pre-join for slice filters. Omit for normal output filters.',
   })
   placement?: 'pre-join' | 'post-join';
-
-  @ApiPropertyOptional({
-    minLength: 1,
-    maxLength: 255,
-    pattern: '^[a-z0-9_]+(\\.[a-z0-9_]+)*$',
-    description: 'Required for slice filters when placement is pre-join.',
-  })
-  aliasPath?: string;
 }
 
 export class ReportSortRuleApiDto {
@@ -232,7 +228,8 @@ const commonReportRequestProperties = {
     nullable: true,
     maxItems: 50,
     items: { $ref: getSchemaPath(ReportFilterRuleApiDto) },
-    description: 'Output filters. Use placement=pre-join and aliasPath for slice filters.',
+    description:
+      'Output filters. Use placement=pre-join for slice filters (column = unified blended identifier).',
   },
   sortConfig: {
     type: 'array',

apps/backend/src/data-marts/controllers/spec/report.openapi.spec.ts

@@ -127,7 +127,10 @@ describe('ReportController OpenAPI', () => {
     );
     expect(filterRule.properties.value.oneOf).toHaveLength(3);
     expect(filterRule.properties.placement.enum).toEqual(['pre-join', 'post-join']);
-    expect(filterRule.properties.aliasPath.description).toContain('slice');
+    expect(filterRule.properties.aliasPath).toBeUndefined();
+    expect(filterRule.properties.column.description).toContain(
+      'category_details__item_event_count'
+    );
 
     expect(updateProperties.sortConfig).toMatchObject({
       type: 'array',

apps/backend/src/data-marts/data-storage-types/athena/services/athena-blended-query-builder.spec.ts

@@ -8,6 +8,7 @@ import {
 import { AthenaBlendedQueryBuilder } from './athena-blended-query-builder';
 import { AthenaClauseRenderer } from './athena-clause-renderer';
 import { BlendedQueryContext } from '../../interfaces/blended-query-builder.interface';
+import { buildBlendedFieldIndex } from '../../../services/blended-field-index';
 
 const buildContext = createBuildContext('"mydb"."customers"');
 
@@ -202,20 +203,26 @@ describe('AthenaBlendedQueryBuilder — output controls', () => {
         { targetFieldName: 'role', outputAlias: 'role', isHidden: true, aggregateFunction: 'MAX' },
       ],
     });
+    const fieldIndex = buildBlendedFieldIndex({
+      blendedFields: [
+        { name: 'users__role', aliasPath: 'users', originalFieldName: 'role', type: 'STRING' },
+      ],
+      availableSources: [{ aliasPath: 'users', isIncluded: true }],
+    } as never);
     const { params } = builder.buildBlendedQuery(
       ctx({
         chains: [chain],
         columns: ['a'],
         filters: [
           {
-            column: 'role',
+            column: 'users__role',
             operator: 'eq',
             value: 'admin',
             placement: 'pre-join',
-            aliasPath: 'users',
           },
           { column: 'a', operator: 'eq', value: 'post', placement: 'post-join' },
         ],
+        fieldIndex,
       })
     );
     // pre-join value first (lives inside the users_raw CTE), post-join value last.
@@ -253,20 +260,30 @@ describe('AthenaBlendedQueryBuilder — output controls', () => {
         },
       ],
     });
+    const fieldIndex = buildBlendedFieldIndex({
+      blendedFields: [
+        {
+          name: 'users__signup_date',
+          aliasPath: 'users',
+          originalFieldName: 'signup_date',
+          type: 'DATE',
+        },
+      ],
+      availableSources: [{ aliasPath: 'users', isIncluded: true }],
+    } as never);
     const { sql, params } = builder.buildBlendedQuery(
       ctx({
         chains: [chain],
         columns: ['a'],
         filters: [
           {
-            column: 'signup_date',
+            column: 'users__signup_date',
             operator: 'gte',
             value: '2024-01-01',
             placement: 'pre-join',
-            aliasPath: 'users',
           },
         ],
-        columnTypes: { preJoin: new Map([['users', new Map([['signup_date', 'DATE']])]]) },
+        fieldIndex,
       })
     );
     expect(sql).toContain('signup_date >= CAST(? AS DATE)');

apps/backend/src/data-marts/data-storage-types/bigquery/services/bigquery-blended-query-builder-edge-cases.spec.ts

@@ -1,4 +1,5 @@
 import { BlendedQueryContext } from '../../interfaces/blended-query-builder.interface';
+import { buildBlendedFieldIndex } from '../../../services/blended-field-index';
 import {
   makeChain,
   makeRelationship,
@@ -122,6 +123,17 @@ describe('BigQueryBlendedQueryBuilder — SQL safety / quoting', () => {
       ],
     });
 
+    const fieldIndex = buildBlendedFieldIndex({
+      blendedFields: [
+        {
+          name: 'users__first name',
+          aliasPath: 'users',
+          originalFieldName: 'first name',
+          type: 'STRING',
+        },
+      ],
+      availableSources: [{ aliasPath: 'users', isIncluded: true }],
+    } as never);
     const ctx: BlendedQueryContext = {
       mainTableReference: '`project.dataset.events`',
       mainDataMartTitle: 'Events',
@@ -130,12 +142,12 @@ describe('BigQueryBlendedQueryBuilder — SQL safety / quoting', () => {
       columns: ['event_id', 'first_name_agg'],
       filters: [
         {
-          column: 'first name',
+          column: 'users__first name',
           operator: 'is_not_null',
           placement: 'pre-join',
-          aliasPath: 'users',
         },
       ],
+      fieldIndex,
     };
 
     const { sql } = builder.buildBlendedQuery(ctx);

apps/backend/src/data-marts/data-storage-types/databricks/services/databricks-blended-query-builder.spec.ts

@@ -8,6 +8,7 @@ import {
 import { DatabricksBlendedQueryBuilder } from './databricks-blended-query-builder';
 import { DatabricksClauseRenderer } from './databricks-clause-renderer';
 import { BlendedQueryContext } from '../../interfaces/blended-query-builder.interface';
+import { buildBlendedFieldIndex } from '../../../services/blended-field-index';
 
 const buildContext = createBuildContext('`catalog`.`schema`.`customers`');
 
@@ -177,19 +178,25 @@ describe('DatabricksBlendedQueryBuilder — output controls', () => {
         { targetFieldName: 'role', outputAlias: 'role', isHidden: true, aggregateFunction: 'MAX' },
       ],
     });
+    const fieldIndex = buildBlendedFieldIndex({
+      blendedFields: [
+        { name: 'users__role', aliasPath: 'users', originalFieldName: 'role', type: 'STRING' },
+      ],
+      availableSources: [{ aliasPath: 'users', isIncluded: true }],
+    } as never);
     const { sql, params } = builder.buildBlendedQuery(
       ctx({
         chains: [chain],
         columns: ['a'],
         filters: [
           {
-            column: 'role',
+            column: 'users__role',
             operator: 'eq',
             value: 'admin',
             placement: 'pre-join',
-            aliasPath: 'users',
           },
         ],
+        fieldIndex,
       })
     );
     // The inlined predicate must sit inside the subsidiary raw CTE, before the outer SELECT.