---
id: codecs--csv-encoder-plugin
title: "CSV encoder"
summary: "Encodes records into CSV: one line per record, one column per configured property. The records of a batch (e.g. one Sql query execution, one file read) go into one CSV file, emitted as an in-memory file stream when the batch completes, ready for a file or blob writer."
audience: user
keywords: "input, output, fields, encoding, firstlineisheaders, columnseparator, lineseparator, usequotes, quotecharacters, autoflushtimeout, batchscope"
---
# CSV encoder

Encodes records into CSV: one line per record, one column per configured property. The records of a batch (e.g. one Sql query execution, one file read) go into one CSV file, emitted as an in-memory file stream when the batch completes, ready for a file or blob writer.

## Pins

| Pin | Kind | Types | Description |
|---|---|---|---|
| Input | input | any | Records to encode. |
| Output | output | `Viaducta.Plugins.Files.Types.ViaFileStream` | The CSV content in a memory stream positioned at 0 (`Extension` `.csv`, `Name`, `Size` set). |

## Configuration

| Field | Type | Default | Description |
|---|---|---|---|
| `Fields` | string | | Property names to write, comma-separated, in column order (spaces around names are trimmed). Marked required in the editor; if it is empty anyway, all properties of the input type are written. |
| `Encoding` | dropdown: `UTF8`, `UTF7`, `UTF32`, `ASCII` | `UTF8` | Encoding of the output. |
| `FirstLineIsHeaders` | boolean | `false` | Write a header line with the field names at the top of every file. |
| `ColumnSeparator` | string | `,` | Column separator; escapes like `\t` are allowed. |
| `LineSeparator` | string | `\n` | Line separator with escapes (`\n`, `\r\n`). |
| `UseQuotes` | boolean | `true` | Enclose string values in the quote character. |
| `QuoteCharacters` | string | `"` | Quote character; only the first character is used. Quotes inside values are doubled. |
| `AutoFlushTimeout` | integer (ms, 0-100000) | `0` | Records without a batch only: `0` = one file per record; otherwise the records go into one file, emitted once no record arrived for this time. |
| `BatchScope` | batch scope selector | empty | Which batch goes into one file. Empty = the closest batch producer upstream. A component id of a batch producer upstream = the batches of that producer. `None` = ignore batches (see `AutoFlushTimeout`). |

## Behaviour

- Records in a batch (see `BatchScope`) are encoded into the file of their batch when they arrive. When the whole batch has been processed the file is emitted with the metadata of the last record; it stays in the batch, so batch consumers behind it (Write file, ...) include it before they commit. When the batch failed the file is discarded. File name: the batch label with `.csv` (e.g. the source file name, `<Sql query>-<time>.csv`).
- If encoding a record fails, the batch fails and the rest of its records are dropped.
- Records without a batch (or `BatchScope` `None`): with `AutoFlushTimeout` `0` every record is emitted as a file of its own; otherwise records are collected into one shared file that is emitted once no record arrived for `AutoFlushTimeout` ms. Name: `CSV-<yyyyMMdd-HHmmss>-<sequence>.csv`.
- Values are written with `ToString()`; `null` becomes an empty column. With `UseQuotes`, string values are enclosed in the quote character.

## Notes

- Numbers and dates are formatted with the server culture; format them as strings upstream for a fixed format.
- A file is built in memory; very large batches need a lot of memory.

## Example

```json
{ "Fields": "Id,Name,Price", "ColumnSeparator": ";", "LineSeparator": "\\r\\n", "Encoding": "UTF8", "FirstLineIsHeaders": true }
```

Timer → Table reader → **CSV encoder** → Write file: one CSV per read