次の方法で共有

semantic_model Package

Functions

cancel_refresh

Cancel the specific refresh of a semantic model.

Note

This is a wrapper function for

Datasets - Cancel Refresh In Group.

cancel_refresh(dataset: str | UUID, request_id: str | None = None, workspace: str | UUID | None = None)

Parameters

Name Description
dataset
Required
str or UUID

Name or ID of the semantic model.
request_id
str

The request id of a semantic model refresh. Defaults to finding the latest active refresh of the semantic model.

Default value: None
workspace
str or UUID

The Fabric workspace name or UUID object containing the workspace ID. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

Default value: None

deploy_semantic_model

Deploy a semantic model based on an existing semantic model's definition.

This function copies the definition (Model.bim / TMSL) of a source semantic model and creates or updates a target semantic model in the specified workspace. Optionally, it can trigger a full refresh of the target model after deployment.

Note

This function wraps the following Fabric REST APIs:

Items - Get Semantic Model Definition

Items - Create Item

Items - Update Item Definition

deploy_semantic_model(source_dataset: str | UUID, source_workspace: str | UUID | None = None, target_dataset: str | None = None, target_workspace: str | UUID | None = None, refresh_target_dataset: bool = True, overwrite: bool = False, credential: TokenCredential | None = None) -> None

Parameters

Name Description
source_dataset
Required
str or UUID

Name or ID of the source semantic model to deploy.
source_workspace
str or UUID

The Fabric workspace name or UUID object containing the source semantic model. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

Default value: None
target_dataset
str

Name of the target semantic model. If None, uses the same name as the source.

Default value: None
target_workspace
str or UUID

The Fabric workspace name or UUID object where the target model will be deployed. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

Default value: None
refresh_target_dataset
bool

If True, initiates a full refresh of the target semantic model after deployment.

Default value: True
overwrite
bool

If True, overwrites an existing semantic model with the same name in the target workspace. If False and a model with the same name exists, raises a ValueError.

Default value: False
credential
<xref:sempy.fabric.semantic_model.TokenCredential>

The credential for token acquisition. Must be an instance of azure.core.credentials.TokenCredential. If None, the default credential will be used.

Default value: None

Exceptions

Type Description
ValueError

If the source and target are the same, or the target exists and overwrite is False.
FabricHTTPException

If any API request fails.

get_refresh_execution_details

Poll the status for a specific refresh requests using Enhanced refresh with the Power BI REST API.

Note

This is a wrapper function for

Datasets - Get Refresh Execution Details In Group.

More details on the underlying implementation in PBI Documentation.

get_refresh_execution_details(dataset: str | UUID, refresh_request_id: str | UUID, workspace: str | UUID | None = None, credential: TokenCredential | None = None) -> RefreshExecutionDetails

Parameters

Name Description
dataset
Required
str or UUID

Name or UUID of the dataset.
refresh_request_id
Required
str or UUID

Id of refresh request on which to check the status.
workspace
str or UUID

The Fabric workspace name or UUID object containing the workspace ID. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

Default value: None
credential
<xref:sempy.fabric.semantic_model.TokenCredential>

The credential for token acquisition. Must be an instance of azure.core.credentials.TokenCredential. If None, the default credential will be used.

Default value: None

Returns

Type Description
RefreshExecutionDetails

RefreshExecutionDetails instance with statuses of refresh request retrieved based on the passed URL.

list_datasets

List datasets in a Fabric workspace.

⚠️ By default (mode="xmla"), this function leverages the Tabular Object Model (TOM) to interact with the target semantic model. To use this function in xmla mode, you must have at least ReadWrite permissions on the model. Alternatively, you can use mode="rest".

list_datasets(workspace: str | UUID | None = None, mode: str = 'xmla', additional_xmla_properties: str | List[str] | None = None, endpoint: Literal['powerbi', 'fabric'] = 'powerbi', credential: TokenCredential | None = None) -> DataFrame

Parameters

Name Description
workspace
str or UUID

The Fabric workspace name or UUID object containing the workspace ID. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

Default value: None
mode
str

Whether to use the XMLA "xmla" or REST API "rest". See REST docs for returned fields.

Default value: xmla
additional_xmla_properties
str or List[str]

Additional XMLA model properties to include in the returned dataframe.

Default value: None
endpoint
<xref:Literal>[<xref:”powerbi”, "fabric"]

The endpoint to use when mode="rest". Supported values are "powerbi" and "fabric". When mode="xmla", this parameter is ignored. See PowerBI List Datasets for using "powerbi" and Fabric List Datasets for using "fabric".

Default value: powerbi
credential
<xref:sempy.fabric.semantic_model.TokenCredential>

The credential for token acquisition. Must be an instance of azure.core.credentials.TokenCredential. If None, the default credential will be used.

Default value: None

Returns

Type Description
DataFrame

Dataframe listing databases and their attributes.

list_refresh_requests

Poll the status or refresh requests for a given dataset using Enhanced refresh with the Power BI REST API.

Note

This is a wrapper function for

Datasets - Get Refresh History In Group.

See details in: PBI Documentation.

list_refresh_requests(dataset: str | UUID, workspace: str | UUID | None = None, top_n: int | None = None, credential: TokenCredential | None = None) -> DataFrame

Parameters

Name Description
dataset
Required
str or UUID

Name or UUID of the dataset.
workspace
str or UUID

The Fabric workspace name or UUID object containing the workspace ID. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

Default value: None
top_n
int

Limit the number of refresh operations returned.

Default value: None
credential
<xref:sempy.fabric.semantic_model.TokenCredential>

The credential for token acquisition. Must be an instance of azure.core.credentials.TokenCredential. If None, the default credential will be used.

Default value: None

Returns

Type Description
DataFrame

Dataframe with statuses of refresh request retrieved based on the passed parameters.

refresh_dataset

Refresh data associated with the given dataset.

Note

This is a wrapper function for

Datasets - Refresh Dataset In Group.

For detailed documentation on the implementation see

Enhanced refresh with the Power BI REST API.

refresh_dataset(dataset: str | UUID, workspace: str | UUID | None = None, refresh_type: str = 'automatic', max_parallelism: int = 10, commit_mode: str = 'transactional', retry_count: int = 0, objects: List | None = None, apply_refresh_policy: bool = True, effective_date: date = datetime.date(2026, 4, 2), verbose: int = 0, credential: TokenCredential | None = None) -> str

Parameters

Name Description
dataset
Required
str or UUID

Name or UUID of the dataset.
workspace
str or UUID

The Fabric workspace name or UUID object containing the workspace ID. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

Default value: None
refresh_type
str

The type of processing to perform. Types align with the TMSL refresh command types: full, clearValues, calculate, dataOnly, automatic, and defragment. The add type isn't supported. Defaults to "automatic".

Default value: automatic
max_parallelism
int

Determines the maximum number of threads that can run the processing commands in parallel. This value aligns with the MaxParallelism property that can be set in the TMSL Sequence command or by using other methods. Defaults to 10.

Default value: 10
commit_mode
str

Determines whether to commit objects in batches or only when complete. Modes are "transactional" and "partialBatch". Defaults to "transactional".

Default value: transactional
retry_count
int

Number of times the operation retries before failing. Defaults to 0.

Default value: 0
objects
List

A list of objects to process. Each object includes table when processing an entire table, or table and partition when processing a partition. If no objects are specified, the entire dataset refreshes. Pass output of json.dumps of a structure that specifies the objects that you want to refresh. For example, this is to refresh "DimCustomer1" partition of table "DimCustomer" and complete table "DimDate":


   [
       {
           "table": "DimCustomer",
           "partition": "DimCustomer1"
       },
       {
           "table": "DimDate"
       }
   ]
Default value: None
apply_refresh_policy
bool

If an incremental refresh policy is defined, determines whether to apply the policy. Modes are true or false. If the policy isn't applied, the full process leaves partition definitions unchanged, and fully refreshes all partitions in the table. If commitMode is transactional, applyRefreshPolicy can be true or false. If commitMode is partialBatch, applyRefreshPolicy of true isn't supported, and applyRefreshPolicy must be set to false.

Default value: True
effective_date
date

If an incremental refresh policy is applied, the effectiveDate parameter overrides the current date.

Default value: 2026-04-02
verbose
int

If set to non-zero, extensive log output is printed.

Default value: 0
credential
<xref:sempy.fabric.semantic_model.TokenCredential>

The credential for token acquisition. Must be an instance of azure.core.credentials.TokenCredential. If None, the default credential will be used.

Default value: None

Returns

Type Description
str

The refresh request id.

refresh_semantic_model

Refresh a semantic model synchronously with options to visualize the refresh progress and collect SSAS traces.

Note

This is a wrapper function for

Datasets - Refresh Dataset In Group.

For detailed documentation on the implementation see

Enhanced refresh with the Power BI REST API.

refresh_semantic_model(dataset: str | UUID, tables: str | List[str] | None = None, partitions: str | List[str] | None = None, workspace: str | UUID | None = None, refresh_type: str = 'automatic', max_parallelism: int = 10, commit_mode: str = 'transactional', retry_count: int = 0, apply_refresh_policy: bool = True, effective_date: date = datetime.date(2026, 4, 2), visualize: bool = False, lro_config: LroConfig | None = None, verbose: int = 0, credential: TokenCredential | None = None) -> DataFrame | None

Parameters

Name Description
dataset
Required
str or UUID

Name or ID of the semantic model.
tables
str or List[str]

A string or a list of tables to refresh. The entire table will be refreshed. Use partitions if you wish to refresh specific partitions within a table.

Default value: None
partitions
str or List[str]

A string or a list of partitions to refresh. Partitions must be formatted as such: 'Table Name'[Partition Name]. Use tables if you wish to refresh all partitions within those tables.

Default value: None
workspace
str or UUID

The Fabric workspace name or UUID object containing the workspace ID. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

Default value: None
refresh_type
str

The type of processing to perform. Types align with the TMSL refresh command types: full, clearValues, calculate, dataOnly, automatic, and defragment. The add type isn't supported. Defaults to "automatic".

Default value: automatic
max_parallelism
int

Determines the maximum number of threads that can run the processing commands in parallel. This value aligns with the MaxParallelism property that can be set in the TMSL Sequence command or by using other methods. Defaults to 10.

Default value: 10
commit_mode
str

Determines whether to commit objects in batches or only when complete. Modes are "transactional" and "partialBatch". Defaults to "transactional".

Default value: transactional
retry_count
int

Number of times the operation retries before failing. Defaults to 0.

Default value: 0
apply_refresh_policy
bool

If an incremental refresh policy is defined, determines whether to apply the policy. Modes are true or false. If the policy isn't applied, the full process leaves partition definitions unchanged, and fully refreshes all partitions in the table. If commitMode is transactional, applyRefreshPolicy can be true or false. If commitMode is partialBatch, applyRefreshPolicy of true isn't supported, and applyRefreshPolicy must be set to false.

Default value: True
effective_date
date

If an incremental refresh policy is applied, the effectiveDate parameter overrides the current date.

Default value: 2026-04-02
visualize
bool

If True, displays a Gantt chart showing the refresh statistics for each table/partition.

Default value: False
lro_config
<xref:sempy.fabric.semantic_model.LroConfig>

Options to control LRO polling behavior. See LroConfig for available keys and defaults.

Default value: None
verbose
int

If set to non-zero, extensive log output is printed.

Default value: 0
credential
<xref:sempy.fabric.semantic_model.TokenCredential>

The credential for token acquisition. Must be an instance of azure.core.credentials.TokenCredential. If None, the default credential will be used.

Default value: None

Returns

Type Description
DataFrame,
None

If 'visualize' is set to True, returns a pandas dataframe showing the SSAS trace output used to generate the visualization.

resolve_dataset_id

Resolve the dataset ID by name in the specified workspace.

resolve_dataset_id(dataset_name: str, workspace: str | UUID | None = None, credential: TokenCredential | None = None) -> str

Parameters

Name Description
dataset_name
Required
str

Name of the dataset to be resolved.
workspace
str or UUID

The Fabric workspace name or UUID object containing the workspace ID. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

Default value: None
credential
<xref:sempy.fabric.semantic_model.TokenCredential>

The credential for token acquisition. Must be an instance of azure.core.credentials.TokenCredential. If None, the default credential will be used.

Default value: None

Returns

Type Description
str

The ID of the specified dataset.

resolve_dataset_name

Resolve the dataset name by ID in the specified workspace.

resolve_dataset_name(dataset_id: str | UUID, workspace: str | UUID | None = None, credential: TokenCredential | None = None) -> str

Parameters

Name Description
dataset_id
Required
str or UUID

Dataset ID or UUID object containing the dataset ID to be resolved.
workspace
str or UUID

The Fabric workspace name or UUID object containing the workspace ID. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

Default value: None
credential
<xref:sempy.fabric.semantic_model.TokenCredential>

The credential for token acquisition. Must be an instance of azure.core.credentials.TokenCredential. If None, the default credential will be used.

Default value: None

Returns

Type Description
str

The name of the specified dataset.

resolve_dataset_name_and_id

Resolve the name and ID of a dataset in the specified or default workspace.

resolve_dataset_name_and_id(dataset: str | UUID, workspace: str | UUID | None = None, credential: TokenCredential | None = None) -> Tuple[str, str]

Parameters

Name Description
dataset
Required
str or <xref:sempy.fabric.semantic_model.UUID>

The dataset name or ID.
workspace
str or <xref:sempy.fabric.semantic_model.UUID>

The Fabric workspace name or ID. If None, the default workspace is used.

Default value: None
credential
<xref:sempy.fabric.semantic_model.TokenCredential>

The credential for token acquisition. Must be an instance of azure.core.credentials.TokenCredential. If None, the default credential will be used.

Default value: None

Returns

Type Description
Tuple[str, str]

A tuple containing the dataset name and dataset ID.

update_direct_lake_model_connection

Remap a Direct Lake semantic model's connection to a new lakehouse or warehouse.

This function updates the M expressions in the semantic model to point to a new data source. It supports both SQL Endpoint and Direct Lake over OneLake connections.

Note

This function uses the Tabular Object Model (TOM)

to update the semantic model. You must have ReadWrite permissions on the model.

update_direct_lake_model_connection(dataset: str | UUID, workspace: str | UUID | None = None, source: str | None = None, source_type: str = 'Lakehouse', source_workspace: str | UUID | None = None, use_sql_endpoint: bool = True, tables: str | List[str] | None = None, credential: TokenCredential | None = None) -> None

Parameters

Name Description
dataset
Required
str or UUID

Name or ID of the semantic model.
workspace
str or UUID

The Fabric workspace name or UUID object containing the semantic model. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

Default value: None
source
str

The name of the lakehouse or warehouse to connect to. Defaults to None which resolves to the lakehouse attached to the notebook.

Default value: None
source_type
str

The type of source. Valid options: "Lakehouse", "Warehouse".

Default value: Lakehouse
source_workspace
str or UUID

The Fabric workspace name or UUID of the data source. Defaults to None which resolves to the workspace of the semantic model.

Default value: None
use_sql_endpoint
bool

If True, uses the SQL Endpoint for the connection. If False, uses Direct Lake over OneLake.

Default value: True
tables
str or list of str

The table name(s) to update. If None and the model has a single expression, all tables are updated. If the model has multiple expressions, this parameter is required to specify which tables should be remapped.

Default value: None
credential
<xref:sempy.fabric.semantic_model.TokenCredential>

The credential for token acquisition. Must be an instance of azure.core.credentials.TokenCredential. If None, the default credential will be used.

Default value: None

Exceptions

Type Description
ValueError

If the semantic model is not in Direct Lake mode, if the source type is invalid, or if multiple expressions exist but tables is not specified.

update_direct_lake_model_lakehouse_connection

Remap a Direct Lake semantic model's connection to a new lakehouse.

This is a convenience wrapper around update_direct_lake_model_connection that sets the source type to "Lakehouse".

update_direct_lake_model_lakehouse_connection(dataset: str | UUID, workspace: str | UUID | None = None, lakehouse: str | None = None, lakehouse_workspace: str | UUID | None = None, credential: TokenCredential | None = None) -> None

Parameters

Name Description
dataset
Required
str or UUID

Name or ID of the semantic model.
workspace
str or UUID

The Fabric workspace name or UUID object containing the semantic model. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

Default value: None
lakehouse
str

The name of the lakehouse to connect to. Defaults to None which resolves to the lakehouse attached to the notebook.

Default value: None
lakehouse_workspace
str or UUID

The Fabric workspace name or UUID of the lakehouse. Defaults to None which resolves to the workspace of the semantic model.

Default value: None
credential
<xref:sempy.fabric.semantic_model.TokenCredential>

The credential for token acquisition. Must be an instance of azure.core.credentials.TokenCredential. If None, the default credential will be used.

Default value: None