@microsoft/fabric-app-data-proxy

IFabricApiProxy implementation for apps embedded in Microsoft Fabric

Quick Reference

Package: @microsoft/fabric-app-data-proxy Purpose: IFabricApiProxy implementation for Fabric embedded iframe scenarios — bridges the SDK with the Fabric host via postMessage. Use when: Your app runs inside a Fabric iframe and you need to pass a proxy to FabricClient. Do NOT use when: You are running in Node.js (use @microsoft/fabric-app-data-cli-proxy instead — it makes direct HTTP calls). Key exports: EmbedFabricApiProxy Peer dependencies: @microsoft/fabric-app-data, @microsoft/fabric-app-data-embed-client Install: npm install @microsoft/fabric-app-data-proxy

Ecosystem Context

@microsoft/fabric-app-data-proxy is the glue between @microsoft/fabric-app-data and Fabric's embedded iframe environment.

• @microsoft/fabric-app-data defines the IFabricApiProxy contract consumed by FabricClient
• @microsoft/fabric-app-data-proxy provides the embedded implementation of that contract
• @microsoft/fabric-app-data-embed-client is used internally as the window.postMessage transport to the Fabric host
• The Fabric host owns authentication and outbound network calls
• For local development and Node.js-based testing, use @microsoft/fabric-app-data-cli-proxy instead

Installation

npm install @microsoft/fabric-app-data-proxy

Public API

This package exports one public symbol.

EmbedFabricApiProxy

import type {
  DaxJsonProxyResponse,
  DaxProxyResponse,
  DaxQueryOptions,
  IFabricApiProxy,
  ILakehouseApiProxy,
  ISemanticModelApiProxy,
  IWarehouseApiProxy,
  SqlParameters,
  SqlProxyResponse,
  SqlQueryOptions,
  WorkspaceId,
} from "@microsoft/fabric-app-data";
import { SemanticModelMessageClient } from "@microsoft/fabric-app-data-embed-client";

export class EmbedFabricApiProxy implements IFabricApiProxy {
  readonly semanticModel: ISemanticModelApiProxy;
  readonly lakehouse: ILakehouseApiProxy;
  readonly warehouse: IWarehouseApiProxy;

  constructor(
    client?: SemanticModelMessageClient,
    options?: { sessionId?: string },
  );
}

Runtime behavior behind the interface

EmbedFabricApiProxy exposes the three IFabricApiProxy sub-proxies below through its public properties.

| Property | Type | Behavior | | --- | --- | --- | | semanticModel | ISemanticModelApiProxy | Delegates DAX queries to SemanticModelMessageClient over postMessage | | lakehouse | ILakehouseApiProxy | Stub implementation; executeSql(...) throws Error("Not implemented — SQL support coming in a future release") | | warehouse | IWarehouseApiProxy | Stub implementation; executeSql(...) throws Error("Not implemented — SQL support coming in a future release") |

The semantic-model proxy currently behaves as:

interface ISemanticModelApiProxy {
  executeDax(
    workspaceId: WorkspaceId,
    itemId: string,
    query: string,
    options?: DaxQueryOptions,
  ): Promise<DaxProxyResponse>;

  executeDaxJson(
    workspaceId: WorkspaceId,
    itemId: string,
    query: string,
  ): Promise<DaxJsonProxyResponse>;
}

interface ILakehouseApiProxy {
  executeSql(
    workspaceId: WorkspaceId,
    itemId: string,
    sql: string,
    params?: SqlParameters,
    options?: SqlQueryOptions,
  ): Promise<SqlProxyResponse>;
}

interface IWarehouseApiProxy {
  executeSql(
    workspaceId: WorkspaceId,
    itemId: string,
    sql: string,
    params?: SqlParameters,
    options?: SqlQueryOptions,
  ): Promise<SqlProxyResponse>;
}

Referenced request/response types used by this package:

type WorkspaceId = "me" | (string & {});

interface DaxQueryOptions {
  culture?: string;
  schemaOnly?: boolean;
  queryTimeout?: number;
  resultSetRowCountLimit?: number;
}

interface DaxProxyResponse {
  data: ArrayBuffer;
  requestId: string;
}

interface DaxJsonProxyResponse {
  data: unknown;
  requestId: string;
}

interface SqlProxyResponse {
  columns: Array<{ name: string; dataType: string }>;
  rows: unknown[][];
  requestId: string;
}

Key Constraints & Gotchas

This is the embedded proxy, NOT the Node.js proxy

// ✅ DO: Use EmbedFabricApiProxy inside a Fabric iframe
import { EmbedFabricApiProxy } from "@microsoft/fabric-app-data-proxy";
const proxy = new EmbedFabricApiProxy();

// ❌ DON'T: Use this in Node.js — use @microsoft/fabric-app-data-cli-proxy instead

Only semantic model DAX is implemented

• semanticModel.executeDax(...) and semanticModel.executeDaxJson(...) work.
• lakehouse.executeSql(...) and warehouse.executeSql(...) throw Error("Not implemented").

Errors are mapped to FabricProxyError types

• FabricError from the embed client is translated to FabricApiProxyError, FabricNetworkProxyError, or FabricGenericProxyError from @microsoft/fabric-app-data.
• Session IDs are auto-generated via crypto.randomUUID() if not provided.

Minimal Usage Examples

Default embedded usage

import { FabricClient } from "@microsoft/fabric-app-data";
import { EmbedFabricApiProxy } from "@microsoft/fabric-app-data-proxy";

const proxy = new EmbedFabricApiProxy();

const fabric = new FabricClient({
  proxy,
  semanticModels: {
    salesModel: {
      workspaceId: "00000000-0000-0000-0000-000000000000",
      itemId: "11111111-1111-1111-1111-111111111111",
    },
  },
});

Inject a prebuilt message client and fixed session ID

import { FabricClient } from "@microsoft/fabric-app-data";
import { SemanticModelMessageClient } from "@microsoft/fabric-app-data-embed-client";
import { EmbedFabricApiProxy } from "@microsoft/fabric-app-data-proxy";

const messageClient = new SemanticModelMessageClient();
const proxy = new EmbedFabricApiProxy(messageClient, { sessionId: "embed-session-1" });

const fabric = new FabricClient({
  proxy,
});

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Security

Microsoft takes the security of our software products and services seriously, which includes all source code repositories in our GitHub organizations.

Please do not report security vulnerabilities through public GitHub issues.

For security reporting information, locations, contact information, and policies, please review the latest guidance for Microsoft repositories at https://aka.ms/SECURITY.md.

Code of conduct

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

See full Microsoft Open Source Code of Conduct