NotebookUtils 湖邊住宅設施

用notebookutils.lakehouse來在 Fabric 筆記本中以程式化方式管理湖屋項目。你可以直接從筆記本程式碼建立、取得、更新、刪除並列出湖屋。

湖屋工具可用 Python、PySpark、Scala 和 R 筆記本使用。本頁範例以 Python 為主要語言，並展示了 Scala 與 R 對應的 Key 方法。

備註

Lakehouse 的公用事業僅支援在 Fabric 中。它們在 Azure Synapse Analytics 中不可用。

若要顯示可用方法及其描述，請致電 notebookutils.lakehouse.help()。

方法概觀

下表總結了可用的方法：

方法	說明	退貨
`create`	建立一個新的湖屋，並可選地支援結構模式。	`Artifact` 具有 `id`、`displayName`、`description` 和 `workspaceId` 的屬性。
`get`	透過名字檢索一座湖邊小屋。	`Artifact` 帶有基本元資料的物件。
`getWithProperties`	取得一座擁有擴展土地的湖畔別墅。	`Artifact` 具有擴展元資料與連結細節的物件。
`update`	更新現有的湖畔別墅名稱或描述。	更新 `Artifact` 對象。
`delete`	刪除了一座湖畔別墅。	`Boolean`。如果成功即為 `True`；否則為 `False`。
`list`	在工作空間中列出湖邊別墅。	物件陣列 `Artifact` 。
`listTables`	列出湖邊小屋的桌子。	物件陣列 `Table` 。
`loadTable`	啟動一個湖屋桌的載入操作。	`Boolean`。如果成功即為 `True`；否則為 `False`。

# Method signatures
notebookutils.lakehouse.create(name: String, description: String = "", definition: Object = {}, workspaceId: String = ""): Artifact
notebookutils.lakehouse.get(name: String = "", workspaceId: String = ""): Artifact
notebookutils.lakehouse.getWithProperties(name: String, workspaceId: String = ""): Artifact
notebookutils.lakehouse.update(name: String, newName: String, description: String = "", workspaceId: String = ""): Artifact
notebookutils.lakehouse.delete(name: String, workspaceId: String = ""): Boolean
notebookutils.lakehouse.list(workspaceId: String = "", maxResults: Int = 1000): Array[Artifact]
notebookutils.lakehouse.listTables(lakehouse: String = "", workspaceId: String = "", maxResults: Int = 1000): Array[Table]
notebookutils.lakehouse.loadTable(loadOption: Object, table: String, lakehouse: String = "", workspaceId: String = ""): Boolean

所有方法都接受可選 workspaceId 參數。若省略，該操作會針對目前的工作區。指定一個工作區 ID 以便跨工作空間存取。你必須在目標工作區擁有適當的權限。

建立湖倉

用 notebookutils.lakehouse.create() 來在目前工作區或指定工作區建立新的湖屋。湖畔屋名稱必須在工作空間內獨一無二。

參數

參數	類型	Required	說明
`name`	繩子	是的	展示湖畔別墅名稱。必須在工作空間內保持獨特性。
`description`	繩子	No	湖邊別墅的文字描述。
`definition`	物件	No	湖邊別墅的結構化定義物件。請傳遞 `{"enableSchemas": True}` 或使用你語言的等效物件形式來啟用結構支援。
`workspaceId`	繩子	No	目標工作區 ID。預設為目前的工作區。

建立一個基本的湖畔小屋

artifact = notebookutils.lakehouse.create("lakehouse_name", "Description of the Lakehouse")

val artifact = notebookutils.lakehouse.create("lakehouse_name", "Description of the Lakehouse")

artifact <- notebookutils.lakehouse.create("lakehouse_name", "Description of the Lakehouse")

備註

將definition作為結構化物件傳遞給你的筆記本語言，例如 Python 字典、Scala Map或 R 列表。

建立一個有結構架構支援的湖屋

啟用結構支援後，湖屋支援多個結構來組織資料表。通過 {"enableSchemas": True} 作為 definition 參數：

artifact = notebookutils.lakehouse.create(
    "SalesAnalyticsWithSchema",
    "Lakehouse with schema support for multi-tenant data",
    {"enableSchemas": True}
)

print(f"Created lakehouse with schema support: {artifact.displayName}")
print(f"Lakehouse ID: {artifact.id}")

val definition = Map("enableSchemas" -> true)

val artifact = notebookutils.lakehouse.create(
    "SalesAnalyticsWithSchema",
    "Lakehouse with schema support for multi-tenant data",
    definition,
    ""
)

println(s"Created lakehouse with schema support: ${artifact.displayName}")
println(s"Lakehouse ID: ${artifact.id}")

artifact <- notebookutils.lakehouse.create(
    "SalesAnalyticsWithSchema",
    "Lakehouse with schema support for multi-tenant data",
    list(enableSchemas = TRUE)
)

print(paste("Created lakehouse with schema support:", artifact$displayName))
print(paste("Lakehouse ID:", artifact$id))

在不同的工作空間中建立湖畔小屋

workspace_id = "aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb"

artifact = notebookutils.lakehouse.create(
    name="SharedAnalytics",
    description="Shared analytics lakehouse",
    workspaceId=workspace_id
)

print(f"Created lakehouse in workspace: {workspace_id}")

val workspaceId = "aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb"

val artifact = notebookutils.lakehouse.create(
    "SharedAnalytics",
    "Shared analytics lakehouse",
    workspaceId = workspaceId
)

println(s"Created lakehouse in workspace: ${workspaceId}")

workspace_id <- "aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb"

artifact <- notebookutils.lakehouse.create(
    "SharedAnalytics",
    "Shared analytics lakehouse",
    workspaceId = workspace_id
)

print(paste("Created lakehouse in workspace:", workspace_id))

批量創建湖邊別墅

你可以在迴圈中建立多個湖屋，為不同團隊或專案配置環境：

departments = ["Sales", "Marketing", "Finance", "Operations"]

created_lakehouses = []
for dept in departments:
    lakehouse = notebookutils.lakehouse.create(
        name=f"{dept}Analytics",
        description=f"Analytics lakehouse for {dept} department"
    )
    created_lakehouses.append(lakehouse)
    print(f"Created: {lakehouse.displayName}")

print(f"Created {len(created_lakehouses)} lakehouses")

小提示

使用能反映湖畔別墅用途的描述性名稱。考慮環境分離的命名慣例，例如開發（dev）、測試（test）和生產（prod）。

買個湖邊別墅

用 notebookutils.lakehouse.get() 來依照名稱檢索湖畔小屋。如果你省略名稱，NotebookUtils 會使用目前預設的 lakehouse。

參數

參數	類型	Required	說明
`name`	繩子	No	要取回的湖邊小屋名稱。省略時預設為現有湖畔別墅。
`workspaceId`	繩子	No	目標工作區 ID。預設為目前的工作區。

artifact = notebookutils.lakehouse.get("lakehouse_name", "optional_workspace_id")

print(f"Lakehouse Name: {artifact.displayName}")
print(f"Lakehouse ID: {artifact.id}")
print(f"Workspace ID: {artifact.workspaceId}")

val artifact = notebookutils.lakehouse.get("lakehouse_name", "optional_workspace_id")
println(s"Lakehouse Name: ${artifact.displayName}")

artifact <- notebookutils.lakehouse.get("lakehouse_name", "optional_workspace_id")
print(paste("Lakehouse Name:", artifact$displayName))

買一間有延伸房產的湖邊別墅

當你需要超出基本元資料的擴展屬性，例如連線字串或設定細節時，請使用 notebookutils.lakehouse.getWithProperties() ：

artifact = notebookutils.lakehouse.getWithProperties("lakehouse_name", "optional_workspace_id")

print(f"Lakehouse: {artifact.displayName}")
print(f"Properties: {artifact.properties}")

val artifact = notebookutils.lakehouse.getWithProperties("lakehouse_name", "optional_workspace_id")

println(s"Lakehouse: ${artifact.displayName}")
println(s"Properties: ${artifact.properties}")

artifact <- notebookutils.lakehouse.getWithProperties("lakehouse_name", "optional_workspace_id")

print(paste("Lakehouse:", artifact$displayName))
print(artifact$properties)

從其他工作空間買一間湖邊別墅

workspace_id = "bbbbbbbb-2222-3333-4444-cccccccccccc"
artifact = notebookutils.lakehouse.get("SharedData", workspaceId=workspace_id)

print(f"Retrieved: {artifact.displayName} from workspace {workspace_id}")

val workspaceId = "bbbbbbbb-2222-3333-4444-cccccccccccc"
val artifact = notebookutils.lakehouse.get("SharedData", workspaceId)

println(s"Retrieved: ${artifact.displayName} from workspace ${workspaceId}")

workspace_id <- "bbbbbbbb-2222-3333-4444-cccccccccccc"
artifact <- notebookutils.lakehouse.get("SharedData", workspace_id)

print(paste("Retrieved:", artifact$displayName, "from workspace", workspace_id))

更新資料湖倉儲

用 notebookutils.lakehouse.update() 來更新現有湖畔別墅的名稱或描述。

這很重要

重新命名湖屋可以打破後續依賴關係，例如筆記本、管線或指向原始名稱的捷徑。在應用更名前，先與團隊協調。

參數

參數	類型	Required	說明
`name`	繩子	是的	湖畔別墅的現今名稱。
`newName`	繩子	是的	湖邊別墅的新名字。
`description`	繩子	No	更新說明。
`workspaceId`	繩子	No	目標工作區 ID。預設為目前的工作區。

updated_artifact = notebookutils.lakehouse.update(
    "old_name",
    "new_name",
    "Updated description",
    "optional_workspace_id"
)

print(f"Updated lakehouse: {updated_artifact.displayName}")

val updatedArtifact = notebookutils.lakehouse.update("old_name", "new_name", "Updated description", "optional_workspace_id")

updated_artifact <- notebookutils.lakehouse.update("old_name", "new_name", "Updated description", "optional_workspace_id")

刪除湖倉

用 notebookutils.lakehouse.delete() 來永久移除湖邊小屋，從工作空間中移除。

謹慎

刪除是永久的，無法撤銷。刪除前請確認 lakehouse 名稱，並檢查是否有相關的筆記本、管線或工作流程會參考它。

參數

參數	類型	Required	說明
`name`	繩子	是的	要刪除的湖邊小屋名稱。
`workspaceId`	繩子	No	目標工作區 ID。預設為目前的工作區。

is_deleted = notebookutils.lakehouse.delete("lakehouse_name", "optional_workspace_id")

if is_deleted:
    print("Lakehouse deleted successfully")
else:
    print("Failed to delete lakehouse")

val isDeleted = notebookutils.lakehouse.delete("lakehouse_name", "optional_workspace_id")

is_deleted <- notebookutils.lakehouse.delete("lakehouse_name", "optional_workspace_id")

湖畔別墅列表

用 notebookutils.lakehouse.list() 來列舉工作空間中的湖邊別墅。

參數

參數	類型	Required	說明
`workspaceId`	繩子	No	目標工作區 ID。預設為目前的工作區。
`maxResults`	整數	No	要傳回的項目數目上限。預設值為1000。

artifacts_list = notebookutils.lakehouse.list("optional_workspace_id")

print(f"Found {len(artifacts_list)} lakehouses:")
for lh in artifacts_list:
    print(f"  - {lh.displayName} (ID: {lh.id})")

val artifactsList = notebookutils.lakehouse.list("optional_workspace_id")

artifacts_list <- notebookutils.lakehouse.list("optional_workspace_id")

備註

在 Scala 中，list 方法以與其他筆記本語言相同的方式支援 maxResults。例如，使用 list(workspaceId, maxResults)。

表格清單

用 notebookutils.lakehouse.listTables() 來列出湖屋裡的所有表格。

參數

參數	類型	Required	說明
`lakehouse`	繩子	No	湖邊小屋的名字。省略時預設為現有湖畔別墅。
`workspaceId`	繩子	No	目標工作區 ID。預設為目前的工作區。
`maxResults`	整數	No	要傳回的項目數目上限。預設值為1000。

artifacts_tables_list = notebookutils.lakehouse.listTables("lakehouse_name", "optional_workspace_id")

val tables = notebookutils.lakehouse.listTables("lakehouse_name", "optional_workspace_id")

tables <- notebookutils.lakehouse.listTables("lakehouse_name", "optional_workspace_id")

載重表

用 notebookutils.lakehouse.loadTable() 來從檔案載入 Lakehouse 資料表。

參數

參數	類型	Required	說明
`loadOption`	物件	是的	結構化載入選項，指定檔案路徑、模式、格式及其他載入設定。
`table`	繩子	是的	目標資料表的名稱。
`lakehouse`	繩子	No	湖邊小屋的名字。省略時預設為現有湖畔別墅。
`workspaceId`	繩子	No	目標工作區 ID。預設為目前的工作區。

該 loadOption 物件支援以下金鑰：

鑰匙	說明
`relativePath`	相對於湖屋根的來源檔案路徑（例如， `Files/myFile.csv`）。
`pathType`	路徑類型。使用`File` 作為單一檔案。
`mode`	載入模式，例如 `Overwrite` 或 `Append`。
`recursive`	將其設定為 `True` 以包含子資料夾中的檔案。
`formatOptions`	一個具有格式特定設定的字典，如 `format`、 `header`、 `delimiter`。

範例：

result = notebookutils.lakehouse.loadTable(
    {
        "relativePath": "Files/myFile.csv",
        "pathType": "File",
        "mode": "Overwrite",
        "recursive": False,
        "formatOptions": {
            "format": "Csv",
            "header": True,
            "delimiter": ","
        }
    }, "table_name", "lakehouse_name", "optional_workspace_id")

if result:
    print("Table loaded successfully")
else:
    print("Table load failed")

val result = notebookutils.lakehouse.loadTable(
    Map(
        "relativePath" -> "Files/myFile.csv",
        "pathType" -> "File",
        "mode" -> "Overwrite",
        "recursive" -> false,
        "formatOptions" -> Map(
            "format" -> "Csv",
            "header" -> true,
            "delimiter" -> ","
        )
    ),
    "table_name",
    "lakehouse_name",
    "optional_workspace_id"
)

println(s"Table loaded successfully: ${result}")

result <- notebookutils.lakehouse.loadTable(
    list(
        relativePath = "Files/myFile.csv",
        pathType = "File",
        mode = "Overwrite",
        recursive = FALSE,
        formatOptions = list(
            format = "Csv",
            header = TRUE,
            delimiter = ","
        )
    ),
    "table_name",
    "lakehouse_name",
    "optional_workspace_id"
)

print(paste("Table loaded successfully:", result))

Fabric 笔记本工具

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-08-05