OneLake shortcuts: rules, limits, security

A OneLake shortcut is a pointer, shown as a folder, that makes data stored somewhere else appear inside a Fabric lakehouse or KQL database without copying it. The decision rule for exam questions: if the scenario says “without copying”, “no ingestion pipeline” or “keep the data where it is”, the answer is a shortcut; if it says the source is an operational database that must be replicated, the answer is mirroring; if it says shortcut queries are too slow in an Eventhouse, the answer is query acceleration on the shortcut.

What a shortcut is, in four facts

Microsoft’s shortcut overview describes shortcuts as behaving like symbolic links. Four facts carry most exam questions.

1. Two paths. The shortcut path is where the folder appears. The target path is where the data really is.
2. Two places to create one. Shortcuts are created in lakehouses and in KQL databases.
3. Independent object. Deleting the shortcut leaves the target unaffected. Moving, renaming or deleting the target can break the shortcut.
4. Any engine can read it. Spark, the SQL analytics endpoint, Real-Time Intelligence and Analysis Services (Direct Lake semantic models) all see the shortcut as ordinary lake data, as does anything that uses the OneLake API.

The sources are internal (lakehouses, warehouses, KQL databases, mirrored databases, SQL databases, semantic models and mirrored Azure Databricks catalogs) or external (ADLS Gen2, Azure Blob Storage, Amazon S3 and S3-compatible storage, Google Cloud Storage, Dataverse, Iceberg, OneDrive and SharePoint). On-premises or network-restricted locations are reachable through the Fabric on-premises data gateway.

Where in the lakehouse the shortcut may sit

A lakehouse has a Tables folder and a Files folder, and the rules differ.

Two small details are testable. A shortcut name containing a space is not recognised as a Delta table, because Delta does not support spaces in table names. Schema shortcuts can be created only in schema-enabled lakehouses.

Worked example: one lakehouse, three shortcuts

A retail team has a lakehouse called LH_Sales. Three requirements arrive.

• Partner price files in an S3 bucket. Spark must read them for a daily job. Create a shortcut under Files, for example Files/partner_prices. It can sit at any depth, and because it is an external source it uses a cloud connection.
• A customer dimension that the finance team maintains in a Fabric warehouse. The lakehouse needs it as a table. Create an internal shortcut under Tables, at the top level, named dim_customer. Spark can read it with spark.read.format("delta").load("Tables/dim_customer") and the SQL analytics endpoint exposes it as dbo.dim_customer.
• Clean up. Deleting Files/partner_prices leaves the bucket untouched. Deleting a file inside the shortcut, with write permission on the target, deletes it at the source.

Candidates miss that last point. Deleting the shortcut object is safe; deleting content through it is a real delete in the target. Shortcuts do not cascade deletes.

Identity: passthrough or delegated

The security article separates two models.

Passthrough sends the calling user’s identity to the target, so the user sees only what they could see at the source. Delegated uses a stored identity (another user, a service principal or an account key), so consumers need no direct access to the external system, and OneLake security roles on the shortcut control what they see. To switch an existing shortcut between the two, delete it and recreate it.

Permissions to create a shortcut: Write on the Fabric item where it is created, plus Read on the target. When a user accesses data through a shortcut, the more restrictive of the two locations applies. There is a documented exception: Power BI semantic models in Direct Lake over SQL, and T-SQL engines in delegated identity mode, use the item owner’s identity rather than the caller’s, and the fix Microsoft names is Direct Lake over OneLake or T-SQL in user identity mode. Related reading: row-level security and semantic model storage modes.

Caching, limits and failure causes

Shortcut caching reduces egress cost for cross-cloud reads. It is switched on per workspace under the OneLake tab of workspace settings, with a retention period of 1 to 28 days that resets each time a file is read. It currently covers Google Cloud Storage, S3, S3-compatible and gateway-based shortcuts, and files larger than 1 GB are not cached.

Limits worth recognising from the overview page: up to 100,000 shortcuts per item, up to 100 unique data source connections per item (internal shortcuts do not count), up to 10 shortcuts on a single OneLake path, and at most 5 direct shortcut-to-shortcut links. Names and paths cannot contain % or +.

Typical causes when a shortcut fails: the target was moved, renamed or deleted; the connection credentials changed; the shortcut sits in a Tables subfolder or has a space in its name, so it is not seen as a table; or the caller lacks permission at the target.

Shortcuts in a KQL database

In a KQL database a shortcut appears under Shortcuts and is treated like an external table, queried with external_table('MyShortcut'). Standard shortcut queries can be slower than on ingested data because of network calls and missing indexes. Query acceleration adds a policy on top of external Delta tables that caches and indexes data for a set number of days, so performance approaches ingested tables while the data stays in OneLake. Accelerated data uses Eventhouse SSD storage and is billed under the OneLake Premium cache meter. Accelerated tables behave like external tables, so materialized views and update policies are not supported, and tables are limited to 900 columns (see the overview). The choice between a native table and a shortcut is the choice between ingesting a copy and leaving the data in place; see batch vs streaming for the surrounding design.

Which exams test this

For where shortcuts fit among lakehouse tables, warehouses and Delta storage, read lakehouse vs warehouse and Delta Lake explained.

How exam questions use shortcuts

• “Without copying” versus “replicate”. Shortcut for files and tables that already exist in storage; mirroring for a supported operational database to be replicated into OneLake; a pipeline or Dataflow Gen2 when data must be transformed and loaded.
• Folder placement. A shortcut required to appear as a table must be at the top level of Tables and point to Delta data. Mixed or unstructured data goes under Files.
• Delete wording. “Delete the shortcut” is harmless to the source. “Delete files inside the shortcut” with write access is not.
• Cross-cloud cost. Repeated reads of S3 or GCS data point to shortcut caching.
• Identity wording. “Users have no access to the source system” means delegated; “each user must see only their own source permissions” means passthrough.
• Eventhouse speed. Slow KQL queries over lake data with a no-duplication constraint mean query acceleration, not re-ingestion.

Practice questions

Go deeper

• OneLake shortcuts (Microsoft Learn)
• Secure and manage OneLake shortcuts (Microsoft Learn)
• Query acceleration for OneLake shortcuts (Microsoft Learn)
• Related guides on this site: medallion architecture and the DP-700 cheat sheet