CSVJOIN(1)

💖 CSVJOIN(1) — csvkit's little join machine 💖

okay so bestie, welcome to csvjoin, straight outta csvkit 🎀 this is the tool that smushes CSV tables together, and yes it's giving very SQL JOIN energy, no cap.

---

📛 NAME

csvjoin — csvjoin Documentation ✨

---

🌸 DESCRIPTION

Merges two or more CSV tables together using a method analogous to a SQL JOIN operation. By default it performs an inner join, but full outer, left outer, and right outer are also available via flags. Key columns are specified with the -c flag — either a single column that exists in all tables, or a comma-separated list of columns with one corresponding to each. And if the columns flag is not provided? Then the tables get merged "sequentially", meaning they're merged in row order with no filtering at all. Just vibes. 🦋

Here's the whole usage situation, verbatim, because I would never gatekeep:

usage: csvjoin [-h] [-d DELIMITER] [-t] [-q QUOTECHAR] [-u {0,1,2,3}] [-b]
               [-p ESCAPECHAR] [-z FIELD_SIZE_LIMIT] [-e ENCODING] [-L LOCALE]
               [-S] [--blanks] [--null-value NULL_VALUES [NULL_VALUES ...]]
               [--date-format DATE_FORMAT] [--datetime-format DATETIME_FORMAT]
               [-H] [-K SKIP_LINES] [-v] [-l] [--zero] [-V] [-c COLUMNS]
               [--outer] [--left] [--right] [-y SNIFF_LIMIT] [-I]
               [FILE [FILE ...]]

Execute a SQL-like join to merge CSV files on a specified column or columns.

positional arguments:
  FILE                  The CSV files to operate on. If only one is specified,
                        it will be copied to STDOUT.

optional arguments:
  -h, --help            show this help message and exit
  -c COLUMNS, --columns COLUMNS
                        The column name(s) on which to join. Should be either
                        one name (or index) or a comma-separated list with one
                        name (or index) per file, in the same order in which
                        the files were specified. If not specified, the two
                        files will be joined sequentially without matching.
  --outer               Perform a full outer join, rather than the default
                        inner join.
  --left                Perform a left outer join, rather than the default
                        inner join. If more than two files are provided this
                        will be executed as a sequence of left outer joins,
                        starting at the left.
  --right               Perform a right outer join, rather than the default
                        inner join. If more than two files are provided this
                        will be executed as a sequence of right outer joins,
                        starting at the right.
  -y SNIFF_LIMIT, --snifflimit SNIFF_LIMIT
                        Limit CSV dialect sniffing to the specified number of
                        bytes. Specify "0" to disable sniffing entirely, or
                        "-1" to sniff the entire file.
  -I, --no-inference    Disable type inference (and --locale, --date-format,
                        --datetime-format, --no-leading-zeroes) when parsing
                        the input.

---

✨ ARGUMENTS ✨ (the ones this page spells out)

🫶 positional arguments

• FILE — the CSV files you want it to operate on. Pro tip: if you only hand it one, it just copies it straight to STDOUT. Iconic behaviour honestly.

💅 optional arguments

• -h, --help — show this help message and exit. Classic. The "hey what does this do" button. 💖
• -c COLUMNS, --columns COLUMNS — the column name(s) to join on. Should be either one name (or index) or a comma-separated list with one name (or index) per file, in the same order in which the files were specified. If you don't specify it, the files get joined sequentially without matching. no thoughts, just row order.
• --outer — perform a full outer join, rather than the default inner join. everybody's invited to the party. 🎉
• --left — perform a left outer join, rather than the default inner join. And heads up: if more than two files are provided, this gets executed as a sequence of left outer joins, starting at the left. 👑
• --right — perform a right outer join, rather than the default inner join. Same deal: if more than two files are provided, this runs as a sequence of right outer joins, starting at the right. 🌈
• -y SNIFF_LIMIT, --snifflimit SNIFF_LIMIT — limit CSV dialect sniffing to the specified number of bytes. Specify "0" to disable sniffing entirely, or "-1" to sniff the entire file. 🐶 that's the whole spectrum, bestie.
• -I, --no-inference — disable type inference (and --locale, --date-format, --datetime-format, --no-leading-zeroes) when parsing the input. sometimes you just want raw text, and honestly? valid.

⚠️ IMPORTANT bestie, for real: note that the join operation requires reading all files into memory. Don't try this on very large files. like, do not. it will not slay, it will suffer. 😭

🧚 arguments common to all tools

these ones come along for the ride from the shared set — their deets live in the common arguments doc:

• -d DELIMITER
• -t
• -q QUOTECHAR
• -u {0,1,2,3}
• -b
• -p ESCAPECHAR
• -z FIELD_SIZE_LIMIT
• -e ENCODING
• -L LOCALE
• -S
• --blanks
• --null-value NULL_VALUES [NULL_VALUES ...]
• --date-format DATE_FORMAT
• --datetime-format DATETIME_FORMAT
• -H
• -K SKIP_LINES
• -v
• -l
• --zero
• -V

See also: Arguments common to all tools. 👀

---

🌟 EXAMPLES

Join on column 1:

csvjoin -c 1 examples/join_a.csv examples/join_b.csv

Add two empty columns to the right of a CSV:

echo "," | csvjoin examples/dummy.csv -

Add a single column to the right of a CSV:

echo "new-column" | csvjoin examples/dummy.csv -

---

💜 AUTHOR

Christopher Groskopf and contributors 🫶

---

🎀 COPYRIGHT

2016, Christopher Groskopf and James McKinney

---

and that's the whole page, bestie!! this was CSVJOIN(1) from csvkit version 2.2.0, dated Aug 16, 2024 💖 go forth and join your little tables, you absolute main character 👑✨