Un job di caricamento sbagliato sovrascrive la cartella di produzione del tuo data lake: come torni indietro, e come avresti potuto provarlo prima su una copia? lakeFS risponde applicando ai dati le idee di Git: rami che sono puntatori, commit immutabili, merge a tre vie. Prima di installarlo, però, c'è una cosa da sapere che molti tutorial non dicono: dalla versione 1.87.0 la licenza del progetto non è più Apache 2.0.
Prerequisiti. Nozioni di Git (commit, ramo, merge) e di object storage; i listati Python usano lo stesso ambiente degli articoli precedenti.
La licenza, prima di tutto
Il 22 settembre 2026 il progetto ha annunciato che, a partire dalla versione 1.87.0, l'edizione Community passa dalla licenza Apache 2.0 alla Business Source License 1.1; le versioni pubblicate prima restano Apache 2.0. Il file LICENSE del repository, letto il 2026-11-13, indica come Licensor Treeverse Labs Ltd., come opera licenziata "lakeFS 1.87.0" e come licenza di conversione Apache 2.0, dopo quattro anni dalla pubblicazione di ciascuna versione. La BSL, dice il testo stesso, non è una licenza open source riconosciuta, anche se il codice resta pubblico. In pratica, la concessione d'uso aggiuntiva ammette l'uso in produzione, a qualunque scala, a due condizioni:
- il programma deve essere quello distribuito dal fornitore, senza modifiche, fork o opere derivate (configurarlo e scrivere software che lo usa tramite le interfacce pubbliche documentate non conta come modifica);
- l'uso deve essere solo per le esigenze interne della tua organizzazione, quindi non puoi offrirlo, ospitarlo o renderne disponibile la funzionalità a terzi;
Per un team che versiona i propri dati dentro la propria azienda, queste condizioni sono compatibili con l'uso normale. Se invece vuoi rivendere un servizio costruito su lakeFS, o mantenere un tuo fork in produzione, ti serve un accordo commerciale. Il testo della licenza e l'annuncio sono documenti legali e commerciali: leggili direttamente e, se il caso è borderline, scrivi al fornitore come l'annuncio stesso invita a fare. La libreria Python lakefs è un'altra cosa e resta Apache-2.0, secondo i suoi metadati su PyPI.
Le edizioni sono tre, secondo la pagina della documentazione: Community (gratuita sotto BSL), Team (con controllo accessi, Iceberg REST Catalog, gestione della retention, audit; la pagina riporta 499 dollari al mese per 5 utenti e 500 GB dopo la prova di 30 giorni, prezzo letto il 2026-11-13) ed Enterprise (a contratto). I prezzi cambiano: verificali alla fonte il giorno in cui decidi.
Il modello: rami che non copiano nulla
La parte che rende lakeFS utile è semplice da dire: un ramo è un puntatore a un commit più un insieme di modifiche non ancora committate, e crearlo non duplica i dati, come spiega la documentazione. I dati restano nel tuo object storage e lakeFS gestisce puntatori e metadati. Un commit è un'istantanea immutabile dell'intero repository, con autore, data, messaggio e coppie chiave-valore a piacere.
Il merge funziona come in Git: trova il commit antenato comune più vicino (merge base) e confronta, per ogni file, com'era alla base, nel ramo sorgente e in quello di destinazione. La documentazione riporta la tabella completa dei casi; il listato qui sotto la riproduce in un modello giocattolo di una trentina di righe e verifica tutte e dieci le righe. Non è il codice di lakeFS: serve a vedere le regole, perché le regole sono ciò che devi capire.
"""Modello giocattolo: NON e' il codice di lakeFS, riproduce le regole descritte nella sua documentazione."""
from types import MappingProxyType
class Commit:
def __init__(self, files, parents=()):
self.files = MappingProxyType(dict(files)) # contenuto congelato: un commit non cambia piu'
self.parents = parents
def antenati(c):
visti, coda = [], [c]
while coda:
x = coda.pop(0)
if x not in visti:
visti.append(x)
coda.extend(x.parents)
return visti
def base_comune(a, b):
sa = antenati(a)
return next(x for x in antenati(b) if x in sa) # il primo antenato di b che e' anche di a
def unisci(base, sorgente, dest, strategia=None):
"""Tre vie, file per file. None = file assente."""
risultato, conflitti = {}, []
for p in sorted(set(base) | set(sorgente) | set(dest)):
a, b, c = base.get(p), sorgente.get(p), dest.get(p)
if b == c: scelto = b # uguali (o cancellati) da entrambe le parti
elif a == b: scelto = c # cambiato solo in destinazione
elif a == c: scelto = b # cambiato solo in sorgente
elif strategia == "source-wins": scelto = b
elif strategia == "dest-wins": scelto = c
else:
conflitti.append(p); continue
if scelto is not None:
risultato[p] = scelto
return risultato, conflitti
# 1) le dieci righe della tabella di "How Merges Work" (A, B, C = contenuti; X = assente)
RIGHE = [("A","A","A","A"), ("A","B","B","B"), ("A","B","C","conflitto"), ("A","A","B","B"),
("A","B","A","B"), ("A","X","X","X"), ("A","B","X","conflitto"), ("A","X","B","conflitto"),
("A","A","X","X"), ("A","X","A","X")]
val = lambda s: None if s == "X" else s
for base, sorg, dest, atteso in RIGHE:
ris, conf = unisci({"f": val(base)} if base != "X" else {}, {"f": val(sorg)} if sorg != "X" else {},
{"f": val(dest)} if dest != "X" else {})
esito = "conflitto" if conf else (ris.get("f") or "X")
assert esito == atteso, (base, sorg, dest, esito)
print(f"base {base} sorgente {sorg} destinazione {dest} -> {esito}")
# 2) un ramo e' un puntatore: crearlo non copia nulla
main = Commit({"ordini/2026-11-12.parquet": "h1"})
rami = {"main": main}
rami["etl"] = rami["main"]
print("ramo creato senza copie:", rami["etl"] is rami["main"])
# 3) il lavoro avviene sul ramo; main non cambia finche' non fai il merge
rami["etl"] = Commit({**rami["etl"].files, "ordini/2026-11-13.parquet": "h2"}, (main,))
print("main vede il nuovo file:", "ordini/2026-11-13.parquet" in rami["main"].files)
ris, conf = unisci(base_comune(rami["main"], rami["etl"]).files, rami["etl"].files, rami["main"].files)
print("merge:", ris, "conflitti:", conf)
# 4) due rami che cambiano lo stesso file in modo diverso
a = Commit({**main.files, "ordini/2026-11-12.parquet": "h-correzione-A"}, (main,))
b = Commit({**main.files, "ordini/2026-11-12.parquet": "h-correzione-B"}, (main,))
base = base_comune(a, b).files
print("senza strategia:", unisci(base, a.files, b.files))
print("source-wins: ", unisci(base, a.files, b.files, "source-wins"))
# Output:
# base A sorgente A destinazione A -> A
# base A sorgente B destinazione B -> B
# base A sorgente B destinazione C -> conflitto
# base A sorgente A destinazione B -> B
# base A sorgente B destinazione A -> B
# base A sorgente X destinazione X -> X
# base A sorgente B destinazione X -> conflitto
# base A sorgente X destinazione B -> conflitto
# base A sorgente A destinazione X -> X
# base A sorgente X destinazione A -> X
# ramo creato senza copie: True
# main vede il nuovo file: False
# merge: {'ordini/2026-11-12.parquet': 'h1', 'ordini/2026-11-13.parquet': 'h2'} conflitti: []
# senza strategia: ({}, ['ordini/2026-11-12.parquet'])
# source-wins: ({'ordini/2026-11-12.parquet': 'h-correzione-A'}, [])
La funzione unisci è il cuore: se sorgente e destinazione hanno lo stesso contenuto, vince quello; se solo uno dei due differisce dalla base, vince quello che è cambiato; se sono cambiati entrambi in modo diverso, o uno ha modificato e l'altro cancellato, c'è conflitto. La scena finale mostra due rami che correggono lo stesso file in modi diversi: senza strategia il merge si ferma e il file in conflitto non entra nel risultato, mentre con source-wins vince la sorgente. La documentazione prevede source-wins e dest-wins e precisa che la strategia vale per tutti i file in conflitto, senza poter decidere caso per caso.
Due conseguenze pratiche vengono dal fatto che lakeFS è indipendente dal formato: il merge lavora su file interi, e non sa fondere due versioni dello stesso Parquet riga per riga. Se due pipeline riscrivono la stessa partizione, avrai un conflitto, non una fusione. La regola di progetto che ne discende è semplice: ogni pipeline scrive in percorsi propri, per esempio una partizione per giorno, e il merge diventa quasi sempre un'aggiunta.
Dove stanno i dati e dove i metadati
lakeFS non contiene i dati: li lascia dove sono, nello storage degli oggetti, e tiene da parte i metadati. La documentazione descrive due livelli, entrambi da conoscere perché sono ciò che dovrai amministrare:
- i commit committati sono salvati come file SSTable nello stesso object storage, sotto il prefisso
_lakefs/; - repository, rami, tag e le modifiche non committate stanno in un key-value store, per il quale esistono driver per PostgreSQL e DynamoDB, mentre un'implementazione in memoria è offerta solo per sperimentare, senza persistenza.
Il significato operativo è che il database non è un dettaglio: contiene lo stato di repository, rami, tag e modifiche in corso. Trattalo come lo stato principale del servizio. La documentazione descrive un backup dei riferimenti con lo script lakefs-refs.py (comandi dump e restore), che ho letto ma non provato. Non usare lo store in memoria fuori da una prova. In questo ambiente non ho eseguito un server lakeFS; ciò che segue è tratto dalla documentazione.
Il flusso scrivi, controlla, pubblica
Il modo più utile di usare lakeFS in una pipeline è un percorso a tre passi che la documentazione chiama write-audit-publish: scrivi su un ramo, controlla i dati, e solo se il controllo passa fai il merge su main. Il pacchetto Python da usare è lakefs, l'SDK ad alto livello. Il blocco seguente stampa le firme reali dei metodi che usi nel flusso, per non lasciarti a un tutorial che potrebbe essere vecchio.
import inspect
from importlib.metadata import version
import lakefs
def parametri(funzione):
"""Nome e valore predefinito di ogni parametro, senza self e senza **kwargs."""
out = []
for p in inspect.signature(funzione).parameters.values():
if p.name == "self" or p.kind is p.VAR_KEYWORD:
continue
out.append(p.name if p.default is p.empty else f"{p.name}={p.default!r}")
return ", ".join(out)
print("lakefs", version("lakefs"), "| lakefs-sdk", version("lakefs-sdk"))
voci = [(lakefs.Repository, "__init__"), (lakefs.Repository, "branch"),
(lakefs.Branch, "create"), (lakefs.Branch, "commit"), (lakefs.Branch, "merge_into"),
(lakefs.Branch, "revert"), (lakefs.Branch, "transact"), (lakefs.Branch, "delete"),
(lakefs.WriteableObject, "upload")]
for classe, nome in voci:
print(f"{classe.__name__}.{nome}({parametri(getattr(classe, nome))})")
# Output:
# lakefs 0.16.0 | lakefs-sdk 1.88.0
# Repository.__init__(repository_id, client=None)
# Repository.branch(branch_id)
# Branch.create(source_reference, exist_ok=False)
# Branch.commit(message, metadata=None)
# Branch.merge_into(destination_branch)
# Branch.revert(reference, parent_number=0, reference_id=None)
# Branch.transact(commit_message='', commit_metadata=None, delete_branch_on_error=True, tag=None)
# Branch.delete()
# WriteableObject.upload(data, mode='w', pre_sign=None, content_type=None, metadata=None)
Le firme dicono più di una descrizione: per creare un ramo si passa source_reference, il commit richiede il messaggio e accetta un dizionario di metadati, merge_into prende la destinazione, e transact avvolge più operazioni in una transazione su un ramo effimero che viene unito al sorgente solo se tutto riesce. Il flusso seguente è uno schema da adattare, non eseguito: serve un server lakeFS e credenziali. L'SDK le legge da ~/.lakectl.yaml o dalle variabili LAKECTL_*.
# Schema da adattare, non eseguito: richiede un server lakeFS raggiungibile e credenziali.
# Le firme usate qui sono quelle stampate dal blocco precedente.
import duckdb
import lakefs # legge endpoint e chiavi da ~/.lakectl.yaml o dalle variabili LAKECTL_*
repo = lakefs.Repository("analytics")
main = repo.branch("main")
lavoro = repo.branch("etl-2026-11-13").create(source_reference="main") # copia zero: solo un puntatore
# 1) scrivo sul ramo, mai su main
with open("orders_2026-11-13.parquet", "rb") as f:
lavoro.object("orders/2026-11-13/orders.parquet").upload(data=f.read(), mode="wb")
# 2) controllo i dati PRIMA di pubblicarli: DuckDB legge il ramo dal gateway S3 di lakeFS
con = duckdb.connect()
con.execute("INSTALL httpfs; LOAD httpfs;")
righe_nulle = con.execute(
"SELECT count(*) FROM read_parquet('s3://analytics/etl-2026-11-13/orders/2026-11-13/orders.parquet') "
"WHERE customer_id IS NULL").fetchone()[0] # lo schema S3 va configurato come nel blocco SQL
# 3) pubblico oppure scarto
if righe_nulle == 0:
lavoro.commit(message="Ordini del 2026-11-13", metadata={"sorgente": "gestionale", "controllo": "ok"})
lavoro.merge_into(main)
else:
lavoro.delete() # il ramo e le modifiche non committate spariscono
Nello schema il controllo è una sola query, ma può essere qualunque cosa: uno schema, conteggi, tolleranze. Il punto importante è dove succede: sul ramo, prima del merge. Se fallisce, lavoro.delete() elimina il ramo con le sue modifiche non committate e main non è mai stato toccato. Per avere il controllo applicato dal server e non dal tuo script, la documentazione descrive gli hook pre-commit e pre-merge, definiti in un file di azioni YAML: se un controllo fallisce, il merge in main è bloccato. Sono una funzione di governo, quindi verifica nella tua edizione che sia inclusa.
Leggere un ramo con DuckDB
Per interrogare i dati di un ramo con DuckDB, la strada più semplice è il gateway S3 di lakeFS: l'URI ha la forma s3://<repository>/<riferimento>/<percorso>, dove il riferimento è un ramo, un tag o un commit, secondo le espressioni di riferimento descritte nella documentazione. La pagina di integrazione con DuckDB mostra la configurazione e avverte che, passando dal gateway, lakeFS entra nel percorso dei dati e fa da proxy alle operazioni, quindi è meno efficiente del catalogo REST Iceberg che raccomanda come via principale. Il catalogo REST Iceberg compare tra le funzioni dell'edizione Team.
-- Schema da adattare, non eseguito: valori d'esempio dalla pagina DuckDB della documentazione di lakeFS.
INSTALL httpfs;
LOAD httpfs;
SET s3_region = 'us-east-1'; -- con storage non S3 la documentazione indica comunque us-east-1
SET s3_endpoint = 'lakefs.example.com'; -- host (e porta) del server lakeFS, non del bucket
SET s3_access_key_id = '<chiave-lakefs>';
SET s3_secret_access_key = '<segreto-lakefs>';
SET s3_url_style = 'path';
-- SET s3_use_ssl = false; -- solo se il server ascolta in chiaro, per esempio in locale
-- lo schema dell'URI e' s3://<repository>/<riferimento>/<percorso>
SELECT count(*)
FROM parquet_scan('s3://analytics/main/orders/**/*.parquet', HIVE_PARTITIONING = 1);
Le impostazioni sono quelle di una connessione S3 qualunque (vedi l'articolo DuckDB in produzione), con due differenze: l'endpoint è il server lakeFS e non il bucket, e le chiavi sono quelle dell'utente lakeFS. Per rendere riproducibile un'analisi, metti nel percorso l'identificativo di un commit invece del nome del ramo: il ramo si muove, il commit no. Qualunque query di oggi darà così lo stesso risultato fra sei mesi, finché il commit non viene eliminato dalla retention.
Tornare indietro: revert da riga di comando
Se un caricamento sbagliato è già in main, il comando documentato è lakectl branch revert, che registra un nuovo commit che annulla gli effetti del commit indicato. Non riscrive la storia: la aggiunge, e il commit sbagliato resta consultabile. La guida al rollback lo presenta come misura d'emergenza per fermare un errore mentre analizzi la causa. Il file mostra l'intero ciclo con i comandi della pagina di riferimento della CLI; anche questo è uno schema, non eseguito.
# Schema da adattare, non eseguito: i comandi e le opzioni sono quelli della pagina lakectl della documentazione.
lakectl branch create lakefs://analytics/etl-2026-11-13 -s lakefs://analytics/main
lakectl commit lakefs://analytics/etl-2026-11-13 -m "Ordini del 2026-11-13" --meta sorgente=gestionale
lakectl merge lakefs://analytics/etl-2026-11-13 lakefs://analytics/main
# se un caricamento ha portato dati sbagliati in main: annulla gli effetti di quel commit
lakectl log lakefs://analytics/main --amount 5
lakectl branch revert lakefs://analytics/main <id-del-commit-da-annullare>
L'ordine dei comandi è quello di Git: branch create con l'opzione -s per indicare la sorgente, commit con -m e coppie --meta chiave=valore, merge da sorgente a destinazione. Il log serve a trovare l'identificativo del commit da annullare: usa l'opzione --amount per limitare le righe. Scrivere nei metadati del commit il giorno dei dati, la sorgente e l'esito dei controlli ti fa risparmiare il giro della memoria quando devi capire quale commit annullare.
Cancellare davvero: la retention non è automatica
Un punto che chi viene da Git sottovaluta: per impostazione predefinita lakeFS conserva tutti gli oggetti per sempre, ed è ciò che permette di viaggiare nel tempo. Cancellare un file in un ramo non lo toglie dallo storage. La documentazione descrive un job di garbage collection (un programma Spark nella versione standard, mentre gli utenti Enterprise possono usare un programma autonomo) che elimina dallo storage gli oggetti cancellati o sostituiti e scaduti secondo regole di retention che definisci per ramo, più gli oggetti non committati diventati irraggiungibili.
Questo conta se hai obblighi di cancellazione, per esempio una richiesta di eliminazione di dati personali: non basta cancellare e fare commit. Serve una regola di retention adeguata e l'esecuzione del job, e va verificato che l'oggetto non sia raggiungibile da altri rami o commit. È una questione tecnica con conseguenze legali, che non trovi risolta da una riga di codice: portala al tuo responsabile della protezione dei dati.
Dove lakeFS non basta
lakeFS versiona oggetti, non tabelle. Se i tuoi dati sono tabelle Iceberg o Delta, quei formati hanno già snapshot e viaggio nel tempo propri, per tabella; lakeFS aggiunge il versionamento coerente di più tabelle insieme e di file non tabellari, con un solo commit. Il confronto fra i tre formati è nell'articolo Iceberg, Delta Lake e Hudi, l'elaborazione dei file con i DataFrame è in Polars e pandas, con le misure, e una pipeline che li usa con Polars è in DuckDB e Polars: una pipeline lean. Per versionare piccoli insiemi di dati insieme al codice esiste DVC, che lakeFS ha acquisito e che secondo l'annuncio resta sotto Apache 2.0.
Sul costo dell'adozione, due voci da stimare prima di partire: il server e il suo database sono servizi in più da far funzionare e da aggiornare, e ogni accesso dal gateway passa da lì. Per un team piccolo con pochi dataset e una pipeline giornaliera, potrebbe bastare una convenzione di cartelle con date e un controllo prima della pubblicazione; lakeFS si giustifica quando gli errori di pubblicazione costano più della sua gestione.
Che cosa sai fare adesso
Sai valutare lakeFS con la licenza in mano, spiegare perché un ramo non copia dati e quando un merge va in conflitto, impostare il flusso scrivi-controlla-pubblica con l'SDK Python, leggere un ramo o un commit da DuckDB, annullare un caricamento con revert e sapere che cancellare un file non libera lo storage finché non gira la garbage collection. Per inserire questo pezzo in un'architettura completa, l'ultimo articolo della serie è Modern Data Stack: un'architettura minima.
Domande frequenti
lakeFS è ancora open source?
Dalla versione 1.87.0 l'edizione Community è distribuita con la Business Source License 1.1, che non è una licenza open source riconosciuta; il codice è pubblico e ogni versione diventa Apache 2.0 quattro anni dopo la pubblicazione. Le versioni precedenti restano Apache 2.0.
Posso usare lakeFS in produzione nella mia azienda?
Sì, alle condizioni della concessione d'uso: programma non modificato e uso solo interno. Non puoi offrirlo come servizio a terzi né usare in produzione una versione modificata. Per i casi dubbi il fornitore invita a contattarlo.
Quale database richiede lakeFS?
La documentazione descrive un key-value store con driver per PostgreSQL e DynamoDB; esiste anche uno store in memoria, utile solo per sperimentare perché non persiste i dati.
Come si gestisce un conflitto di merge?
Il merge si ferma se lo stesso file è cambiato in modo diverso nei due rami, o modificato da una parte e cancellato dall'altra. Puoi rilanciarlo con la strategia source-wins o dest-wins, che vale per tutti i conflitti, oppure sistemare i rami prima.
Fonti
- lakeFS: Community Edition is Moving to the Business Source License - passaggio da Apache 2.0 a BSL dalla versione 1.87.0, che cosa è consentito, consultata il 2026-11-13
- lakeFS: file LICENSE (Business Source License 1.1) - Licensor, concessione d'uso aggiuntiva, data di conversione e licenza di conversione, consultata il 2026-11-13
- lakeFS documentation: Internals - rami a copia zero, commit immutabili, tabella del merge a tre vie, strategie, metadati e store key-value, consultata il 2026-11-13
- lakeFS documentation: Editions - differenze fra Community, Team ed Enterprise e prezzo del piano Team, consultata il 2026-11-13
- lakeFS documentation: DuckDB - configurazione del gateway S3 e forma dell'URI, consultata il 2026-11-13
- lakeFS documentation: lakectl (CLI reference) - sintassi di branch create, commit, merge, log e branch revert, consultata il 2026-11-13
- lakeFS documentation: Garbage Collection - conservazione predefinita degli oggetti e regole di retention, consultata il 2026-11-13
- lakeFS documentation: Backup and Restore - lo script
lakefs-refs.pyper salvare e ripristinare i riferimenti, consultata il 2026-11-13 - lakeFS documentation: Actions and Hooks - hook pre-commit e pre-merge e file di azioni, consultata il 2026-11-13
- PyPI: lakefs - versione 0.16.0 dell'SDK ad alto livello e licenza Apache-2.0, consultata il 2026-11-13
Il modello giocattolo e il blocco con le firme dell'SDK sono stati eseguiti con Python 3.14.4 e lakefs 0.16.0, due volte con uscita identica. Nessun server lakeFS è stato avviato: gli schemi sul flusso, sul gateway e sulla CLI sono da adattare e non eseguiti, e riportano sintassi lette nella documentazione ufficiale.

Commenti
Caricamento commenti...
Accedi per commentare