csv on Grafana Labs

parse( file, [options] )

Mon, 21 Sep 2026 15:16:28 +0000

parse( file, [options] )

The csv.parse function parses an entire CSV file at once and returns a promise that resolves to a SharedArray instance. This function uses Go-based processing, which results in faster parsing and lower memory usage compared to JavaScript alternatives. It’s ideal for scenarios where performance is a priority, and the entire CSV file can be loaded into memory.

Parameters

Parameter	Type	Description
file	fs.File	A file instance opened using the `fs.open` function.
options	Options	An optional parameter object to customize the parsing behavior.

Returns

A promise resolving to a SharedArray instance, where each element is an array representing a CSV record, and each sub-element is a field from that record.

Examples

Basic Usage

import { open } from 'k6/experimental/fs';
import csv from 'k6/experimental/csv';
import { scenario } from 'k6/execution';

export const options = {
  iterations: 10,
};

const file = await open('data.csv');

// The `csv.parse` function consumes the entire file at once and returns
// the parsed records as a `SharedArray` object.
const csvRecords = await csv.parse(file);

export default async function () {
  // `csvRecords` is a `SharedArray`. Each element is a record from the CSV file, represented as an array
  // where each element is a field from the CSV record.
  //
  // `csvRecords[scenario.iterationInTest]` gives the record for the current iteration.
  console.log(csvRecords[scenario.iterationInTest]);
}

Using `asObjects`

The asObjects option parses the CSV file into an array of objects. The object keys are the column names from the CSV file, and the values are the field values from the CSV record. Note that the first line of the CSV file is skipped, as it is assumed to contain the column names (header row).

import { open } from 'k6/experimental/fs';
import csv from 'k6/experimental/csv';
import { scenario } from 'k6/execution';

export const options = {
  iterations: 3,
};

const file = await open('data.csv');
const csvRecords = await csv.parse(file, { asObjects: true });

export default function () {
  // Will print the record for the current iteration as an object.
  //
  // For example, given the following CSV file:
  //
  // firstname,lastname
  // francois,mitterand
  // helmut,kohl
  // pierre,mendes-france
  //
  // The test will print:
  //
  // { firstname: 'francois', lastname: 'mitterand' }
  // { firstname: 'helmut', lastname: 'kohl' }
  // { firstname: 'pierre', lastname: 'mendes-france' }
  console.log(csvRecords[scenario.iterationInTest]);
}

Notes on Usage

Memory considerations: csv.parse loads the entire CSV file into memory at once, which may lead to increased memory usage and startup time for very large files.
Shared memory usage: The SharedArray returned by csv.parse is shared among all Virtual Users (VUs), reducing memory overhead when multiple VUs access the same data.

Parser

Mon, 21 Sep 2026 15:16:28 +0000

Parser

The csv.Parser class provides a streaming parser that reads CSV files line-by-line, offering fine-grained control over the parsing process and minimizing memory consumption. It’s well-suited for scenarios where memory efficiency is crucial or when you need to process large CSV files without loading the entire file into memory.

Constructor

Parameter	Type	Description
file	fs.File	A file instance opened using the fs.open function.
options	Options	An optional parameter object to customize the parsing behavior. Options can include a delimiter (string).

Methods

Name	Description
`next()`	Reads the next line from the CSV file and returns a promise that resolves to an iterator-like object.

Returns

A promise resolving to an object with the following properties:

Property	Type	Description
done	boolean	Indicates whether there are more rows to read (false) or the end of the file has been reached (true).
value	string[]	Contains the fields of the CSV record as an array of strings. If done is true, value is undefined.

Example

Basic Usage

import { open } from 'k6/experimental/fs';
import csv from 'k6/experimental/csv';

export const options = {
  iterations: 10,
};

const file = await open('data.csv');
const parser = new csv.Parser(file, { skipFirstLine: true });

export default async function () {
  // The `next` method attempts to read the next row from the CSV file.
  //
  // It returns an iterator-like object with a `done` property that indicates whether
  // there are more rows to read, and a `value` property that contains the row fields
  // as an array.
  const { done, value } = await parser.next();
  if (done) {
    throw new Error('No more rows to read');
  }

  // We expect the `value` property to be an array of strings, where each string is a field
  // from the CSV record.
  console.log(done, value);
}

Using `asObjects`

import { open } from 'k6/experimental/fs';
import csv from 'k6/experimental/csv';
import { scenario } from 'k6/execution';

export const options = {
  iterations: 3,
};

const file = await open('data.csv');
const parser = new csv.Parser(file, { asObjects: true });

export default async function () {
  // Will print the record for the current iteration as an object.
  //
  // For example, given the following CSV file:
  //
  // firstname,lastname
  // francois,mitterand
  // helmut,kohl
  // pierre,mendes-france
  //
  // The test will print:
  //
  // { firstname: 'francois', lastname: 'mitterand' }
  // { firstname: 'helmut', lastname: 'kohl' }
  // { firstname: 'pierre', lastname: 'mendes-france' }
  const { done, value } = await parser.next();
  if (done) {
    throw new Error('No more rows to read');
  }

  console.log(value);
}

Notes on usage

Memory efficiency: Since csv.Parser reads the file line-by-line, it keeps memory usage low and avoids loading the entire set of records into memory. This is particularly useful for large CSV files.
Streaming control: The streaming approach provides more control over how records are processed, which can be beneficial for complex data handling requirements.

Options

Mon, 21 Sep 2026 15:16:28 +0000

Options

The Options object describes the configuration available for the operation of parsing CSV files using the csv.parse function and the csv.Parser class.

Properties

Property	Type	Description
delimiter	string	The character used to separate fields in the CSV file. Default is `','`.
asObjects	boolean	Whether to parse the CSV file’s lines as JavaScript objects. If it is `false`, then they are parsed as arrays. Default is `false`.
skipFirstLine	boolean	Whether to skip the first line of the CSV file. Default is `false`.
fromLine	(optional) number	The line number from which to start reading the CSV file. Default is `0`.
toLine	(optional) number	The line number at which to stop reading the CSV file. If the option is not set, then read until the end.

asObjects

When asObjects is set to true, parsing operations over the CSV file will return an array of objects. The object keys are the column names from the CSV file, as inferred from the first line of the file, and the values are the field values from the CSV record. Note that the first line of the CSV file is skipped, as it is assumed to contain the column names (header row).

As a result, the following CSV file:

name,age
John,30
Jane,25

Will be parsed into the following array of objects:

[
  { "name": "John", "age": "30" },
  { "name": "Jane", "age": "25" }
]

Example

import { open } from 'k6/experimental/fs';
import csv from 'k6/experimental/csv';

const file = await open('data.csv');
const parser = new csv.Parser(file, {
  delimiter: ',',
  skipFirstLine: true,
  fromLine: 2,
  toLine: 8,
});

export default async function () {
  // The `next` method attempts to read the next row from the CSV file.
  //
  // It returns an iterator-like object with a `done` property that indicates whether
  // there are more rows to read, and a `value` property that contains the row fields
  // as an array.
  const { done, value } = await parser.next();
  if (done) {
    throw new Error('No more rows to read');
  }

  // We expect the `value` property to be an array of strings, where each string is a field
  // from the CSV record.
  console.log(done, value);
}

csv on Grafana Labs

parse( file, [options] )

parse( file, [options] )

Parameters

Returns

Examples

Basic Usage

Using asObjects

Notes on Usage

Parser

Parser

Constructor

Methods

Returns

Example

Basic Usage

Using asObjects

Notes on usage

Options

Options

Properties

asObjects

Example

Using `asObjects`

Using `asObjects`