Fabric OneLake shortcuts vs ADLS Gen2 mounts: what actually works in production

Neeraj Agarwal — Sat, 18 Apr 2026 15:15:55 +0000

If you've just moved a team onto Microsoft Fabric, the "how do I read our existing ADLS Gen2 data?" question comes up in the first week. Two patterns are on the table:

OneLake shortcuts - Fabric's newer, metadata-only references that make external data appear as a Lakehouse table
ADLS Gen2 mounts - the mssparkutils/notebookutils pattern that's been around since Synapse

The docs describe them as roughly interchangeable options. They aren't. We've now shipped both across ~15 Fabric projects and the failure modes are completely different.

Here's the field report.

Quick refresher - the two patterns

Shortcut (the new way)

Create via UI, REST API, or Fabric CLI. Zero-copy reference to an external location, exposed as a table or folder inside a Lakehouse:

curl -X POST \
  "https://api.fabric.microsoft.com/v1/workspaces/{wsid}/items/{lakehouseid}/shortcuts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "Tables",
    "name": "orders_raw",
    "target": {
      "adlsGen2": {
        "location": "https://prodstorage.dfs.core.windows.net",
        "subpath": "/raw/orders",
        "connectionId": "1234abcd-..."
      }
    }
  }'

Once created, Spark and SQL treat it as a normal Lakehouse table:

df = spark.read.table("Lakehouse.orders_raw")

Mount (the familiar way)

In a Fabric notebook, create a logical mount path backed by an ADLS Gen2 container using a LinkedService:

notebookutils.fs.mount(
    "abfss://raw@prodstorage.dfs.core.windows.net/orders",
    "/orders_raw",
    {"linkedService": "prod_adls_linked"}
)

df = spark.read.parquet("/synfs/nb_resource/orders_raw")

Both read the same bytes. The differences start everywhere else.

Where shortcuts are magic

1. Direct Lake mode only works with shortcuts

This is the big one. If you want your Power BI semantic models to query Lakehouse data with zero import latency via Direct Lake, the table must live in the Lakehouse - which means shortcut or physical copy. Mounts don't count.

Direct Lake reads  →  Lakehouse table  →  shortcut OR Delta files in /Tables
Direct Lake reads  ✗  Mount path

If Direct Lake is in your architecture diagram (and on Fabric it usually should be), this alone settles the argument.

2. ACLs inherit from the source

Shortcuts honor the ACL model of the underlying storage. A user who can read /raw/orders in ADLS via POSIX ACL or RBAC can read it through the shortcut - Fabric doesn't re-auth.

Mounts run under the LinkedService's identity, which is usually a service principal with broad access. You've just given every notebook in that workspace the same blast radius.

3. Zero operational overhead at mount time

Shortcut creation is metadata only. A 40TB dataset becomes queryable in under a second. Mounts require the runtime to resolve the path at session start - fine for small containers, annoying when you're re-starting sessions dozens of times a day across a team.

4. SQL endpoint sees them

A Lakehouse's SQL analytics endpoint exposes shortcut tables for free. Warehouses can cross-query them with three-part names. Mounts are invisible to the SQL endpoint - you can only read them from a notebook.

-- Works on a shortcut, fails on a mount
SELECT COUNT(*)
FROM [MyLakehouse].[dbo].[orders_raw]
WHERE order_ts >= '2026-01-01';

Where shortcuts silently break

1. Cross-region reads are expensive and slow

Shortcuts don't copy data. If your ADLS account is in westus2 and your Fabric capacity is in eastus, every query pulls bytes across the region boundary - at egress pricing, at cross-region latency.

We had one client where a dashboard that ran in 4 seconds against a co-located Lakehouse took 38 seconds through a shortcut to a foreign-region ADLS. Nobody's documentation flagged this.

Rule: shortcut target and Fabric capacity home region should match. If they can't, plan for a daily materialized copy or move the capacity.

2. Connection credentials expire in ways you won't see

When you create a shortcut via UI, Fabric prompts for credentials once and stores them as a Connection object. If that connection uses a SAS token, it expires. When it does, the shortcut starts returning:

Error: [FabricOneLakeShortcutAuthFailure] Connection refused

Not at creation time. Not logged anywhere obvious. Users just see empty tables.

Rule: use workspace identity or a managed-identity-backed connection, not SAS. If you must use SAS, alert on expiry explicitly.

3. ADLS Gen1 is not supported

We know, you thought it was fully deprecated. We had a client with a Gen1 account still humming along for a batch job. Fabric won't shortcut it - no workaround. You're migrating to Gen2 first.

4. Shortcuts to Hive-partitioned data don't auto-discover partitions

If your external ADLS Gen2 layout is /sales/year=2025/month=04/, a shortcut exposes it as a folder shortcut - not a partitioned table. You either:

Shortcut the root and read in Spark (spark.read.option("basePath", …)) - loses the Lakehouse table abstraction
Convert to Delta first on the ADLS side, then shortcut (the "right" answer, but it's work)

Mounts have the same issue, but at least there's no expectation of table-like behavior.

Performance we measured

We ran the same Spark query - a 200M-row aggregation over Parquet sitting in ADLS Gen2 - through both access patterns, from a Fabric F64 capacity. Five cold runs, five warm runs, averaged:

Access path	Cold (first run)	Warm (cached)	Notes
Delta files directly in Lakehouse `/Tables/`	11.2 s	2.1 s	Baseline. No shortcut, no mount.
Shortcut to same-region ADLS (Delta)	12.8 s	2.4 s	~15% overhead cold, negligible warm
Mount to same-region ADLS (Parquet)	14.1 s	3.0 s	Lacks Delta stats; CBO worse
Shortcut to cross-region ADLS (Delta)	38.4 s	6.7 s	Egress + latency dominates

Two takeaways:

Same-region shortcuts are essentially free
Cross-region shortcuts are a trap dressed up as convenience

When to use which - decision matrix

Requirement	Shortcut	Mount
Direct Lake mode from Power BI	✅ required	❌ not supported
SQL analytics endpoint access	✅	❌
User-level ACL enforcement	✅ honored from source	❌ runs as SPN
External Iceberg tables (preview)	✅	❌
Read ad-hoc files (CSV dumps, logs)	⚠️ overkill	✅ just mount and read
Cross-region source storage	❌ egress pain	❌ egress pain - at least you know it
ADLS Gen1	❌	❌
Write back to external storage from Fabric	❌ shortcuts are read-focused	✅ mount supports write
Quick ETL staging in a notebook	⚠️	✅ simpler

The pattern we land on

On every new Fabric engagement now we default to this:

All production table access → shortcuts. No exceptions. Direct Lake, SQL endpoint access, and source-ACL inheritance are non-negotiable in an enterprise deployment.
Shortcuts target same-region ADLS. If source is elsewhere, we budget a one-way replication with a scheduled pipeline into same-region staging, then shortcut that.
Connections use workspace identity or MI-backed Connection objects. SAS is banned unless there's a specific third-party constraint, and if it is, we alert on token expiry.
Mounts only for notebook-level ETL utility work - reading a one-off CSV, writing a temp file back to a scratch container. Never for anything a dashboard depends on.
ADLS Gen1 migrates to Gen2 before Fabric migration. Non-negotiable.

The TL;DR for teams coming from Synapse: you're going to reach for mounts because they're familiar. Resist. Shortcuts are the primitive Fabric is built around - learn them well, and most of Fabric's headline features (Direct Lake, SQL endpoint cross-query, cross-item data reuse) fall into your lap for free.

If you're mid-migration and want a second set of eyes on shortcut architecture, the team at Algoscale runs these assessments regularly. The full write-up of the migration playbook including the connection-identity pattern lives on our blog.

DEV Community: Neeraj Agarwal