Vai al contenuto

Join con xan: casi base, fuzzy, regex e URL

Questa pagina mostra i casi principali di join con esempi minimi.

Questa guida è scritta per il comportamento di xan 0.56.0 o superiore:

  • join classici con xan join;
  • join fuzzy/regex/url con xan fuzzy-join (-r per regex, -u per URL prefix).

File di esempio (download raw)

Per eseguire i comandi così come sono scritti sotto, posizionati nella cartella:

cd docs/xan/risorse/join

Join standard (xan join)

Sintassi base:

xan join [opzioni] <campi_sx> <file_sx.csv> <campi_dx> <file_dx.csv>

Parametri chiave:

  • <campi_sx>: una o più colonne chiave del file di sinistra (es. id oppure più campi separati da virgola anno,comune);
  • <file_sx.csv>: CSV di sinistra;
  • <campi_dx>: una o più colonne chiave del file di destra, nello stesso ordine di <campi_sx>;
  • <file_dx.csv>: CSV di destra.

Regola pratica:

  • puoi fare join su un campo (id);
  • puoi fare join su più campi (anno,comune), ma il numero dei campi deve coincidere a sinistra e a destra.

Esempio multi-colonna:

dati_a.csv

anno,comune,valore_a
2024,Roma,10
2024,Milano,20
2025,Roma,30

dati_b.csv

anno,comune,valore_b
2024,Roma,100
2025,Roma,300
2025,Torino,400

xan join anno,comune dati_a.csv anno,comune dati_b.csv

Output (estratto):

anno,comune,valore_a,valore_b
2024,Roma,10,100
2025,Roma,30,300

Input usati negli esempi:

persone.csv

id,nome,citta
1,Ada,Roma
2,Luca,Milano
3,Sara,Torino

ordini.csv

id,ordine,valore
1,Penna,5
2,Taccuino,8
4,Zaino,35

Inner join (default)

xan join id persone.csv id ordini.csv

Output (estratto):

id,nome,citta,ordine,valore
1,Ada,Roma,Penna,5
2,Luca,Milano,Taccuino,8

Left join

xan join --left id persone.csv id ordini.csv

Output (estratto):

id,nome,citta,ordine,valore
1,Ada,Roma,Penna,5
2,Luca,Milano,Taccuino,8
3,Sara,Torino,,

Right join

xan join --right id persone.csv id ordini.csv

Output (estratto):

nome,citta,id,ordine,valore
Ada,Roma,1,Penna,5
Luca,Milano,2,Taccuino,8
,,4,Zaino,35

Full join

xan join --full id persone.csv id ordini.csv

Output (estratto):

id,nome,citta,ordine,valore
1,Ada,Roma,Penna,5
2,Luca,Milano,Taccuino,8
,,,Zaino,35
3,Sara,Torino,,

Cross join

Input usati:

lettere.csv

lettera
A
B

numeri.csv

numero
1
2

xan join --cross lettere.csv numeri.csv

Output:

lettera,numero
A,1
A,2
B,1
B,2

Fuzzy join (substring)

Esempio classico: hai una lista di parole/etichette e vuoi agganciare i testi dove compaiono.

Sintassi usata:

xan fuzzy-join [opzioni] <colonne_testo> <file_testi.csv> <colonna_pattern> <file_pattern.csv>

Parametri chiave:

  • -i: confronto case-insensitive (ignora maiuscole/minuscole);
  • --left: mantiene tutte le righe del file testi anche quando non c'è match;
  • <colonne_testo>: una o più colonne in cui cercare (qui testo, ma puoi usare anche titolo,testo);
  • <file_testi.csv>: file dove cercare (qui testi.csv);
  • <colonna_pattern>: colonna con le stringhe/pattern da cercare (qui needle);
  • <file_pattern.csv>: file che contiene i pattern (qui pattern_fuzzy.csv).

Input usati:

testi.csv

id,testo
1,"Il Comune di Roma annuncia nuovi cantieri sulla mobilità urbana."
2,"Bando scuola digitale per laboratori e formazione docenti a Milano."
3,"Nuovo parco urbano con 300 alberi nel quartiere nord."

pattern_fuzzy.csv

tema,needle
scuola,scuola
mobilita,mobilita
verde,parco

xan fuzzy-join -i testo testi.csv needle pattern_fuzzy.csv

Lettura rapida del comando:

  • cerca in testo (dentro testi.csv) i valori di needle (dentro pattern_fuzzy.csv);
  • con -i trova match anche se cambia il maiuscolo/minuscolo.

Output (estratto):

id,testo,tema,needle
2,Bando scuola digitale per laboratori e formazione docenti a Milano.,scuola,scuola
3,Nuovo parco urbano con 300 alberi nel quartiere nord.,verde,parco

Versione left (mantiene tutte le righe dei testi):

xan fuzzy-join -i --left testo testi.csv needle pattern_fuzzy.csv

Differenza rispetto al comando precedente:

  • con --left ottieni anche le righe senza match, con colonne pattern vuote.

Output (estratto):

id,testo,tema,needle
1,Il Comune di Roma annuncia nuovi cantieri sulla mobilità urbana.,,
2,Bando scuola digitale per laboratori e formazione docenti a Milano.,scuola,scuola
3,Nuovo parco urbano con 300 alberi nel quartiere nord.,verde,parco

Regex join

Sintassi usata:

xan fuzzy-join -r [opzioni] <colonne_testo> <file_testi.csv> <colonna_regex> <file_regex.csv>

Parametri chiave:

  • -r: attiva il matching via espressioni regolari;
  • -i: rende il matching case-insensitive;
  • <colonne_testo>: una o più colonne in cui cercare (qui testo, ma puoi usare anche titolo,testo);
  • <file_testi.csv>: file da analizzare (qui testi.csv);
  • <colonna_regex>: colonna con i pattern regex (qui pattern);
  • <file_regex.csv>: file che contiene i regex pattern (qui pattern.csv).

Input aggiuntivo usato:

pattern.csv

tema,pattern
scuola,scuola
mobilita,mobilit[aà]
verde,parco|alberi

xan fuzzy-join -r -i testo testi.csv pattern pattern.csv

Lettura rapida del comando:

  • cerca in testo i pattern regex definiti nella colonna pattern;
  • con -r interpreta i pattern come regex, non come semplice sottostringa.

Output (estratto):

id,testo,tema,pattern
1,Il Comune di Roma annuncia nuovi cantieri sulla mobilità urbana.,mobilita,mobilit[aà]
2,Bando scuola digitale per laboratori e formazione docenti a Milano.,scuola,scuola
3,Nuovo parco urbano con 300 alberi nel quartiere nord.,verde,parco|alberi

Quando usarlo:

  • hai una tabella di pattern (keyword o regex);
  • vuoi etichettare automaticamente testi con tema/categoria.

URL join

Sintassi usata:

xan fuzzy-join -u [opzioni] <colonne_url> <file_link.csv> <colonna_prefisso> <file_sorgenti.csv>

Parametri chiave:

  • -u: attiva il matching per prefisso URL;
  • -S: semplifica gli URL prima del confronto (schema, www, ecc.);
  • <colonne_url>: una o più colonne URL da classificare (qui link, ma puoi indicare più colonne se servono);
  • <file_link.csv>: file con gli URL completi (qui link.csv);
  • <colonna_prefisso>: colonna con i prefissi/domini da usare come riferimento (qui url);
  • <file_sorgenti.csv>: file con la mappatura sorgenti (qui sorgenti_url.csv).

Input usati:

link.csv

link
https://www.comune.roma.it/notizie/mobilita
https://dati.regione.lombardia.it/dataset/trasporti
https://example.org/post/1

sorgenti_url.csv

fonte,url
comune-roma,comune.roma.it
regione-lombardia,dati.regione.lombardia.it

xan fuzzy-join -u -S link link.csv url sorgenti_url.csv

Lettura rapida del comando:

  • confronta ogni valore di link con i prefissi presenti in url;
  • con -S aumenta i match utili anche se gli URL hanno forme diverse.

Output (estratto):

link,fonte,url
https://www.comune.roma.it/notizie/mobilita,comune-roma,comune.roma.it
https://dati.regione.lombardia.it/dataset/trasporti,regione-lombardia,dati.regione.lombardia.it

Quando usarlo:

  • devi attribuire URL completi a domini/prefissi noti;
  • vuoi arricchire rapidamente liste di link con fonte/editore/categoria.