feat(analytics): analytics over federated objects honors the remote table (ADR-0062 Phase 3, D6) (#2200)

Author: xuyushun441-sys

.changeset/adr-0062-analytics-external.md

@@ -0,0 +1,20 @@
+---
+"@objectstack/spec": minor
+"@objectstack/service-analytics": minor
+---
+
+feat(analytics): correct analytics over federated objects (ADR-0062 Phase 3, D6)
+
+Analytics over an external (federated) object now aggregates against the
+**correct** remote table instead of silently querying the wrong one. The
+`NativeSQLStrategy` hand-compiles `FROM "<object>"` and bare column references,
+which bypass the driver's physical-table resolution (`external.remoteName` /
+`remoteSchema` / `columnMap`). It now **declines** any query whose base or joined
+object is federated, routing it to the `ObjectQLStrategy` — whose
+`engine.aggregate()` goes through the driver's `getBuilder` and already honours
+`remoteName`/`remoteSchema` (#2138/#2149). This "reuses the driver's resolution"
+(D6) rather than re-implementing it.
+
+Adds an optional `StrategyContext.isExternalObject(objectName)` hook (reported by
+the analytics plugin from the object's `external` block). Purely additive — with
+no hook, behavior is unchanged for managed objects.

docs/adr/0062-external-datasource-runtime.md

@@ -77,6 +77,8 @@ Code-defined datasources surface in `GET /api/v1/datasources`, `GET /api/v1/meta
 
 The analytics native-SQL strategy compiles its own `FROM "<table>"` / column references outside the driver (ADR-0015 §18 noted this). It must resolve an external object's physical table (`remoteName`/`remoteSchema`) and columns (`columnMap`) the same way `SqlDriver` now does — reusing the driver's resolution (e.g. an exposed `physicalTableFor(object)` / `physicalColumnFor(object, field)`), not a second copy. Until then, analytics over external objects stays disabled rather than silently querying the wrong table.
 
+> **Phase 3 implementation note (#2163) — "reuse the driver's resolution" = route external objects to the ObjectQL path.** Rather than re-implement `remoteName`/`remoteSchema`/`columnMap` resolution inside the native-SQL strategy (a second copy — explicitly rejected), `NativeSQLStrategy.canHandle` now **declines** any query whose base or joined object is federated (new optional `StrategyContext.isExternalObject` hook, reported by the analytics plugin from the object's `external` block). Declining routes the query to the lower-priority `ObjectQLStrategy`, whose `engine.aggregate()` already goes through the driver's `getBuilder` — which honours `remoteName`/`remoteSchema` (#2138/#2149). So external analytics aggregates against the **correct** remote table via the single source of truth (the driver), and native-SQL never queries the wrong table. (A native-SQL fast path for external objects can be added later by exposing `physicalTableFor`/`physicalColumnFor` on the driver; deeper `columnMap`-in-`GROUP BY` support is a separate driver concern.)
+
 ### D7 — `columnMap` is the external mechanism; reconcile `field.columnName`
 
 `external.columnMap` ({ remoteColumn → localField }) is the supported way to map external columns (shipped #2149). `field.columnName` (localField → physicalColumn) is its inverse and is **not** applied by the driver's query pipeline for external objects. Decision: for external objects, `columnMap` is authoritative; `field.columnName` on an external object is rejected at validation (no silent dual-source) until a unified column-resolution model is designed. Managed objects' `field.columnName` semantics are untouched.

packages/services/service-analytics/src/__tests__/native-sql-strategy-external.test.ts

@@ -0,0 +1,52 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// ADR-0062 D6 — the NativeSQLStrategy must DECLINE federated (external-datasource)
+// objects: its hand-compiled `FROM "<object>"` / bare column refs bypass the
+// driver's physical-table resolution (remoteName/remoteSchema/columnMap) and
+// would query the wrong table. Declining routes the query to the lower-priority
+// ObjectQL aggregate path, which goes through the driver's getBuilder (correct).
+
+import { describe, it, expect } from 'vitest';
+import { NativeSQLStrategy } from '../strategies/native-sql-strategy.js';
+import type { StrategyContext } from '../strategies/types.js';
+
+const baseCaps = { nativeSql: true, objectqlAggregate: true, inMemory: false };
+
+function ctxFor(cube: any, isExternalObject?: (o: string) => boolean): StrategyContext {
+  return {
+    getCube: () => cube,
+    queryCapabilities: () => baseCaps,
+    executeRawSql: async () => [],
+    ...(isExternalObject ? { isExternalObject } : {}),
+  } as unknown as StrategyContext;
+}
+
+const query = { cube: 'c', measures: ['cnt'], dimensions: ['region'] } as any;
+
+describe('NativeSQLStrategy external-object gate (ADR-0062 D6)', () => {
+  const strategy = new NativeSQLStrategy();
+
+  it('DECLINES when the base object is external', () => {
+    const cube = { name: 'c', sql: 'ext_customer', dimensions: {}, measures: {} };
+    const ctx = ctxFor(cube, (o) => o === 'ext_customer');
+    expect(strategy.canHandle(query, ctx)).toBe(false);
+  });
+
+  it('ACCEPTS a managed object (native-SQL still used)', () => {
+    const cube = { name: 'c', sql: 'account', dimensions: {}, measures: {} };
+    const ctx = ctxFor(cube, () => false);
+    expect(strategy.canHandle(query, ctx)).toBe(true);
+  });
+
+  it('DECLINES when a JOINED object is external (the join would hit the wrong table)', () => {
+    const cube = { name: 'c', sql: 'orders', joins: { customer: { name: 'ext_customer' } }, dimensions: {}, measures: {} };
+    const ctx = ctxFor(cube, (o) => o === 'ext_customer');
+    expect(strategy.canHandle(query, ctx)).toBe(false);
+  });
+
+  it('is purely additive — with no isExternalObject hook it behaves as before (accept)', () => {
+    const cube = { name: 'c', sql: 'ext_customer', dimensions: {}, measures: {} };
+    const ctx = ctxFor(cube); // no hook
+    expect(strategy.canHandle(query, ctx)).toBe(true);
+  });
+});

packages/services/service-analytics/src/analytics-service.ts

@@ -135,6 +135,14 @@ export interface AnalyticsServiceConfig {
    * `StrategyContext.coerceTemporalFilterValue` for the full rationale.
    */
   coerceTemporalFilterValue?: (objectName: string, fieldName: string, value: unknown) => unknown;
+  /**
+   * ADR-0062 D6 — report whether an object is federated (external datasource).
+   * Threaded into the StrategyContext so `NativeSQLStrategy` declines external
+   * objects (which it would otherwise query against the wrong physical table),
+   * routing them to the driver-correct ObjectQL aggregate path instead. See
+   * `StrategyContext.isExternalObject`.
+   */
+  isExternalObject?: (objectName: string) => boolean;
   /**
    * ADR-0021 — optional object-graph resolver used when compiling datasets:
    * `(baseObject, relationshipName) => relatedObjectName | undefined`. When
@@ -260,6 +268,7 @@ export class AnalyticsService implements IAnalyticsService {
         this.datasetRegistry.get(cubeName)?.allowedRelationships
         ?? config.getAllowedRelationships?.(cubeName),
       coerceTemporalFilterValue: config.coerceTemporalFilterValue,
+      isExternalObject: config.isExternalObject,
     };
 
     // Build strategy chain (built-in + custom, sorted by priority)

packages/services/service-analytics/src/plugin.ts

@@ -32,6 +32,10 @@ interface DataEngineLike {
       reference?: string;
       options?: Array<{ value: unknown; label?: string }>;
     }>;
+    /** Federation marker (ADR-0015): set on objects bound to an external datasource. */
+    external?: unknown;
+    /** The datasource this object is bound to (ADR-0062 D6 external detection). */
+    datasource?: string;
   } | undefined;
   /**
    * Resolve the storage driver backing an object (public ObjectQL accessor).
@@ -443,6 +447,13 @@ export class AnalyticsServicePlugin implements Plugin {
           | undefined;
         return f ? { type: f.type, defaultCurrency: f.currencyConfig?.defaultCurrency } : undefined;
       },
+      // ADR-0062 D6 — a federated object carries an `external` block (ADR-0015).
+      // Reported so NativeSQLStrategy declines it (its hand-compiled FROM would
+      // hit the wrong physical table) and the driver-correct ObjectQL path runs.
+      isExternalObject: (objectName: string) => {
+        const obj = dataEngine()?.getObject?.(objectName);
+        return !!(obj && obj.external != null);
+      },
       draftRowsResolver,
     };
 

packages/services/service-analytics/src/strategies/native-sql-strategy.ts

@@ -28,6 +28,26 @@ export class NativeSQLStrategy implements AnalyticsStrategy {
     // query silently grouped by the raw timestamp — one bucket per row — and a
     // non-UTC reference timezone was ignored entirely (ADR-0053 Phase 2, #1982).
     if (query.timeDimensions?.some((td) => !!td.granularity)) return false;
+    // ADR-0062 D6 — DECLINE federated (external-datasource) objects. This
+    // strategy hand-compiles `FROM "<object>"` and bare column references, which
+    // bypass the driver's physical-table resolution (`external.remoteName` /
+    // `remoteSchema` / `columnMap`) and would query the WRONG table. Routing the
+    // query to the lower-priority ObjectQL aggregate path keeps it correct —
+    // that path goes through the driver's `getBuilder` (#2138/#2149). Applies to
+    // the base object AND any joined object (a join would also hit the wrong
+    // table). Until native-SQL learns the driver's resolution, "disabled" beats
+    // "silently wrong".
+    if (typeof ctx.isExternalObject === 'function') {
+      const cube = ctx.getCube(query.cube);
+      if (cube) {
+        if (ctx.isExternalObject(this.extractObjectName(cube))) return false;
+        const joinTargets = cube.joins ? Object.values(cube.joins) : [];
+        for (const j of joinTargets) {
+          const joinedObject = (j as { name?: string })?.name;
+          if (joinedObject && ctx.isExternalObject(joinedObject)) return false;
+        }
+      }
+    }
     const caps = ctx.queryCapabilities(query.cube);
     return caps.nativeSql && typeof ctx.executeRawSql === 'function';
   }

packages/spec/src/contracts/analytics-service.ts

@@ -322,6 +322,26 @@ export interface StrategyContext {
      * @param value      The stringified comparand from the normalized filter.
      */
     coerceTemporalFilterValue?(objectName: string, fieldName: string, value: unknown): unknown;
+
+    /**
+     * ADR-0062 D6 — is `objectName` a federated (external-datasource) object?
+     *
+     * The `NativeSQLStrategy` compiles its own `FROM "<object>"` and column
+     * references, which bypass the driver's physical-table resolution and so
+     * would query the WRONG table for a federated object whose `external.remoteName`
+     * / `remoteSchema` / `columnMap` differ from the logical object/field names.
+     * Until native-SQL learns the driver's physical resolution, the strategy
+     * DECLINES external objects (see its `canHandle`), so they fall through to the
+     * ObjectQL aggregate path — which routes through the driver's `getBuilder`
+     * (honouring `remoteName`/`remoteSchema`, #2138/#2149). This keeps external
+     * analytics correct ("reuse the driver's resolution") rather than silently
+     * querying the wrong table.
+     *
+     * Returns `true` for a federated object, `false`/`undefined` otherwise. When
+     * the hook is absent (legacy wiring) the strategy assumes non-external —
+     * purely additive, no behavior change for managed objects.
+     */
+    isExternalObject?(objectName: string): boolean;
 }
 
 /**