How to Automate OneLake Shortcuts for Eventhouse (Step-by-Step)

In Microsoft Fabric, OneLake shortcuts allow you to easily share data across workspaces and teams, eliminating the need for expensive and complex ETL processes. Enriching your real-time data in an Eventhouse with Lakehouse data is a powerful capability. While the Fabric UI makes shortcut creation simple, automating OneLake shortcuts for Eventhouse requires a different approach when building data pipelines at scale.

In this post, I’ll explain what shortcuts are and how to automate their creation for Eventhouse and KQL databases.

What are OneLake shortcuts?

OneLake shortcuts are objects in OneLake that point to other storage locations. These locations can be internal (another Lakehouse or Warehouse) or external (Azure Storage Account, Dataverse, AWS S3, or Google Cloud Storage). To learn more about OneLake fundamentals, check the Microsoft Fabric documentation on OneLake.

The magic of shortcuts is data virtualization. It is similar to symbolic links (ln -s) in Linux. Instead of copying data from a Lakehouse to an Eventhouse to perform real-time analytics, you create a shortcut. The data remains in its original location, but it appears as if it is stored locally in the target item. Just like a symlink, a shortcut is a pointer that creates the illusion of local storage without moving the actual data.

The main benefits are:

  • No data duplication: Save on storage costs and avoid data silos.
  • Zero ETL: Skip the complex pipelines needed to move and transform data between environments.
  • Real-time access: Changes in the source are immediately visible in the target.

The challenge: From UI to automation

In the Fabric portal, creating a shortcut is a walk in the park. A few clicks in the UI, and your Lakehouse tables are visible in your Eventhouse. All the heavy lifting happens behind the scenes. It’s a great experience for ad-hoc exploration. However, for automated data pipelines we want to avoid manual steps.

When you need to move your solution from Development into higher environments such as Production, you cannot rely on someone clicking through the UI. You need a repeatable, automated process. While Microsoft provides REST APIs for shortcuts, the documentation does not explicitly explain that more is required beyond creating the OneLake shortcut itself.

As it turns out, getting shortcuts to actually work in an Eventhouse requires more than a single Fabric API call.

Why the shortcuts API alone is not enough

The Fabric shortcuts API lets an Eventhouse reference Lakehouse tables. When you create this shortcut, the Delta tables (and their underlying Parquet files) become available in the Eventhouse.

However, a KQL database doesn’t automatically see these files as a table. Without a KQL external table, the data remains invisible to your queries.

So the complete automated flow must be:

  1. Create the shortcut: Makes the Delta table data available in the Eventhouse.
  2. Create a KQL external table: Points the KQL engine at those files.

Step 1: Create the OneLake shortcut

Using the Fabric REST API, you associate a shortcut with a KQL database item. This points at a specific Lakehouse table path. For this request, your access token should use https://api.fabric.microsoft.com as the audience.

HTTP Request:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{kqlDatabaseId}/shortcuts
Authorization: Bearer <token>
Content-Type: application/json

Request body:

{
  "path": "/Tables",
  "name": "{shortcutName}",
  "target": {
    "oneLake": {
      "workspaceId": "{workspaceId}",
      "itemId": "{lakehouseId}",
      "path": "Tables/{lakehouseTablPath}"
    }
  },
  "type": "OneLake"
}

At this point, the data is available in OneLake, but you still cannot see the table using the command .show external table routes or query the data.

Step 2: Create the external table

To make the data queryable, you must run a KQL management command against the KQL database. This tells the KQL engine to create an external table that references the shortcut files. For more on KQL databases, see the Eventhouse documentation.

The command you will execute is .create-or-alter external table. Here is the structure:

.create-or-alter external table {tableName}
kind=delta
(
h@'https://onelake.{workspaceRegion}.pbidedicated.windows.net/{workspaceId}/{kqlDatabaseId}/Tables/{shortcutName};impersonate'
)

Breaking down the command:

  • kind=delta: Specifies the file format that the external table will read. Since the shortcut points to Delta tables from the Lakehouse, you must use kind=delta. This tells KQL how to interpret the underlying Parquet files stored in that format.
  • workspaceRegion: Your Fabric capacity region (e.g., westeurope). This variable is part of the URL and must match your Fabric capacity region.
  • impersonate: This parameter at the end of the URL is mandatory. It enables the KQL engine to authenticate and access the shortcut files. Without it, the request will fail with an authentication error.
  • pbidedicated.windows.net: This domain is not documented in the official Microsoft API documentation. By reverse-engineering shortcuts created through the Fabric UI, I discovered that this is the endpoint Fabric uses internally. Use this URL pattern when creating shortcuts programmatically via REST APIs.

Making the REST request to the management endpoint

To execute the KQL command programmatically, you must send a request to the KQL Query Service management endpoint. The queryServiceUri is obtained from the Eventhouse properties, and the format of the URL is something like https://{prefix}.z9.kusto.fabric.microsoft.com.

Unlike Step 1, the access token for this request must use your specific queryServiceUri (e.g., https://trd-jkwaq252058z9521zy.z9.kusto.fabric.microsoft.com) as the audience.

HTTP Request:

POST {queryServiceUri}/v1/rest/mgmt
Authorization: Bearer <token>
Content-Type: application/json

Request payload:

The payload contains two fields:

  • db: The name of the KQL database.
  • csl: The KQL command (the .create-or-alter external table statement).
{
  "db": "{databaseName}",
  "csl": ".create-or-alter external table {tableName} kind=delta (h@'{url};impersonate')"
}

Summary

OneLake shortcuts are a powerful way to share data between Lakehouses and Eventhouses in Microsoft Fabric. To automate them, you need a two-step process that goes beyond what the basic REST API provides. By pointing your Eventhouse directly to existing Lakehouse tables, you eliminate data duplication and keep your architecture lean.

While the UI makes this look like a single step, building a robust automated data pipeline requires:

  1. Create the shortcut: Use the Fabric REST API to create the pointer in OneLake.
  2. Create the external table: Use the KQL Management API to create an external table so the KQL engine can query the Delta files.

By combining these two calls, you can fully automate your real-time analytics environment and ensure your shortcuts work reliably across all Fabric environments.

As we’ve seen, Microsoft is continuously improving the Fabric API, and we may eventually see a new endpoint that handles both steps in a single request. Until then, remember that creating the external table is a necessary step to get your shortcuts functioning in an Eventhouse.