# CSV

Read CSV into rows, or write CSV from data.

## Do things in CSV

Add a **CSV** step and choose an **Operation**. Choose the row to see the fields of each.

- [Convert CSV](https://docs.gorunner.io/apps/csv#fields-f-convert): Parse (CSV → rows) · Generate (rows → CSV)

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

**What changed in version 2?**

New steps use version 2.0.0. A step made before keeps 1.0.0 and works as it always has. The step’s panel shows its version at the top right. On an older step it reads **v1.0.0 · 2.0.0 available**: press it to choose the version.

In 2.0.0: A blank header cell becomes `column_N`, after its position. When rows arrive as JSON text, the columns keep the order they were written in. In version 1.0.0, a blank header is an empty key and columns are sorted.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, CSV is `pieceId: "csv"` with `actionId: "convert"`, set by `operation`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It computes from its inputs only (`pure`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### CSV › Convert CSV

Parse CSV text to rows, or generate CSV from an array of objects.

### Parse (CSV → rows)

- **CSV Source · Optional**: Where the CSV comes from: text you paste or map in, or a .csv file, uploaded here or produced by an earlier step (an HTTP download, an email attachment, an unzipped entry). Options: Paste CSV text, Use a CSV file. Default: Paste CSV text.
- **CSV File · Required**: Upload a .csv, or switch to an expression to use a file from an earlier step (such as {{steps.download.result}}). Shows when **CSV Source** is **Use a CSV file**.
- **CSV Text · Required**: Paste the CSV content to read, such as name,age then a new line with Ann,30. Shows when **CSV Source** isn’t **Use a CSV file**.
- **Delimiter · Optional**: Field separator. Use \t for tab. Default:,.
- **First Row Is Header · Optional**: Turn on if the first line names the columns; those names become each row's field names. On by default.
- **Trim Spaces · Optional**: Trim leading whitespace from each field. Off by default.
- **Tolerate Bad Quotes · Optional**: Allow bare or unbalanced double-quotes inside fields instead of erroring. Off by default.
- **Skip Rows · Optional**: Number of leading data rows to skip. Default: 0.
- **Max Rows · Optional**: Limit number of rows returned (0 = all). Default: 0.

### Generate (rows → CSV)

- **Rows · Required**: Array of objects to serialize. You can also pass a reading step's whole result (such as {{steps.read_sheet.result}}), and its column order is then reused.
- **Column Order · Optional**: Optional list of column names in the order you want them, such as ["name","score","city"] or {{steps.parse_csv.headers}}. Columns you don't list are added after the ones you do, so nothing is dropped.
- **Delimiter · Optional**: Field separator. Use \t for tab. Default:,.
- **Flatten Nested Objects · Optional**: Expand nested objects into dot-notation columns (such as address.city). When off, nested values are JSON-encoded into one cell. On by default.
- **Quoting · Optional**: Choose whether to wrap every value in quotes, or only values that need it. Options: Minimal (only when needed), Quote all fields. Default: Minimal (only when needed).
- **Include Header Row · Optional**: Turn on to add a first line with the column names above the data rows. On by default.
- **Also Output A File · Optional**: Turn on to also emit a downloadable .csv file alongside the text, ready to attach to an email, upload, or zip. `result` still carries the text either way. Off by default.
- **File Name · Optional**: Name for the generated file. Default: data.csv. Shows when **Also Output A File** is on.
- **Protect Against Spreadsheet Formulas · Optional**: Turn on when the file will be opened in Excel, Google Sheets or LibreOffice and holds text other people wrote (form answers, emails). A value starting with = + - or @ is then written with a leading apostrophe, so it shows as text instead of running as a formula. Numbers are left alone. Leave off when another program reads the CSV: to it, the apostrophe is part of the value. Off by default.

Source: https://docs.gorunner.io/apps/csv