Compartilhar via

Utilitários do NotebookUtils Lakehouse

Use notebookutils.lakehouse para gerenciar itens do Lakehouse programaticamente em blocos de anotações do Fabric. Você pode criar, obter, atualizar, excluir e listar Lakehouses diretamente do código do notebook.

Os utilitários Lakehouse estão disponíveis em notebooks de Python, PySpark, Scala e R. Os exemplos nesta página usam o Python como o idioma principal, com equivalentes scala e R mostrados para métodos-chave.

Observação

As ferramentas de lakehouse têm suporte apenas no Microsoft Fabric. Eles não estão disponíveis no Azure Synapse Analytics.

Para exibir os métodos disponíveis e suas descrições, chame notebookutils.lakehouse.help().

Visão geral dos métodos

A tabela a seguir resume os métodos disponíveis:

Método Descrição Devoluções
create Cria um novo Lakehouse, com suporte de esquema opcional. Artifactobjeto com propriedades: id, , displayNamee descriptionworkspaceId.
get Recupera um Lakehouse pelo nome. Artifact objeto com metadados básicos.
getWithProperties Recupera um Lakehouse com propriedades estendidas. Artifact objeto com metadados estendidos e detalhes da conexão.
update Atualiza um nome ou descrição existente do Lakehouse. Objeto atualizado Artifact .
delete Exclui um Lakehouse. Boolean. True se for bem-sucedido; caso contrário, False.
list Lista Lakehouses em um espaço de trabalho. Matriz de Artifact objetos.
listTables Lista tabelas em um Lakehouse. Matriz de Table objetos.
loadTable Inicia uma operação de carga para uma tabela "lakehouse". Boolean. True se for bem-sucedido; caso contrário, 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

Todos os métodos aceitam um parâmetro opcional workspaceId . Quando omitida, a operação tem como destino o espaço de trabalho atual. Especifique um ID de espaço de trabalho para acesso entre espaços de trabalho. Você deve ter permissões apropriadas no workspace de destino.

Criar um Lakehouse

Use notebookutils.lakehouse.create() para criar um novo Lakehouse no espaço de trabalho atual ou em um espaço de trabalho especificado. Os nomes de Lakehouse devem ser exclusivos em um workspace.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name String Sim Nome de exibição do Lakehouse. Deve ser exclusivo dentro do espaço de trabalho.
description String No Uma descrição de texto para o Lakehouse.
definition Objeto No Objeto de definição estruturado para o Lakehouse. Passe {"enableSchemas": True} ou a forma de objeto equivalente do seu idioma para habilitar o suporte ao esquema.
workspaceId String No ID do workspace de destino. O padrão é o espaço de trabalho atual.

Criar um Lakehouse básico

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

Observação

Passe definition como um objeto estruturado para sua linguagem de notebook, como um dicionário Python, um Scala Mapou uma lista R.

Criar um Lakehouse com suporte a esquema

Quando você habilita o suporte ao esquema, o Lakehouse dá suporte a vários esquemas para organizar tabelas. Passe {"enableSchemas": True} como o definition parâmetro:

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

Criar um Lakehouse em um workspace diferente

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

Criar lakehouses em lote

Você pode criar vários Lakehouses em um loop para provisionar ambientes para equipes ou projetos diferentes:

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

Dica

Use nomes descritivos que reflitam a finalidade do Lakehouse e considere convenções de nomenclatura para separação dos ambientes (desenvolvimento, teste, produção).

Obter um Lakehouse

Utilize notebookutils.lakehouse.get() para recuperar um Lakehouse pelo nome. Se você omitir o nome, o NotebookUtils usará o Lakehouse padrão atual.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name String No Nome do Lakehouse para obter. O padrão é o Lakehouse atual quando omitido.
workspaceId String No ID do workspace de destino. O padrão é o espaço de trabalho atual. 
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}")

Obter um Lakehouse com propriedades estendidas

Use quando precisar de notebookutils.lakehouse.getWithProperties() propriedades estendidas além dos metadados básicos, como cadeias de conexão ou detalhes de configuração:

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

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

Obtenha um Lakehouse de outro espaço de trabalho

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

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

Atualizar um Lakehouse

Use notebookutils.lakehouse.update() para atualizar o nome ou a descrição de um Lakehouse existente.

Importante

Renomear um Lakehouse pode comprometer dependências posteriores, como notebooks, pipelines ou atalhos que fazem referência ao nome original. Coordene renomeações com sua equipe antes de aplicá-las.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name String Sim Nome atual do Lakehouse.
newName String Sim Novo nome para o Lakehouse.
description String No Descrição atualizada.
workspaceId String No ID do workspace de destino. O padrão é o espaço de trabalho atual. 
updated_artifact = notebookutils.lakehouse.update(
    "old_name",
    "new_name",
    "Updated description",
    "optional_workspace_id"
)

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

Excluir um Lakehouse

Use notebookutils.lakehouse.delete() para remover permanentemente um Lakehouse de um workspace.

Cuidado

A exclusão é permanente e não pode ser desfeita. Certifique-se de que o nome do Lakehouse está correto antes de excluí-lo e verifique se há notebooks, pipelines ou fluxos de trabalho dependentes que fazem referência a ele.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name String Sim Nome do Lakehouse que será excluído.
workspaceId String No ID do workspace de destino. O padrão é o espaço de trabalho atual. 
is_deleted = notebookutils.lakehouse.delete("lakehouse_name", "optional_workspace_id")

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

Listar Lakehouses

Use notebookutils.lakehouse.list() para enumerar Lakehouses em um workspace.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
workspaceId String No ID do workspace de destino. O padrão é o espaço de trabalho atual.
maxResults int No Número máximo de itens a serem retornados. O valor padrão é 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})")

Observação

Em Scala, o método list oferece suporte maxResults da mesma forma que as outras linguagens de programação do notebook. Por exemplo, use list(workspaceId, maxResults).

Listar tabelas

Use notebookutils.lakehouse.listTables() para listar todas as tabelas em um Lakehouse.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
lakehouse String No Nome do Lakehouse. O padrão é para o Lakehouse atual quando omitido.
workspaceId String No ID do workspace de destino. O padrão é o espaço de trabalho atual.
maxResults int No Número máximo de itens a serem retornados. O valor padrão é 1000. 
artifacts_tables_list = notebookutils.lakehouse.listTables("lakehouse_name", "optional_workspace_id")

Tabela de carga

Use notebookutils.lakehouse.loadTable() para carregar dados de arquivos em uma tabela Lakehouse.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
loadOption Objeto Sim Opções de carga estruturadas que especificam o caminho do arquivo, o modo, o formato e outras configurações de carga.
table String Sim Nome da tabela de destino.
lakehouse String No Nome do Lakehouse. O padrão é o Lakehouse atual quando omitido.
workspaceId String No ID do workspace de destino. O padrão é o espaço de trabalho atual.

O loadOption objeto dá suporte às seguintes chaves:

Chave Descrição
relativePath Caminho para o arquivo de origem relativo à raiz Lakehouse (por exemplo, Files/myFile.csv).
pathType Tipo de caminho. Use File para um único arquivo.
mode Modo de carregamento, como Overwrite ou Append.
recursive Definido para True para incluir arquivos em subpastas.
formatOptions Um dicionário com configurações específicas de formato, como format, headere delimiter.

Exemplo:

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

Conteúdo relacionado

  • Last updated on