ClickHouse ha rilasciato @clickhouse/rowbinary, un reader e writer Node.js per i formati RowBinary, RowBinaryWithNames e RowBinaryWithNamesAndTypes. La novita’ non e’ solo la libreria in se’, ma il modo in cui viene distribuita: oltre a poterla importare e chiamare come qualsiasi altra dipendenza, il pacchetto include una Agent Skill. Puntando un coding agent al file SKILL.md incluso, invece di chiamare la libreria l’agente la legge e scrive un parser specializzato per i tipi esatti delle colonne della tua query. Questi parser generati girano da 1,5 a 3,4 volte piu’ veloci rispetto al comporre le funzioni della libreria in un loop, costano circa 0,20 dollari a generazione ed evitano i bug di corruzione silenziosa dei dati che i modelli producono quando scrivono decoder binari a memoria.
Il problema che risolve
RowBinary e’ uno dei modi piu’ efficienti per estrarre dati da ClickHouse, ma anche uno dei piu’ scomodi da consumare da JavaScript. Il formato e’ semplice (primitive little-endian, varint LEB128, nessun overhead per riga), ma il lato reader e’ doloroso: ogni tipo foglia ha il suo pattern di lettura, e Nullable, Array, Map, Tuple e LowCardinality si annidano arbitrariamente. Molte applicazioni ripiegano sui formati JSON, che pero’ costano CPU e arrotondano silenziosamente i UInt64 oltre Number.MAX_SAFE_INTEGER a float64. Chi adotta RowBinary finisce con un parser generico dispatchato per tipo a runtime: facile da mantenere, difficile da rendere veloce, perche’ ogni cella paga un dispatch e l’inliner di V8 si arrende sui call site megamorfici. Cio’ che serve ad alto QPS e’ un parser monomorfizzato sulla query specifica.
Libreria come riferimento, non come API
Il pacchetto ha due strati. Il primo e’ una libreria di primitive di lettura tipo-specifiche, scritte per essere monomorfizzabili e quindi inlineabili senza sconfiggere l’ottimizzatore V8; e’ perfettamente usabile da sola chiamando parseRowBinary(...). Il secondo strato e’ il SKILL.md, che invece di descrivere come chiamare l’API insegna a un coding agent la policy per assemblare le primitive in un parser su misura. Su uno schema di ordini con colonne tutte a larghezza fissa, l’agente si accorge del pattern ed emette un parser con un solo bounds check per l’intera riga da 26 byte, letture a offset costanti e un formatter UUID basato su tabella: output byte-identico alla versione composta ma 3,41x piu’ veloce.
Numeri e affidabilita’
Nei benchmark su 50.000 righe per schema, RowBinary batte il percorso JSON corretto di 3,3x su uno schema finanziario con interi larghi su Apple M4 Max e di 2,5x su AMD EPYC 7763. Il parser generato dall’agente batte poi il reader composto di un ulteriore 1,55x (ledger finanziario), 2,46x (telemetria IoT) e 3,41x (ordini). La generazione costa circa 0,20 dollari a parser con Claude Sonnet 4.6 usando il prompt cache. Il punto piu’ importante, pero’, riguarda la correttezza: chiesto di scrivere il decoder UUID a memoria, Sonnet 4.6 ha sbagliato l’ordine dei byte in 3 run su 5, producendo stringhe plausibili ma corrotte; con la skill caricata ogni run e’ corretto per costruzione, perche’ il parser generato e’ una ricombinazione delle primitive ufficiali, testate e revisionate.
- Il parser generato e’ codice normale: un umano lo committa, lo revisiona e lo testa come qualsiasi altro modulo, e la skill e’ un file markdown auditabile.
- Al posto di un compilatore di codegen con la sua matrice di flag, la personalizzazione diventa una conversazione con un modello che ha letto la tua libreria.
- La skill conosce i propri limiti: su schemi ricchi di stringhe consiglia di non usare RowBinary, dove i formati JSON compatti vincono.
Fonte: @clickhouse/rowbinary: when your library is also a parser compiler — https://clickhouse.com/blog/clickhouse-rowbinary-library-parser-compiler
Hai qualcosa da aggiungere? Unisciti alla discussione.