Combining files

This group merges several loaded CSV/TSV tables into a new one: stack them one below another, join them side by side on a shared column, or compare two versions to see what changed. Every instruction in this group reads existing loaded documents and produces a brand-new document — it never touches the originals.

Prerequisite: the documents you want to combine must already be loaded — each created with Create CSV/TSV file or opened with one of the Reading instructions — and, in general, loaded with headers (named columns), because these instructions match and align rows by column name.

These concepts recur across the instructions in this group; they are explained here once.

• Inputs are documents, referenced by key — not files. You don’t point these instructions at a file on disk; you point them at documents already loaded in the workflow, using their document key (Base/Compare document key, Primary/Secondary document key, or the comma-separated Source document keys). An unloaded key simply contributes no rows.
• Columns are matched by name, ignoring upper/lower case. These instructions expect tables loaded with headers. Rows are aligned and joined by column name; a document loaded without headers (rows are plain lists of values) contributes no named columns and is effectively ignored.
• The result is a new document (Output … fields): the combined table is registered as a separate document — the sources are left unchanged. Output name is the file it will be saved under, Output path is its folder, Output document key names it so later instructions can target it, and Output delimiter decides the extension (a tab saves it as .tsv, anything else as .csv). The result is only produced when at least one of Output name or Output document key is filled in; otherwise the instruction does nothing.
• Case sensitive key: for the joins and the compare, this controls whether the values in the key column are matched exactly (Apple ≠ apple) or treated the same regardless of case. Default is No (case is ignored).
• Dynamic values @name: the text fields (the document keys, column names, Output name, Output path, etc.) accept a saved value — type @ followed by its name and the engine substitutes it at run time.
• Saving a result (Save … count key fields): these instructions save row counts (how many rows were written, added, removed, …). Type a name and the count is stored under it for later instructions to use with @name; leave it empty and nothing is saved.

• Compare Files .csv
• Concatenate Files .csv
• Join Files .csv
• Left Join Files .csv

Compare Files .csv

Compares two versions of a table and writes out only the differences — the rows that were added, removed, or modified between them.

When to use it: to audit what changed between two exports — a yesterday-vs-today snapshot, an original vs an edited file — keyed on a column that uniquely identifies each row.

Parameter	Meaning	Default	Required
Base document key	The original/“before” loaded table (accepts @name)	(empty)	Yes
Compare document key	The “after” loaded table to compare against the base (accepts @name)	(empty)	Yes
Key column	The column that uniquely identifies each row (accepts @name)	(empty)	Yes
Case sensitive	Yes = match the key values exactly; No = ignore upper/lower case	No	No
Output delimiter	Delimiter/extension of the produced document (accepts @name)	,	No
Case sensitive (from variable)	Reads the yes/no value from a saved value	(empty)	No
Output name	File name the new document will be saved under (accepts @name)	(empty)	To save
Output path	Folder the new document will be saved to (accepts @name)	(empty)	To save
Output document key	Names the new document so later instructions can target it (accepts @name)	(empty)	No
Save added count key	Saves the number of added rows	(empty)	No
Save removed count key	Saves the number of removed rows	(empty)	No
Save modified count key	Saves the number of modified rows	(empty)	No

Important behavior: the instruction does nothing unless both Base document key and Compare document key are given. If you fill in neither Output name nor Output document key, the comparison still happens and its counts are still saved — only the result document is not kept. The result table has a leading _Change column tagging each row as Removed, Added, or Modified, followed by all the columns of the base table. A row present in the base but not in the compare is Removed; one present in the compare but not the base is Added; one present in both but with any differing value is Modified. Rows are keyed by Key column (whose matching honors Case sensitive key), while the value-by-value change check is always exact. A tab Output delimiter saves the result as a .tsv.

---

Concatenate Files .csv

Stacks the rows of several loaded tables one below another into a single new document.

When to use it: to append monthly exports, combine split files, or merge tables that share the same columns into one long table.

Parameter	Meaning	Default	Required
Source document keys	The loaded documents to stack, as a comma-separated list of keys, e.g. jan,feb,mar (accepts @name)	(empty)	Yes
Require matching headers	Yes = skip any document whose columns don’t match the first one; No = include every document	Yes	No
Output delimiter	Delimiter/extension of the produced document (accepts @name)	,	No
Require matching headers (from variable)	Reads the yes/no value from a saved value	(empty)	No
Output name	File name the new document will be saved under (accepts @name)	(empty)	To save
Output path	Folder the new document will be saved to (accepts @name)	(empty)	To save
Output document key	Names the new document so later instructions can target it (accepts @name)	(empty)	No
Save count key	Saves the number of rows written	(empty)	No

Important behavior: the instruction does nothing if Source document keys is empty. If you fill in neither Output name nor Output document key, the stacking still happens and Save count key is still saved — only the combined document is not kept. The column layout of the first non-empty document wins — every row in the result is aligned to those columns (extra columns from other documents are dropped, missing ones are left blank). With Require matching headers = Yes, any document whose columns don’t exactly match that first layout is skipped entirely. Empty or unloaded documents are skipped. A tab Output delimiter saves the result as a .tsv.

---

Join Files .csv

Combines two tables side by side by matching a key column — an inner join, so only rows that have a match on both sides are kept.

When to use it: to enrich one table with columns from another — e.g. add customer details to an orders table by matching on a customer ID.

Parameter	Meaning	Default	Required
Primary document key	The main loaded table (accepts @name)	(empty)	Yes
Secondary document key	The table whose columns are added on (accepts @name)	(empty)	Yes
Primary key column	The column in the primary table used to match rows (accepts @name)	(empty)	Yes
Secondary key column	The column in the secondary table used to match rows (accepts @name)	(empty)	Yes
Case sensitive	Yes = match the key values exactly; No = ignore upper/lower case	No	No
Output delimiter	Delimiter/extension of the produced document (accepts @name)	,	No
Case sensitive (from variable)	Reads the yes/no value from a saved value	(empty)	No
Output name	File name the new document will be saved under (accepts @name)	(empty)	To save
Output path	Folder the new document will be saved to (accepts @name)	(empty)	To save
Output document key	Names the new document so later instructions can target it (accepts @name)	(empty)	No
Save count key	Saves the number of rows written	(empty)	No

Important behavior: the instruction does nothing unless both Primary document key and Secondary document key are given. If you fill in neither Output name nor Output document key, the join still happens and Save count key is still saved — only the joined document is not kept. Each result row carries all the primary columns plus the secondary columns, except the secondary key column (it would just duplicate the primary one). A primary row with no match is dropped; if several secondary rows share the same key, the primary row is repeated once per match. A tab Output delimiter saves the result as a .tsv.

---

Left Join Files .csv

Like Join Files, but keeps every row of the primary table — when a primary row has no match, the secondary columns are simply left blank (a left join).

When to use it: to add optional details to a table without losing any rows — e.g. attach a category to each product, keeping products that have no category yet.

Parameter	Meaning	Default	Required
Primary document key	The main loaded table, every row of which is kept (accepts @name)	(empty)	Yes
Secondary document key	The table whose columns are added on (accepts @name)	(empty)	Yes
Primary key column	The column in the primary table used to match rows (accepts @name)	(empty)	Yes
Secondary key column	The column in the secondary table used to match rows (accepts @name)	(empty)	Yes
Case sensitive	Yes = match the key values exactly; No = ignore upper/lower case	No	No
Output delimiter	Delimiter/extension of the produced document (accepts @name)	,	No
Case sensitive (from variable)	Reads the yes/no value from a saved value	(empty)	No
Output name	File name the new document will be saved under (accepts @name)	(empty)	To save
Output path	Folder the new document will be saved to (accepts @name)	(empty)	To save
Output document key	Names the new document so later instructions can target it (accepts @name)	(empty)	No
Save count key	Saves the number of rows written	(empty)	No

Important behavior: same requirements as Join Files — both document keys plus an output target, or the instruction does nothing. The difference is that a primary row with no match is still written, with its secondary columns empty. As with the inner join, the secondary key column is not duplicated, and a primary row that matches several secondary rows is repeated once per match. A tab Output delimiter saves the result as a .tsv.

---