Semantic Link (SemPy)

Warnings

• breaking Semantic Link (SemPy) is exclusively supported within Microsoft Fabric notebooks and Spark environments. It will not run in standalone Python environments outside of Fabric. Attempting to use it locally will result in errors related to missing Fabric-specific components.
  Fix: Ensure all development and execution involving Semantic Link occurs within a Microsoft Fabric workspace. For local testing or development, consider mocking Fabric interactions or adapting code to use alternative libraries.
• gotcha The `semantic-link` package is a meta-package. For core functionality, `semantic-link-sempy` is sufficient. If you encounter dependency conflicts or only need specific features, consider installing `semantic-link-sempy` and other `semantic-link-functions-*` packages individually instead of the meta-package.
  Fix: If `pip install semantic-link` causes issues, try `pip install semantic-link-sempy` and then install specific function packages (e.g., `semantic-link-functions-holidays`) as needed.
• gotcha Semantic Link is pre-installed in Microsoft Fabric Runtimes 1.2 (Spark 3.4) and above. Explicitly installing it with `%pip install -U semantic-link` is only necessary for older runtimes (Spark 3.3 or below) or to ensure you have the very latest version.
  Fix: Check your Fabric Spark runtime version. If it's 3.4 or higher, the library is likely already available. Only run `%pip install -U semantic-link` if you need to upgrade or if you're on an older runtime.
• gotcha Using Semantic Link requires a Microsoft Fabric subscription with appropriate capacity (e.g., F64 for LLM samples) and Power BI datasets residing in a Premium or Fabric workspace within the same tenant. Certain advanced features may also require XMLA Read/Write enabled for your capacity.
  Fix: Verify that your Microsoft Fabric environment and Power BI workspace configurations meet the necessary prerequisites outlined in the official documentation.
• gotcha The `semantic-link-labs` library is an official extension offering early access to experimental features. While powerful, features in `Labs` may be less stable and subject to change or removal compared to the core `semantic-link` library.
  Fix: Be mindful of the experimental nature of `semantic-link-labs` features. For production-critical workflows, prioritize features available directly in the core `semantic-link` package.
• gotcha The primary goal of Semantic Link is to leverage the semantic information (measures, relationships, data categories) already defined in Power BI semantic models. A common anti-pattern is to extract raw data and re-implement business logic in Python/Spark, negating a key benefit of the library.
  Fix: Focus on utilizing `sempy` functions to compute Power BI measures, query with DAX, and propagate semantic metadata to ensure consistency and avoid duplicated effort.

Install

• %pip install -U semantic-link In Microsoft Fabric notebooks
• pip install semantic-link Standard Python environments (for development/local checks)

Imports

• fabric

  import sempy.fabric as fabric

  Common alias for functions interacting with Fabric items like semantic models and workspaces.
• functions

  import sempy.functions as sf

  Common alias for semantic functions provided by SemPy.

Quickstart

This quickstart demonstrates how to list available semantic models (datasets) in your Microsoft Fabric workspace and then read a specific table from one of those models using the `sempy.fabric` module. This code should be executed within a Microsoft Fabric notebook.

import sempy.fabric as fabric

# List all semantic models (datasets) in the current workspace
df_datasets = fabric.list_datasets()
print("Available datasets:")
print(df_datasets.head())

# Assuming a dataset named 'Sales & Returns Sample' exists
# Read a specific table from a semantic model
df_customers = fabric.read_table(dataset="Sales & Returns Sample", table="Customer")
print("\nFirst 5 rows of the 'Customer' table:")
print(df_customers.head())