DataFrame.join() în pandas

df.join(other, on=None, how='left', sort=False, validate=None, *, suffixes=('', ''))

Ce face DataFrame.join()

join() este o formă scurtă de merge care potrivește rândurile după index. Dacă ai două tabele indexate după numele elevului (notele și absențele), note.join(absente) le pune unul lângă altul.

Implicit how="left": rămân toate rândurile din tabelul pe care apelezi metoda. Dacă cele două tabele au coloane cu același nume, trebuie să dai sufixe cu suffixes=("_stanga", "_dreapta"), altfel primești eroare. În pandas 3.1 acest parametru înlocuiește perechea veche lsuffix/rsuffix, care este acum depreciată și afișează un avertisment.

Cu on="coloana", cheia din stânga poate fi o coloană obișnuită, care se potrivește cu indexul tabelului din dreapta. Pentru chei care sunt coloane în ambele tabele, merge e mai potrivit.

Parametri

Parametru	Descriere
other	Tabelul (sau seria cu nume, ori o listă de tabele) de adăugat. Se potrivește după indexul lui.
on	O coloană din tabelul din stânga folosită în locul indexului, potrivită cu indexul lui other.
how	"left" (implicit), "right", "inner", "outer" sau "cross".
suffixes	Perechea de sufixe pentru coloanele cu același nume, din stânga și din dreapta (pandas 3.1+). None în loc de text lasă numele neschimbat pe acea parte. Obligatoriu dacă există nume comune.
lsuffix, rsuffix	Forma veche a lui suffixes, depreciată în pandas 3.1. Merge încă, dar afișează Pandas4Warning; pe versiunile mai vechi de 3.1 este singura variantă.
sort	Cu True sortează rezultatul după cheie.
validate	Verifică relația ("one_to_one", "many_to_one" etc.), ca la merge.

Ce returnează

Un DataFrame nou, cu coloanele ambelor tabele.

Exemple

Exemplul 1: Note și absențe după numele elevului

Ambele tabele au numele elevului ca index. Radu nu apare la absențe, deci primește NaN; Elena nu are notă, deci nu apare deloc (how="left").

import pandas as pd

note = pd.DataFrame({"nota": [9, 7, 10]}, index=["Ana", "Mihai", "Radu"])
absente = pd.DataFrame({"absente": [2, 5, 1]}, index=["Ana", "Mihai", "Elena"])

print(note.join(absente))

Rezultat

       nota  absente
Ana       9      2.0
Mihai     7      5.0
Radu     10      NaN

Exemplul 2: Coloane cu același nume: suffixes

Ambele tabele au coloana nota, deci sufixele sunt obligatorii (fără ele primești ValueError). Cu how="inner" rămân doar elevii din ambele tabele.

import pandas as pd

sem1 = pd.DataFrame({"nota": [9, 7, 10]}, index=["Ana", "Mihai", "Radu"])
sem2 = pd.DataFrame({"nota": [10, 8]}, index=["Ana", "Mihai"])

print(sem1.join(sem2, how="inner", suffixes=("_sem1", "_sem2")))

Rezultat

       nota_sem1  nota_sem2
Ana            9         10
Mihai          7          8

Exemplul 3: Coloană din stânga cu indexul din dreapta (on)

Tabelul de orașe e indexat după cod. Cu on="cod_oras", codul fiecărui client se caută în indexul tabelului de orașe.

import pandas as pd

clienti = pd.DataFrame({
    "nume": ["Ana", "Mihai", "Ioana"],
    "cod_oras": ["IS", "CJ", "IS"],
})
orase = pd.DataFrame({"oras": ["Iași", "Cluj"]}, index=["IS", "CJ"])

print(clienti.join(orase, on="cod_oras"))

Rezultat

    nume cod_oras  oras
0    Ana       IS  Iași
1  Mihai       CJ  Cluj
2  Ioana       IS  Iași

Greșeli frecvente

• Apelezi join pe două tabele cu coloane comune fără sufixe și primești ValueError: columns overlap but no suffix specified. Adaugă suffixes=("_1", "_2"); codul vechi cu lsuffix/rsuffix afișează în pandas 3.1 un avertisment de depreciere.
• Aștepți ca join să potrivească după o coloană din ambele tabele: el folosește indexul tabelului din dreapta. Fie setezi indexul cu set_index(), fie folosești merge(on=...).
• Uiți că implicit join este how="left", pe când merge este how="inner"; aceleași date dau un număr diferit de rânduri.

Comenzi înrudite

• pd.merge(): Unește două tabele după o coloană comună (de exemplu id-ul clientului), ca un JOIN din SQL: inner, left, right sau outer.
• pd.concat(): Lipește mai multe tabele unul sub altul (rânduri) sau unul lângă altul (coloane), de exemplu vânzările din mai multe luni.
• DataFrame.set_index() / reset_index(): set_index face dintr-o coloană indexul rândurilor; reset_index mută indexul înapoi într-o coloană sau îl renumerotează.