Partilhar via

Utilidades da casa do lago NotebookUtils

Uso notebookutils.lakehouse para gerir os itens do Lakehouse programaticamente em cadernos Fabric. Pode criar, obter, atualizar, eliminar e listar Lakehouses diretamente a partir do código do caderno.

As utilidades da Lakehouse estão disponíveis em cadernos Python, PySpark, Scala e R. Os exemplos nesta página usam Python como linguagem principal, com equivalentes em Scala e R mostrados para os métodos-chave.

Observação

As ferramentas Lakehouse são suportadas apenas em Microsoft Fabric. Não estão disponíveis no Azure Synapse Analytics.

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

Visão geral dos métodos

A tabela seguinte resume os métodos disponíveis:

Método Descrição Devoluções
create Cria um novo Lakehouse, com suporte opcional de esquemas. Artifact objeto com propriedades: id, displayName, description, e workspaceId.
get Recupera um Lakehouse pelo nome. Artifact objeto com metadados básicos.
getWithProperties Recupera um Lakehouse com propriedades adicionais. Artifact objeto com metadados estendidos e detalhes de ligação.
update Atualiza o nome ou descrição existente do Lakehouse. Objeto atualizado Artifact .
delete Apaga uma casa do lago. Boolean. True se for bem-sucedido; caso contrário, False.
list Lista Casas de Lago num espaço de trabalho. Conjunto de Artifact objetos.
listTables Listas de tabelas numa casa do lago. Conjunto de Table objetos.
loadTable Inicia uma operação de carregamento 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 omitido, a operação dirige-se ao espaço de trabalho atual. Especifique um ID de espaço de trabalho para acesso entre espaços de trabalho. Deve ter permissões apropriadas no espaço de trabalho alvo.

Crie uma Lakehouse

notebookutils.lakehouse.create() Use para criar uma nova Lakehouse no espaço de trabalho atual ou num espaço de trabalho especificado. Os nomes de Lakehouse devem ser únicos dentro de uma workspace.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name Cordão Sim Nome de exibição do Lakehouse. Tem de ser único dentro do espaço de trabalho.
description Cordão No Uma descrição em texto da Casa do Lago.
definition Objeto No Objeto de definição estruturada para o Lakehouse. Passe {"enableSchemas": True} ou a forma de objeto equivalente para a tua língua para ativar o suporte a esquemas.
workspaceId Cordão No ID do espaço de trabalho alvo. Por padrão, define-se como o espaço de trabalho atual.

Crie uma casa de lago básica

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

Observação

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

Crie um Lakehouse com suporte de esquemas

Quando ativas o suporte de esquemas, o Lakehouse suporta múltiplos esquemas para organizar tabelas. Passe {"enableSchemas": True} como parâmetro 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}")

Crie uma Casa do Lago num espaço de trabalho 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}")

Criação em lote de Lakehouses

Pode criar vários Lakehouses em sequência para provisionar ambientes para diferentes equipas ou projetos.

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

Sugestão

Use nomes descritivos que reflitam o propósito do Lakehouse e considere convenções de nomeação para a separação do ambiente (dev, test, prod).

Adquira um Lakehouse

Use notebookutils.lakehouse.get() para recuperar um Lakehouse pelo nome. Se omitires o nome, o NotebookUtils usará o Lakehouse predefinido atual.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name Cordão No Nome da Casa do Lago para recuperar. Por padrão, utiliza-se o Lakehouse atual quando omitido.
workspaceId Cordão No ID do espaço de trabalho alvo. Por padrão, define-se como 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}")

Adquira uma casa no lago com propriedades ampliadas

Use notebookutils.lakehouse.getWithProperties() quando precisar de propriedades estendidas para além de metadados básicos, como cadeias de ligaçã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}")

Obtém 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 uma Casa do Lago

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

Importante

Renomear um Lakehouse pode quebrar dependências posteriores, como cadernos, pipelines ou atalhos que fazem referência ao nome original. Coordena as renomeações com a tua equipa antes de as aplicar.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name Cordão Sim Nome atual da Casa do Lago.
newName Cordão Sim Novo nome para a Casa do Lago.
description Cordão No Descrição atualizada.
workspaceId Cordão No ID do espaço de trabalho alvo. Por padrão, define-se como 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}")

Eliminar um Lakehouse

Utilize notebookutils.lakehouse.delete() para remover permanentemente um Lakehouse de um espaço de trabalho.

Atenção

A eliminação é permanente e não pode ser desfeita. Verifica o nome Lakehouse antes de o apagar e verifica se há cadernos dependentes, pipelines ou fluxos de trabalho que o referenciam.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
name Cordão Sim Nome da casa do lago para apagar.
workspaceId Cordão No ID do espaço de trabalho alvo. Por padrão, define-se como 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")

Lista Lakehouses

Use notebookutils.lakehouse.list() para enumerar Lakehouses num espaço de trabalho.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
workspaceId Cordão No ID do espaço de trabalho alvo. Por padrão, define-se como o espaço de trabalho atual.
maxResults Int No Número máximo de itens a devolver. 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

No Scala, o list método suporta maxResults a mesma forma que as outras linguagens de cadernos. Por exemplo, use list(workspaceId, maxResults).

Listar tabelas

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

Parâmetros

Parâmetro Tipo Obrigatório Descrição
lakehouse Cordão No Nome do Lakehouse Por padrão, utiliza-se o Lakehouse atual quando não especificado.
workspaceId Cordão No ID do espaço de trabalho alvo. Por padrão, define-se como o espaço de trabalho atual.
maxResults Int No Número máximo de itens a devolver. 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 ficheiros numa tabela Lakehouse.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
loadOption Objeto Sim Opções de carregamento estruturadas que especificam o caminho do ficheiro, modo, formato e outras definições de carga.
table Cordão Sim Nome da tabela alvo.
lakehouse Cordão No Nome do Lakehouse. Por defeito, a Casa do Lago atual é omitida.
workspaceId Cordão No ID do espaço de trabalho alvo. Por padrão, define-se como o espaço de trabalho atual.

O loadOption objeto suporta as seguintes teclas:

Chave Descrição
relativePath Caminho para o ficheiro fonte relativo à raiz do Lakehouse (por exemplo, Files/myFile.csv).
pathType Tipo de caminho. Usa File para um ficheiro único.
mode Modo de carga, como Overwrite ou Append.
recursive Defina para True para incluir os ficheiros nas subpastas.
formatOptions Um dicionário com definições específicas de formato como format, header, e 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