---
title: CSV collector
slug: reference/csv-collector
docTags: 
createdAt: 2025-09-10T15:45:05.684Z
---

The collector settings are used by the collector to successfully parse CSV files.

## Basic settings

### Delimiter

**Description**: The delimiter of the csv file.
**Required**: yes

### CSVHeaderRows

**Description**: The number of header rows at the top of the csv file. Those rows are skipped when parsing the file. Set to 0 if the file has no header.
**Required**: yes
**Default**: 0

### TimestampColumns

**Description**: Indices of the columns holding the timestamp, starting from 0. Multiple indices can be configured using semicolon separated values, in which case their values are concatenated into one timestamp.
**Required**: yes
**Default**: 0

:::hint{type="warning"}
These settings were called `CSVHeader` (a boolean) and `TimestampColumn` (a single index) before collector version 6.0.0. A collector upgraded from an earlier version has its old values converted automatically.
:::

### TimestampLayout

**Description**: The layout of the timestamp of the measurements, default RFC3339 will be used. More info: [https://pkg.go.dev/time#Layout](https://pkg.go.dev/time#Layout)
**Required**: no

For epoch timestamps one of the following keywords can be used instead of a Go layout: `UNIX` (seconds), `UNIXMILLIS` (milliseconds), `UNIXMICROS` (microseconds) or `UNIXNANOS` (nanoseconds).

### StatusColumn

**Description**: Index of column holding the status (starts from 0)
**Required**: no

### TrimString

**Description**: The string to trim (leading and trailing) from the csv cells used (values, mappings, status, …)
**Required**: no
**Default**: a space and a double quote, so cells are trimmed of both out of the box. Clearing the field is not the same as leaving it at the default.

### BasePath

**Description**: Base directory, upon which the default `incoming`, `processed` and `error` directory are constructed.
**Required**: yes
**Example**: c:\plantdata\\

### IncomingDirectoryPath

**Description**: Override for the directory that needs to be monitored by the CSV collector.
**Required**: no
**Example**: c:\plantdata\incoming

### ProcessedDirectoryPath

**Description**: Override for the directory in which processed files will be put. Processed files are files which had at least one measurement sent to Influx.
**Required**: no
**Example**: c:\plantdata\processed

Processed files are files which had at least one measurement sent to Influx.

:::hint{type="info"}
When a CSV measurement name is not found in the measurements configuration, the file will still be marked as processed successfully.
:::

### ErrorDirectoryPath

**Description**: Override for the directory in which files that contained an error will be put. Invalid CSV files will be stored here.
**Required**: no
**Example**: c:\plantdata\failed

### FileMask

**Description**: File mask of the files to use.
**Required**: yes

The file mask for which the collector will monitor files.

## Advanced settings

### ProcessInterval

**Description**: The interval in milliseconds at which the incoming directory is scanned for files matching `FileMask`.
**Required**: no
**Default**: 10000

### ProcessDelay

**Description**: Delay in milliseconds for processing new files after the were detected
**Required**: no
**Default**: 3000

### StartupDelay

**Description**: Initial delay for checking the incoming directory in milliseconds
**Required**: no
**Default**: 9000

### ProcessedMaxAge

**Description**: The maximum time in minutes to keep processed files. 0 will keep the files indefinitely
**Required**: no
**Default**: 43200

### FailedMaxAge

**Description**: The maximum time in minutes to keep failed files. 0 will keep the files indefinitely
**Required**: no
**Default**: 129600

### SourceTimezone

**Description**: The timezone for the data points coming from the source device can be overwritten using this setting. Available timezones can be found here: [https://en.wikipedia.org/wiki/List\\\_of\\\_tz\\\_database\\\_time\\\_zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
**Required**: no

### Locale

**Description**: The locale used to parse numbers, for example `nl-BE` for files that use a comma as the decimal separator. Leave empty to parse numbers without a locale.
**Required**: no
**Default**: empty

## Measurement settings

The Measurement Settings section configures how CSV data is interpreted and mapped into measurements. This includes defining how each column in the CSV file is used, setting up filters for data inclusion, and specifying data quality indicators.

### ValueColumn

**Description**: Column of the value in the csv file for this measurement.
**Required**: yes
**Example**: 6

### Filter

**Description**: Filter to parse only the rows that match the filter. The filter is a JSON object where the key is the column index (as a string) and the value is the value to match. If multiple values in the same column should be matched, separate them with a semicolon.
**Required**: no
**Default**: \{}, which matches every record
**Details**:

- **Key**: CSV column index as a string.
- **Value**: Names used for mapping, separated by semicolons if multiple.

**Example**:
In the following example, the filter will only parse rows where the value of the first column is `Example value` **and** the value of the second column is `match with this` or `also match with this`. Every column in the filter must match; only the semicolon separated values within one column are alternatives.

```json
{
  "0": "Example value",
  "1": "match with this;also match with this"
}
```

Checkout the data collection methods section for more information.

### FilterByRegularExpression

**Description**: When enabled, each value in `Filter` is compiled as a regular expression instead of a list of exact values. Backslashes have to be doubled.
**Required**: no
**Default**: false

### TimestampLayout

**Description**: The layout of the timestamp, defaults to the TimestampLayout setting on the collector. More info: [https://pkg.go.dev/time#Layout](https://pkg.go.dev/time#Layout)
**Required**: no

For epoch timestamps one of the following keywords can be used instead of a Go layout: `UNIX` (seconds), `UNIXMILLIS` (milliseconds), `UNIXMICROS` (microseconds) or `UNIXNANOS` (nanoseconds).

### TagsInCSV

**Description**:This allows to add tags to the measurement with the tag value coming from csv data. The structure of this setting is similar as the `Filter` setting. The json key is the column index (as string) where the tag value is present, and the json value is the tag key (or tag name) under which the data should be stored upon the measurement:
**Required**: no
**Example**: `{"4": "Description"}`

### Locale

**Description**: The locale used to parse numbers for this measurement. Overrides the `Locale` setting on the collector.
**Required**: no
**Default**: empty

## Examples

### Example 1

This example demonstrates setting up a collector and measurement for a CSV with multiple sensor data.

Given the following CSV format, with files being provided by a data source located in `Europe/Brussels`.

:::BlockQuote
Time,Name,Value,Unit,Quality
"1/12/2023 13:00:01.868",P99,"0.00",,Good
"1/12/2023 13:01:01.876",P99,"0.00",,Good
"1/12/2023 13:02:01.863",P99,"100.00",,Good
"1/12/2023 13:03:01.840",P99,"100.00",,Good
"1/12/2023 13:00:01.868",TT100,"27.51",,Good
"1/12/2023 13:01:01.876",TT100,"26.04",,Good
"1/12/2023 13:02:01.863",TT100,"25.97.00",,Good
"1/12/2023 13:03:01.840",TT100,"26.23",,Good
:::

### Collector Settings

| Setting          | Value                  |
| ---------------- | ---------------------- |
| Delimiter        | ,                      |
| CSVHeaderRows    | 1                      |
| TimestampColumns | 0                      |
| TimestampLayout  | 2/01/2006 15:04:05.000 |
| StatusColumn     | 4                      |
| StatusGood       | Good                   |
| TrimString       | *No Value*             |

| Advanced Setting | Value             |
| ---------------- | ----------------- |
| SourceTimezone   | `Europe/Brussels` |

### Measurement Settings

| Setting         | Value           |
| --------------- | --------------- |
| Name            | Area\_Pump99    |
| ValueColumn     | 2               |
| Filter          | \{ “1”: “P99” } |
| TagsInCSV       | \{}             |
| TimestampLayout | *No Value*      |

| Setting         | Value                |
| --------------- | -------------------- |
| Name            | Area\_Temperature100 |
| ValueColumn     | 2                    |
| Filter          | \{ “1”: “TT100” }    |
| TagsInCSV       | \{}                  |
| TimestampLayout | *No Value*           |

### Filtering CSV data for measurements

The CSV collector can create points for multiple measurements at the same record (optionally originating from different value columns).
Measurements on the csv collector, are required to have a value column index using `ValueColumn` and can optionally have a mapping for a name or multiple names in the csv record using `Filter`.

When no name in the csv is available for the measurement, the measurement can be saved with `Filter`:
`{}`

When there is a name or there are multiple names available in the csv (in different columns) which should match for this measurement, then the measurement can be saved with `Filter`:
`{"column index": "name in csv in that column"}`
or
`{"column index": "name in csv in that column", "column index": "name in csv in that column"}`

For multiple mappings in `Filter`, all mappings should be valid for the record to create a point for the measurement!

For one mapping, multiple possible names can be given by separating the names with a semicolon:
`{"column index": "name1;name2", "column index": "name in csv in that column"}`

### Settings

Make sure to set the according [collector settings](docId:8gg_phiz1KfFGCi2XkWCp) , prior to adding measurements with the proper [measurement settings](docId:8gg_phiz1KfFGCi2XkWCp).