NotebookUtils utilità del lakehouse

Usalo notebookutils.lakehouse per gestire in modo programmatico gli oggetti della casa del lago nei quaderni Fabric. Puoi creare, ottenere, aggiornare, cancellare e elencare le case sul lago direttamente dal codice del notebook.

Le utility della casa del lago sono disponibili in Python, PySpark, Scala e notebook R. Gli esempi in questa pagina usano Python come linguaggio primario, con gli equivalenti Scala e R visualizzati per i metodi chiave.

Annotazioni

Le utenze Lakehouse sono supportate solo in Fabric. Non sono disponibili in Azure Synapse Analytics.

Per visualizzare i metodi disponibili e le relative descrizioni, chiamare notebookutils.lakehouse.help().

Panoramica dei metodi

La tabella seguente riepiloga i metodi disponibili:

metodo Descrizione Restituzioni
create Crea una nuova casa sul lago, con supporto opzionale per lo schema. Artifact oggetto con proprietà: id, displayName, descriptione workspaceId.
get Recupera una casa sul lago per nome. Artifact oggetto con metadati di base.
getWithProperties Recupera una casa sul lago con proprietà estese. Artifact oggetto con metadati estesi e dettagli di connessione.
update Aggiorna il nome o la descrizione di una casa sul lago esistente. Oggetto aggiornato Artifact .
delete Elimina una casa sul lago. Boolean. True se ha avuto esito positivo; in caso contrario, False.
list Elenca le case sul lago in uno spazio di lavoro. Matrice di Artifact oggetti.
listTables Elenca tavoli in una casa sul lago. Matrice di Table oggetti.
loadTable Avvia un'operazione di carico per un tavolo a casa del lago. Boolean. True se ha avuto esito positivo; in caso contrario, 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

Tutti i metodi accettano un parametro facoltativo workspaceId . Se viene omesso, l'operazione è destinata all'area di lavoro corrente. Specificare un ID area di lavoro per l'accesso tra aree di lavoro. È necessario disporre delle autorizzazioni appropriate nell'area di lavoro di destinazione.

Crea un lakehouse

Usalo notebookutils.lakehouse.create() per creare una nuova casa sul lago nello spazio di lavoro attuale o in uno spazio specificato. I nomi di Lakehouse devono essere univoci all'interno di un'area di lavoro.

Parametri

Parametro Tipo Obbligatorio Descrizione
name String Sì Nome espositivo della casa sul lago. Deve essere univoco all'interno dell'area di lavoro.
description String No Una descrizione testuale della casa sul lago.
definition oggetto No Oggetto di definizione strutturata per la casa sul lago. Passare {"enableSchemas": True} o la forma oggetto equivalente per il tuo linguaggio per abilitare il supporto per lo schema.
workspaceId String No ID area di lavoro di destinazione. L'impostazione predefinita è l'area di lavoro attuale.

Creare un Lakehouse di base

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

Annotazioni

Passa definition come oggetto strutturato per il linguaggio notebook, ad esempio un dizionario Python, una Scala Map o un elenco R.

Crea una casa sul lago con supporto di schema

Quando abiliti il supporto degli schemi, il lakehouse supporta più schemi per organizzare le tabelle. Passa {"enableSchemas": True} come parametro 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}")

Creare un lakehouse in un'area di lavoro diversa

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

Costruiscono a loti case sul lago

Puoi creare più lakehouse in un ciclo per fornire ambienti a diversi team o progetti:

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

Suggerimento

Usa nomi descrittivi che riflettano lo scopo della casa sul lago. Considera convenzioni di denominazione per la separazione dell'ambiente, come dev, test e prod.

Prendi una casa sul lago

Usato notebookutils.lakehouse.get() per recuperare una casa sul lago per nome. Se ometti il nome, NotebookUtils usa l'attuale lakehouse predefinito.

Parametri

Parametro Tipo Obbligatorio Descrizione
name String No Nome della casa sul lago da recuperare. Di default si usa la casa attuale sul lago quando viene omessa.
workspaceId String No ID area di lavoro di destinazione. L'impostazione predefinita è l'area di lavoro attuale. 
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}")

Prendi una casa sul lago con proprietà estese

Usare notebookutils.lakehouse.getWithProperties() quando sono necessarie proprietà estese oltre i metadati di base, ad esempio stringhe di connessione o dettagli di configurazione:

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

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

Prendi una casa sul lago da un altro posto di lavoro

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

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

Aggiornare un lakehouse

Da usare notebookutils.lakehouse.update() per aggiornare il nome o la descrizione di una casa sul lago esistente.

Importante

Rinominare una casa sul lago può rompere dipendenze a valle come notebook, pipeline o scorciatoie che fanno riferimento al nome originale. Coordina le ridenominazione con il team prima di applicarle.

Parametri

Parametro Tipo Obbligatorio Descrizione
name String Sì Nome attuale della casa sul lago.
newName String Sì Nuovo nome per la casa sul lago.
description String No Descrizione aggiornata.
workspaceId String No ID area di lavoro di destinazione. L'impostazione predefinita è l'area di lavoro attuale. 
updated_artifact = notebookutils.lakehouse.update(
    "old_name",
    "new_name",
    "Updated description",
    "optional_workspace_id"
)

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

Eliminare un lakehouse

Usalo notebookutils.lakehouse.delete() per rimuovere permanentemente una casa sul lago da uno spazio di lavoro.

Attenzione

L'eliminazione è permanente e non può essere annullata. Verifica il nome della casa del lago prima di cancellarlo e controlla se i quaderni, le pipeline o i flussi di lavoro che vi fanno riferimento.

Parametri

Parametro Tipo Obbligatorio Descrizione
name String Sì Nome della casa sul lago da cancellare.
workspaceId String No ID area di lavoro di destinazione. L'impostazione predefinita è l'area di lavoro attuale. 
is_deleted = notebookutils.lakehouse.delete("lakehouse_name", "optional_workspace_id")

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

Elenco delle case sul lago

Usalo notebookutils.lakehouse.list() per elencare le case sul lago in uno spazio di lavoro.

Parametri

Parametro Tipo Obbligatorio Descrizione
workspaceId String No ID area di lavoro di destinazione. L'impostazione predefinita è l'area di lavoro attuale.
maxResults Intero No Numero massimo di elementi da restituire. Di default è 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})")

Annotazioni

In Scala, il metodo list supporta maxResults nello stesso modo degli altri linguaggi del notebook. Ad esempio, usare list(workspaceId, maxResults).

Elenco delle tabelle

Usalo notebookutils.lakehouse.listTables() per elencare tutti i tavoli di una casa sul lago.

Parametri

Parametro Tipo Obbligatorio Descrizione
lakehouse String No Nome della casa sul lago. Di default si usa la casa attuale sul lago quando viene omessa.
workspaceId String No ID area di lavoro di destinazione. L'impostazione predefinita è l'area di lavoro attuale.
maxResults Intero No Numero massimo di elementi da restituire. Di default è 1000. 
artifacts_tables_list = notebookutils.lakehouse.listTables("lakehouse_name", "optional_workspace_id")

Carica tabella

Usalo notebookutils.lakehouse.loadTable() per caricare dati dai file in una tabella di lakehouse.

Parametri

Parametro Tipo Obbligatorio Descrizione
loadOption oggetto Sì Opzioni di caricamento strutturate che specificano il percorso del file, la modalità, il formato e altre impostazioni di caricamento.
table String Sì Nome della tabella di destinazione.
lakehouse String No Nome della casa sul lago. Di default si usa la casa attuale sul lago quando viene omessa.
workspaceId String No ID area di lavoro di destinazione. L'impostazione predefinita è l'area di lavoro attuale.

L'oggetto loadOption supporta le chiavi seguenti:

Chiave Descrizione
relativePath Percorso verso il file sorgente rispetto alla radice lakehouse (ad esempio, Files/myFile.csv).
pathType Tipo di percorso. Usare File per un singolo file.
mode Modalità di caricamento, ad esempio Overwrite o Append.
recursive Imposta su True per includere i file nelle sottocartelle.
formatOptions Dizionario con impostazioni specifiche del formato, ad esempio format, headere delimiter.

Esempio:

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

Contenuti correlati

  • Last updated on