通过

NotebookUtils Lakehouse 实用工具

使用 notebookutils.lakehouse 在 Fabric 笔记本中以编程方式管理 Lakehouse 项目。 可以直接通过笔记本代码来创建、获取、更新、删除和列出 Lakehouses。

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

注释

Lakehouse 实用工具仅在 Microsoft Fabric 中受支持。 它们在 Azure Synapse Analytics 中不可用。

若要显示可用方法及其说明，请调用 notebookutils.lakehouse.help()。

方法概述

下表总结了可用的方法：

方法 说明 退货
create 创建一个支持可选架构的新Lakehouse。 Artifact 具有属性的对象： id、 displayName、 description和 workspaceId。
get 按名称检索 Lakehouse。 Artifact 具有基本元数据的对象。
getWithProperties 检索具有扩展属性的 Lakehouse。 Artifact 具有扩展元数据和连接详细信息的对象。
update 更新现有的 Lakehouse 名称或说明。 更新 Artifact 的对象。
delete 删除 Lakehouse。 Boolean。 如果成功，则为 True；否则为 False。
list 列出工作区中的 Lakehouses。 Artifact对象的数组。
listTables 列出 Lakehouse 中的表。 Table对象的数组。
loadTable 启动 Lakehouse 表的加载操作。 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。 Lakehouse 名称在工作区中必须唯一。

参数

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

创建一个基本的 Lakehouse

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

注释

作为笔记本语言的结构化对象传递 definition ，例如 Python 字典、Scala Map或 R 列表。

创建具有架构支持的 Lakehouse

启用架构支持时，Lakehouse 支持多个架构来组织表。 将{"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}")

批量创建 Lakehouses

可以在循环中创建多个 Lakehouses 来为不同的团队或项目预配环境：

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

小窍门

使用反映 Lakehouse 用途的描述性名称，并考虑环境分离（开发、测试、生产）的命名约定。

获取 Lakehouse

使用 notebookutils.lakehouse.get() 根据名称检索 Lakehouse。 如果省略名称，NotebookUtils 将使用当前的默认 Lakehouse。

参数

参数 类型 必需 说明
name String 否 要检索的 Lakehouse 的名称。 省略时将默认为当前的 Lakehouse。
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}")

获取具有扩展属性的 Lakehouse

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

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

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

从另一个工作区获取 Lakehouse

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

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

更新 Lakehouse

使用 notebookutils.lakehouse.update() 更新 Lakehouse 的现有名称或描述。

重要

重命名 Lakehouse 可能会破坏引用原始名称的笔记本、管道或快捷方式等下游依赖项。 在应用重命名之前，请与团队协调。

参数

参数 类型 必需 说明
name String 是的 Lakehouse 的当前名称。
newName String 是的 Lakehouse 的新名称。
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}")

删除 Lakehouse

使用 notebookutils.lakehouse.delete() 从工作区中永久移除 Lakehouse。

注意

删除是永久性的，无法撤消。 在删除 Lakehouse 名称之前，请验证它，并检查引用它的依赖笔记本、管道或工作流。

参数

参数 类型 必需 说明
name String 是的 要删除的 Lakehouse 的名称。
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() 枚举工作区内的 Lakehouses。

参数

参数 类型 必需 说明
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 中的所有表。

参数

参数 类型 必需 说明
lakehouse String 否 湖屋的名称。 如果被省略，则默认为当前 Lakehouse。
workspaceId String 否 目标工作区 ID。 默认为当前工作区。
maxResults int (整数) 否 要返回的最大项数。 默认值为1000。 
artifacts_tables_list = notebookutils.lakehouse.listTables("lakehouse_name", "optional_workspace_id")

加载表

使用notebookutils.lakehouse.loadTable()将数据从文件加载到 Lakehouse 表中。

参数

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

该 loadOption 对象支持以下键：

密钥 说明
relativePath 相对于 Lakehouse 根目录的源文件路径（例如 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")

相关内容

  • Last updated on