fabric-sdk

Fabric SDK Usage

Overview

@microsoft/fabric-app-data lets web applications query Fabric semantic models at runtime. The SDK provides a FabricClient that handles querying, result parsing, caching, and error handling. Transport and authentication are delegated to an IFabricApiProxy implementation, keeping the SDK environment-agnostic (browser, Node.js, Fabric extensions).

Quick Start

import { FabricClient } from "@microsoft/fabric-app-data";
 
const client = new FabricClient({
  proxy,                               // provided by host environment
  semanticModels: {
    sales: { workspaceId: "...", itemId: "..."

Key Concepts

FabricClient Configuration

The FabricClient is constructed with a config object. The proxy and connection details are typically provided by the host environment — your code just needs to pass them through:

• workspaceId can be a GUID or "me" for My Workspace items.

Managing Connections

The FabricClient accepts connection config as a plain object. How you manage those IDs (environment variables, config files, codegen) is up to your project. The only requirement is that workspaceId and itemId are provided for each named connection.

Querying

There is one method for DAX queries:

Result Handling

Always check result.status — queries never throw.

Each query must contain exactly one EVALUATE statement. On success, the result contains a single table with:

• columns: Array<{ name: string, dataType: string }> — column metadata
• rows: unknown[][] — row-major array, values match column order by index

Caching

Results are cached in memory by default (LRU, 64 entries).

What gets cached:

• ✅ Success results
• ✅ Query errors (bad DAX — won't fix itself)
• ❌ API errors (401, 500 — transient)
• ❌ Network errors (transient)

Error Categories

Data Types and DateTime Semantics

The SDK converts all DAX data types to standard JS values:

DateTime values are returned as ISO 8601 strings without a timezone suffix (no Z, no ±HH:MM). This matches the semantics of Analysis Services semantic models, where datetimes are timezone-unaware.

This format is directly usable as a temporal type in charting libraries and ensures consistent display across all browser timezones. The JSON and Arrow protocols both return the same format.

Integer overflow: If an integer value exceeds ±Number.MAX_SAFE_INTEGER (±9,007,199,254,740,991), the query returns an error with category: "overflow" rather than silently losing precision.

Common Patterns

Multiple Models

My Workspace Items

Disabling Cache

Anti-Patterns

• Don't catch errors from query() — it never throws. Check result.status.
• Don't hardcode endpoint URLs — the proxy handles transport.
• Don't construct SemanticModelClient directly — use client.semanticModel(alias).
• Don't import from internal paths — only import from "@microsoft/fabric-app-data".

Type Reference

All types are exported from the "@microsoft/fabric-app-data" package entry point.

Key types to import when needed:

For full type definitions, see references/types.md in this skill.