NotebookUtils Lakehouse 实用工具

用notebookutils.lakehouse来在 Fabric 笔记本中程序管理湖屋物品。 你可以直接从笔记本代码创建、获取、更新、删除和列出湖屋。

湖屋工具可在Python、PySpark、Scala和R笔记本中使用。 此页上的示例使用 Python 作为主要语言,其中显示了键方法的 Scala 和 R 等效项。

注释

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() 来在当前工作区或指定工作区创建新的湖屋。 Lakehouse 名称在工作区中必须唯一。

参数

参数 类型 必需 说明
name String 是的 湖边别墅的展示名称。 必须在工作区内保持唯一。
description String 否 湖边别墅的文字描述。
definition 对象 否 湖边别墅的结构化定义对象。 为你的语言传递 {"enableSchemas": True} 或等效的对象形式以启用模式支持。
workspaceId String 否 目标工作区 ID。 默认为当前工作区。

创建一个基本的 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}")

在不同工作区中创建 Lakehouse

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}")

批量创建湖畔别墅

你可以在循环中创建多个湖屋,为不同的团队或项目配置环境:

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")

小窍门

使用能体现湖畔别墅用途的描述性名称。 考虑环境分离的命名规范,如开发、测试和生产。

买个湖边别墅

用来 notebookutils.lakehouse.get() 按名字检索湖边别墅。 如果你省略了名称,NotebookUtils 会使用当前默认的 lakehouse。

参数

参数 类型 必需 说明
name String 否 要取回的湖边小屋名字。 省略时默认使用当前的湖畔别墅。
workspaceId String 否 目标工作区 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}")

买一栋带扩展房产的湖边别墅

如果需要超出基本元数据的扩展属性,例如连接字符串或配置详细信息,请使用 notebookutils.lakehouse.getWithProperties() :

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

print(f"Lakehouse: {artifact.displayName}")
print(f"Properties: {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}")

创建湖屋

用于 notebookutils.lakehouse.update() 更新现有湖畔别墅的名称或描述。

重要

重命名湖屋可以破坏后续依赖关系,比如笔记本、管道或引用原名称的快捷方式。 在应用重命名之前,请与团队协调。

参数

参数 类型 必需 说明
name String 是的 湖畔别墅的现名。
newName String 是的 湖边别墅的新名字。
description String 否 更新了说明。
workspaceId String 否 目标工作区 ID。 默认为当前工作区。
updated_artifact = notebookutils.lakehouse.update(
    "old_name",
    "new_name",
    "Updated description",
    "optional_workspace_id"
)

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

删除湖屋

用 notebookutils.lakehouse.delete() 来永久移除一个湖边别墅,离开工作空间。

注意

删除是永久性的,无法撤消。 删除前请核实湖屋名称,并检查是否有相关的笔记本、管道或工作流引用该名称。

参数

参数 类型 必需 说明
name String 是的 要删除的湖边别墅名称。
workspaceId String 否 目标工作区 ID。 默认为当前工作区。
is_deleted = notebookutils.lakehouse.delete("lakehouse_name", "optional_workspace_id")

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

湖畔别墅列表

用 notebookutils.lakehouse.list() 来枚举工作空间中的湖边别墅。

参数

参数 类型 必需 说明
workspaceId String 否 目标工作区 ID。 默认为当前工作区。
maxResults int (整数) 否 要返回项目的最大数量。 默认值为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})")

注释

在 Scala 中,该方法 list 以与其他笔记本语言相同的方式支持 maxResults。 例如,使用 list(workspaceId, maxResults)。

列出表格

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

参数

参数 类型 必需 说明
lakehouse String 否 湖边别墅的名字。 省略时默认使用当前的湖畔别墅。
workspaceId String 否 目标工作区 ID。 默认为当前工作区。
maxResults int (整数) 否 要返回项目的最大数量。 默认值为1000。
artifacts_tables_list = notebookutils.lakehouse.listTables("lakehouse_name", "optional_workspace_id")

加载表

用 notebookutils.lakehouse.loadTable() 来将文件中的数据加载到湖屋表中。

参数

参数 类型 必需 说明
loadOption 对象 是的 用于指定文件路径、模式、格式和其他加载设置的结构化加载选项。
table String 是的 目标表的名称。
lakehouse String 否 湖边别墅的名字。 省略时默认使用当前的湖畔别墅。
workspaceId String 否 目标工作区 ID。 默认为当前工作区。

该 loadOption 对象支持以下键:

密钥 说明
relativePath 相对于湖屋根的路径(例如, Files/myFile.csv)。
pathType 路径的类型。 使用File表示单个文件。
mode 加载模式,例如 Overwrite 或 Append。
recursive 设置为 True 以包含子文件夹中的文件。
formatOptions 具有特定格式设置的字典,例如 format, header和 delimiter。

Example:

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")