Condividi tramite

NotebookUtils lakehouse utilities

Usare notebookutils.lakehouse per gestire gli elementi Lakehouse a livello di codice nei notebook di Fabric. È possibile creare, ottenere, aggiornare, eliminare ed elencare lakehouse direttamente dal codice del notebook.

Le utilità Lakehouse sono disponibili nei notebook Python, PySpark, Scala e R. Gli esempi in questa pagina usano Python come linguaggio primario, con gli equivalenti Scala e R visualizzati per i metodi chiave.

Annotazioni

Le utilità Lakehouse sono supportate solo in Microsoft 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 un nuovo Lakehouse, con supporto facoltativo allo schema. Artifact oggetto con proprietà: id, displayName, descriptione workspaceId.
get Ottiene un Lakehouse per nome. Artifact oggetto con metadati di base.
getWithProperties Recupera una lakehouse con proprietà estese. Artifact oggetto con metadati estesi e dettagli di connessione.
update Aggiorna il nome o la descrizione di una lakehouse esistente. Oggetto aggiornato Artifact .
delete Elimina una lakehouse. Boolean. True se ha avuto esito positivo; in caso contrario, False.
list Elenca i Lakehouse in un'area di lavoro. Matrice di Artifact oggetti.
listTables Le elenca le tabelle in un "Lakehouse". Matrice di Table oggetti.
loadTable Avvia un'operazione di caricamento per una tabella Lakehouse. Boolean. True se riesce; 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.

Creare un lakehouse

Usare notebookutils.lakehouse.create() per creare un nuovo Lakehouse nell'area di lavoro corrente o in un'area di lavoro specificata. I nomi di Lakehouse devono essere univoci all'interno di un'area di lavoro.

Parametri

Parametro Tipo Obbligatorio Descrizione
name String Sì Nome visualizzato del Lakehouse. Deve essere univoco all'interno dell'area di lavoro.
description String No Descrizione di testo per Lakehouse.
definition oggetto No Oggetto di definizione strutturata per il Lakehouse. 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.

Creare un Lakehouse con supporto dello schema

Quando si abilita il supporto dello schema, Lakehouse supporta più schemi per l'organizzazione delle 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}")

Creazione batch di lakehouse

È possibile creare più Lakehouses in successione per fornire ambienti per team o progetti diversi.

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

Usare nomi descrittivi che riflettano lo scopo del Lakehouse e considerare le convenzioni di denominazione per la separazione degli ambienti (sviluppo, test, produzione).

Ottenere un lakehouse

Usare notebookutils.lakehouse.get() per recuperare un lakehouse in base al nome. Se si omette il nome, NotebookUtils utilizza il Lakehouse predefinito corrente.

Parametri

Parametro Tipo Obbligatorio Descrizione
name String No Nome della Lakehouse da recuperare. Il valore predefinito è impostato su il Lakehouse corrente quando viene omesso.
workspaceId String No ID area di lavoro di destinazione. L'impostazione predefinita è quella dell'area di lavoro corrente. 
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}")

Ottieni un lakehouse 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}")

Ottenere un lakehouse da un'altra area 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

Usare notebookutils.lakehouse.update() per aggiornare il nome o la descrizione di una lakehouse esistente.

Importante

La ridenominazione di una Lakehouse può interrompere le dipendenze downstream, come notebook, pipeline o collegamenti che fanno riferimento al nome originale. Coordina le ridenominazione con il team prima di applicarle.

Parametri

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

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

Eliminare un Lakehouse

Usare notebookutils.lakehouse.delete() per rimuovere definitivamente un Lakehouse da un'area di lavoro.

Attenzione

L'eliminazione è permanente e non può essere annullata. Verificare il nome di Lakehouse prima di eliminare e verificare la presenza di notebook, pipeline o flussi di lavoro dipendenti che vi fanno riferimento.

Parametri

Parametro Tipo Obbligatorio Descrizione
name String Sì Nome della Lakehouse da eliminare.
workspaceId String No ID area di lavoro di destinazione. L'impostazione predefinita è l'area di lavoro corrente. 
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

Usare notebookutils.lakehouse.list() per enumerare i lakehouse in un'area di lavoro.

Parametri

Parametro Tipo Obbligatorio Descrizione
workspaceId String No ID area di lavoro di destinazione. L'area di lavoro corrente viene impostata come predefinita.
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

Usare notebookutils.lakehouse.listTables() per elencare tutte le tabelle in un Lakehouse.

Parametri

Parametro Tipo Obbligatorio Descrizione
lakehouse String No Nome del Lakehouse Il valore predefinito è il "lakehouse" corrente quando viene omesso.
workspaceId String No ID area di lavoro di destinazione. L'impostazione predefinita è l'area di lavoro corrente.
maxResults Intero No Numero massimo di elementi da restituire. Impostazione predefinita è 1000. 
artifacts_tables_list = notebookutils.lakehouse.listTables("lakehouse_name", "optional_workspace_id")

Carica tabella

Usare notebookutils.lakehouse.loadTable() per caricare dati da file in una tabella 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 del Lakehouse. Il valore predefinito è il Lakehouse corrente quando viene omesso.
workspaceId String No ID area di lavoro di destinazione. L'impostazione predefinita è l'area di lavoro corrente.

L'oggetto loadOption supporta le chiavi seguenti:

Chiave Descrizione
relativePath Percorso del file di origine relativo 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