CSVReader

Reads a CSV file row by row, as objects keyed by column heading or as raw value arrays.

load.js

const reader = datasource.csvRead("uploads/actuals.csv", 0);

for (const row of reader) {
    cube.set(Number(row.amount), "Sales", row.year, row.month, row.product, "Actual");
}

actuals.csv

year,month,product,amount
2026,Jan,Widgets,1200.50
2026,Jan,Gadgets,830

Constructor

datasource.csvRead datasource.csvRead(fileName, skipLines, ignoreEscapeCharacter, delimiter) CSVReader | null

Opens a CSV file from the filesystem and returns a CSVReader, or null when the file can't be opened.

Parameter	Type	Description
fileName	string	The path of the file, for example "uploads/actuals.csv".
skipLines	number	The number of lines to skip before the heading row. Use 0 when the file starts with its headings.
ignoreEscapeCharacter	boolean	Optional. true to treat backslashes as ordinary characters.
delimiter	string	Optional. The field delimiter. Detected from the file when omitted.

// A file that starts with its headings
const reader = datasource.csvRead("uploads/actuals.csv", 0);

// A file with two title lines above the headings
const reader = datasource.csvRead("uploads/trial_balance.csv", 2);

// A pipe-delimited file
const reader = datasource.csvRead("uploads/extract.txt", 0, false, "|");

Overview

• Headings: when the first row looks like a heading, its values become the property names on each row. Otherwise columns are named column0, column1 and so on.
• Format: the delimiter, quote character and encoding are detected from the file. Override them with the setter methods before the first read.
• Values are strings: convert with Number(...) before writing to a cube or doing arithmetic.
• Looping: for...of is the simplest way to read every row. Use a while (!reader.isEOF()) loop for one row at a time, or when you want arrays from readValues().

for...of

// Each row is an object keyed by column heading
for (const row of reader) {
    console.log(row.product + ": " + row.amount);
}

while + read()

// Same row objects, one call at a time
while (!reader.isEOF()) {
    const row = reader.read();
    console.log(row.product + ": " + row.amount);
}

while + readValues()

// Each row is an array of strings, in column order
while (!reader.isEOF()) {
    const values = reader.readValues();
    console.log(values[2] + ": " + values[3]);
}

Methods

read read() object | null

Returns the next row as an object keyed by column heading, or null at the end of the file. Each for...of iteration yields the same object.

readValues readValues() string[] | null

Returns the next row as an array of strings in column order, or null at the end of the file. Use it for files without headings, or to pick columns by position.

isEOF isEOF() boolean

Returns true once the reader has passed the last row of the file.

close close() optional

Closes the file. Readers close automatically when the process finishes, so only call this to release the file early, such as before renaming or deleting it.

reader.close();
datasource.renameFile("uploads/actuals.csv", "archive/actuals.csv");

setDelimiter setDelimiter(delimiter)

Sets the field delimiter, overriding auto-detection. Call it before the first read.

Parameter	Type	Description
delimiter	string	The delimiter, for example ";" or "|". Pass "\t" or "t" for tab.

getDelimiter getDelimiter() string | null

Returns the delimiter set on the reader, or null when it will be auto-detected.

setQuoteCharacter setQuoteCharacter(quoteCharacter)

Sets the quote character, overriding auto-detection. Call it before the first read.

Parameter	Type	Description
quoteCharacter	string	The quote character, for example "'".

getQuoteCharacter getQuoteCharacter() string | null

Returns the quote character set on the reader, or null when it will be auto-detected.

setCharset setCharset(charset)

Sets the character encoding, overriding auto-detection. Call it before the first read. Unknown encoding names are ignored.

Parameter	Type	Description
charset	string	The encoding name, for example "UTF-8" or "windows-1252".

getCharset getCharset() string

Returns the character encoding used to read the file, either detected or set with setCharset().

setTrimValues setTrimValues(trim)

Turns on trimming of spaces around each value. Call it before the first read.

Parameter	Type	Description
trim	boolean	true to trim spaces around each value.

getTrimValues getTrimValues() boolean

Returns whether spaces around each value are trimmed.

Examples

A file with a title block and semicolons

Skip the title lines with skipLines, then set the format before reading.

load-trial-balance.js

const reader = datasource.csvRead("uploads/trial_balance.txt", 2);
reader.setDelimiter(";");
reader.setTrimValues(true);

for (const row of reader) {
    cube.set(Number(row.debit) - Number(row.credit), "GL", row.account, "Jan", "2026", "Actual");
}

trial_balance.txt

Trial Balance Export
Generated 2026-02-01
account;debit;credit
4000;0.00;15230.50
5000;8120.00;0.00

A file without headings

load-rates.js

const reader = datasource.csvRead("uploads/rates.csv", 0);

while (!reader.isEOF()) {
    const [currency, year, month, rate] = reader.readValues();
    cube.set(Number(rate), "FX Rates", year, month, currency);
}

rates.csv

AUD,2026,Jan,0.65
NZD,2026,Jan,0.60

Add up rows that land on the same cell

const reader = datasource.csvRead("uploads/invoices.csv", 0);

for (const row of reader) {
    cube.increment(Number(row.total), "Revenue", row.customer, row.month, "Actual");
}

Related

• CSVWriter: writes CSV files.