---
title: Extended annotated CSV
description: Extended annotated CSV provides additional annotations and options that specify how CSV data should be converted to line protocol and written to InfluxDB.
url: https://docs.influxdata.com/influxdb/v2/reference/syntax/annotated-csv/extended/
estimated_tokens: 3830
product: InfluxDB OSS v2
version: v2
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb/v2/reference/syntax/annotated-csv/extended/
date: '2025-04-02T15:54:32-06:00'
lastmod: '2025-04-02T15:54:32-06:00'
---

This page documents an earlier version of InfluxDB OSS.[InfluxDB 3 Core](/influxdb3/core/) is the latest stable version.

#### API token hashing is enabled by default in InfluxDB OSS 2.9.0

Stronger token security: tokens are stored as hashes on disk, so a
copy of the database file doesn’t expose usable tokens. Existing
tokens are hashed on first startup and the original strings can’t
be recovered afterward — **capture any plaintext tokens you still
need before you upgrade**.

For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing).

**Extended annotated CSV** provides additional annotations and options that specify
how CSV data should be converted to [line protocol](/influxdb/v2/reference/syntax/line-protocol/)and written to InfluxDB.
InfluxDB uses the [`csv2lp` library](https://github.com/influxdata/influxdb/tree/master/pkg/csv2lp)to convert CSV into line protocol.
Extended annotated CSV supports all [Annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/)annotations.

The Flux [`csv.from` function](/flux/v0/stdlib/csv/from/) only supports[annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/), not extended annotated CSV.

To write data to InfluxDB, line protocol must include the following:

* [measurement](/influxdb/v2/reference/syntax/line-protocol/#measurement)
* [field set](/influxdb/v2/reference/syntax/line-protocol/#field-set)
* [timestamp](/influxdb/v2/reference/syntax/line-protocol/#timestamp) *(Optional but recommended)*
* [tag set](/influxdb/v2/reference/syntax/line-protocol/#tag-set) *(Optional)*

Extended CSV annotations identify the element of line protocol a column represents.

## CSV Annotations

Extended annotated CSV extends and adds the following annotations:

* [datatype](#datatype)
* [constant](#constant)
* [timezone](#timezone)
* [concat](#concat)

### datatype

Use the `#datatype` annotation to specify the [line protocol element](/influxdb/v2/reference/syntax/line-protocol/#elements-of-line-protocol)a column represents.
To explicitly define a column as a **field** of a specific data type, use the field
type in the annotation (for example: `string`, `double`, `long`, etc.).

|          Data type          |        Resulting line protocol        |
|-----------------------------|---------------------------------------|
| [measurement](#measurement) |     Column is the **measurement**     |
|         [tag](#tag)         |          Column is a **tag**          |
|    [dateTime](#datetime)    |      Column is the **timestamp**      |
|       [field](#field)       |         Column is a **field**         |
|     [ignored](#ignored)     |           Column is ignored           |
|      [string](#string)      |     Column is a **string field**      |
|      [double](#double)      |      Column is a **float field**      |
|        [long](#long)        |    Column is an **integer field**     |
|[unsignedLong](#unsignedlong)|Column is an **unsigned integer field**|
|     [boolean](#boolean)     |     Column is a **boolean field**     |

#### measurement

Indicates the column is the **measurement**.

#### tag

Indicates the column is a **tag**.
The **column label** is the **tag key**.
The **column value** is the **tag value**.

#### dateTime

Indicates the column is the **timestamp**.`time` is an alias for `dateTime`.
If the [timestamp format](#supported-timestamp-formats) includes a time zone,
the parsed timestamp includes the time zone offset.
By default, all timestamps are UTC.
You can also use the [`#timezone` annotation](#timezone) to adjust timestamps to
a specific time zone.

> [!Note]
> There can only be **one** `dateTime` column.

The `influx write` command converts timestamps to [Unix timestamps](/influxdb/v2/reference/glossary/#unix-timestamp).
Append the timestamp format to the `dateTime` datatype with (`:`).

```csv
#datatype dateTime:RFC3339
#datatype dateTime:RFC3339Nano
#datatype dateTime:number
#datatype dateTime:2006-01-02
```

##### Supported timestamp formats

|Timestamp format|   Description   |            Example             |
|----------------|-----------------|--------------------------------|
|  **RFC3339**   |RFC3339 timestamp|     `2020-01-01T00:00:00Z`     |
|**RFC3339Nano** |RFC3339 timestamp|`2020-01-01T00:00:00.000000000Z`|
|   **number**   | Unix timestamp  |     `1577836800000000000`      |

> [!Note]
> If using the `number` timestamp format and timestamps are **not in nanoseconds**,
> use the [`influx write --precision` flag](/influxdb/v2/reference/cli/influx/write/#flags)to specify the [timestamp precision](/influxdb/v2/reference/glossary/#precision).

##### Custom timestamp formats

To specify a custom timestamp format, use timestamp formats as described in the[Go time package](https://golang.org/pkg/time).
For example: `2020-01-02`.

#### field

Indicates the column is a **field**.
The **column label** is the **field key**.
The **column value** is the **field value**.

> [!Note]
> With the `field` datatype, field values are copies **as-is** to line protocol.
> For information about line protocol values and how they are written to InfluxDB,
> see [Line protocol data types and formats](/influxdb/v2/reference/syntax/line-protocol/#data-types-and-format).
> We generally recommend specifying the [field type](#field-types) in annotations.

#### ignored

The column is ignored and not written to InfluxDB.

#### Field types

The column is a **field** of a specified type.
The **column label** is the **field key**.
The **column value** is the **field value**.

* [string](#string)
* [double](#double)
* [long](#long)
* [unsignedLong](#unsignedlong)
* [boolean](#boolean)

##### string

Column is a **[string](/influxdb/v2/reference/glossary/#string) field**.

##### double

Column is a **[float](/influxdb/v2/reference/glossary/#float) field**.
By default, InfluxDB expects float values that use a period (`.`) to separate the
fraction from the whole number.
If column values include or use other separators, such as commas (`,`) to visually
separate large numbers into groups, specify the following **float separators**:

* **fraction separator**: Separates the fraction from the whole number.
* **ignored separator**: Visually separates the whole number into groups but ignores
  the separator when parsing the float value.

Use the following syntax to specify **float separators**:

```sh
# Syntax
<fraction-separator><ignored-separator>

# Example
.,

# With the float separators above
# 1,200,000.15 => 1200000.15
```

Append **float separators** to the `double` datatype annotation with a colon (`:`).
For example:

```
#datatype "double:.,"
```

> [!Note]
> If your **float separators** include a comma (`,`), wrap the column annotation in double
> quotes (`""`) to prevent the comma from being parsed as a column separator or delimiter.
> You can also [define a custom column separator](#define-custom-column-separator).

##### long

Column is an **[integer](/influxdb/v2/reference/glossary/#integer) field**.
If column values contain separators such as periods (`.`) or commas (`,`), specify
the following **integer separators**:

* **fraction separator**: Separates the fraction from the whole number.***Integer values are truncated at the fraction separator when converted to line protocol.***
* **ignored separator**: Visually separates the whole number into groups but ignores
  the separator when parsing the integer value.

Use the following syntax to specify **integer separators**:

```sh
# Syntax
<fraction-separator><ignored-separator>

# Example
.,

# With the integer separators above
# 1,200,000.00 => 1200000i
```

Append **integer separators** to the `long` datatype annotation with a colon (`:`).
For example:

```
#datatype "long:.,"
```

> [!Note]
> If your **integer separators** include a comma (`,`), wrap the column annotation in double
> quotes (`""`) to prevent the comma from being parsed as a column separator or delimiter.
> You can also [define a custom column separator](#define-custom-column-separator).

##### unsignedLong

Column is an **[unsigned integer (uinteger)](/influxdb/v2/reference/glossary/#unsigned-integer) field**.
If column values contain separators such as periods (`.`) or commas (`,`), specify
the following **uinteger separators**:

* **fraction separator**: Separates the fraction from the whole number.***Uinteger values are truncated at the fraction separator when converted to line protocol.***
* **ignored separator**: Visually separates the whole number into groups but ignores
  the separator when parsing the uinteger value.

Use the following syntax to specify **uinteger separators**:

```sh
# Syntax
<fraction-separator><ignored-separator>

# Example
.,

# With the uinteger separators above
# 1,200,000.00 => 1200000u
```

Append **uinteger separators** to the `long` datatype annotation with a colon (`:`).
For example:

```
#datatype "unsignedLong:.,"
```

> [!Note]
> If your **uinteger separators** include a comma (`,`), wrap the column annotation in double
> quotes (`""`) to prevent the comma from being parsed as a column separator or delimiter.
> You can also [define a custom column separator](#define-custom-column-separator).

##### boolean

Column is a **[boolean](/influxdb/v2/reference/glossary/#boolean) field**.
If column values are not [supported boolean values](/influxdb/v2/reference/syntax/line-protocol/#boolean),
specify the **boolean format** with the following syntax:

```sh
# Syntax
<true-values>:<false-values>

# Example
y,Y,1:n,N,0

# With the boolean format above
# y => true, Y => true, 1 => true
# n => false, N => false, 0 => false
```

Append the **boolean format** to the `boolean` datatype annotation with a colon (`:`).
For example:

```
#datatype "boolean:y,Y:n,N"
```

> [!Note]
> If your **boolean format** contains commas (`,`), wrap the column annotation in double
> quotes (`""`) to prevent the comma from being parsed as a column separator or delimiter.
> You can also [define a custom column separator](#define-custom-column-separator).

### constant

Use the `#constant` annotation to define a constant column label and value for each row.
The `#constant` annotation provides a way to supply[line protocol elements](/influxdb/v2/reference/syntax/line-protocol/#elements-of-line-protocol)that don’t exist in the CSV data.

Use the following syntax to define constants:

```
#constant <datatype>,<column-label>,<column-value>
```

To provide multiple constants, include each `#constant` annotations on a separate line.

```
#constant measurement,m
#constant tag,dataSource,csv
```

> [!Note]
> For constants with `measurement` and `dateTime` datatypes, the second value in
> the constant definition is the **column-value**.

### timezone

Use the `#timezone` annotation to update timestamps to a specific timezone.
By default, timestamps are parsed as UTC.
Use the `±HHmm` format to specify the timezone offset relative to UTC.

### strict mode

Use the `:strict` keyword to indicate a loss of precision when parsing `long` or `unsignedLong` data types.
Turn on strict mode by using a column data type that ends with `strict`, such as `long:strict`.
When parsing `long` or `unsignedLong` value from a string value with fraction digits, the whole CSV row fails when in a strict mode.
A warning is printed when not in a strict mode, saying `line x: column y: '1.2' truncated to '1' to fit into long data type`.
For more information on strict parsing, see the [package documentation](https://github.com/influxdata/influxdb/tree/master/pkg/csv2lp).

##### Timezone examples

|           Timezone            |Offset |
|-------------------------------|-------|
|   US Mountain Daylight Time   |`-0600`|
| Central European Summer Time  |`+0200`|
|Australia Eastern Standard Time|`+1000`|
|      Apia Daylight Time       |`+1400`|

##### Timezone annotation example

```
#timezone -0600
```

### concat

The `#concat` annotation adds a new column that is concatenated from existing columns according to bash-like string interpolation literal with variables referencing existing column labels.

For example:

```
#concat,string,fullName,${firstName} ${lastName}
```

This is especially useful when constructing a timestamp from multiple columns.
For example, the following annotation will combine the given CSV columns into a timestamp:

```
#concat,dateTime:2006-01-02,${Year}-${Month}-${Day}

Year,Month,Day,Hour,Minute,Second,Tag,Value
2020,05,22,00,00,00,test,0
2020,05,22,00,05,00,test,1
2020,05,22,00,10,00,test,2
```

## Define custom column separator

If columns are delimited using a character other than a comma, use the `sep`keyword to define a custom separator **in the first line of your CSV file**.

```
sep=;
```

## Annotation shorthand

Extended annotated CSV supports **annotation shorthand**.
Include the column label, datatype, and *(optional)* default value in each column
header row using the following syntax:

```
<column-label>|<column-datatype>|<column-default-value>
```

##### Example annotation shorthand

```
m|measurement,location|tag|Hong Kong,temp|double,pm|long|0,time|dateTime:RFC3339
weather,San Francisco,51.9,38,2020-01-01T00:00:00Z
weather,New York,18.2,,2020-01-01T00:00:00Z
weather,,53.6,171,2020-01-01T00:00:00Z
```

##### The shorthand explained

* The `m` column represents the **measurement** and has no default value.
* The `location` column is a **tag** with the default value, `Hong Kong`.
* The `temp` column is a **field** with **float** (`double`) values and no default value.
* The `pm` column is a **field** with **integer** (`long`) values and a default of `0`.
* The `time` column represents the **timestamp**, uses the **RFC3339** timestamp format,
  and has no default value.

##### Resulting line protocol

```
weather,location=San\ Francisco temp=51.9,pm=38i 1577836800000000000
weather,location=New\ York temp=18.2,pm=0i 1577836800000000000
weather,location=Hong\ Kong temp=53.6,pm=171i 1577836800000000000
```

#### Related

* [Write CSV data to InfluxDB](/influxdb/v2/write-data/developer-tools/csv/)
* [influx write](/influxdb/v2/reference/cli/influx/write/)
* [Line protocol](/influxdb/v2/reference/syntax/line-protocol/)
* [Annotated CSV](/influxdb/v2/reference/syntax/annotated-csv/)

[csv](/influxdb/v2/tags/csv/)[syntax](/influxdb/v2/tags/syntax/)[write](/influxdb/v2/tags/write/)
| Data type | Resulting line protocol |
| --- | --- |
| Data type | Resulting line protocol |
| measurement | Column is the  measurement |
| tag | Column is a  tag |
| dateTime | Column is the  timestamp |
| field | Column is a  field |
| ignored | Column is ignored |
| string | Column is a  string field |
| double | Column is a  float field |
| long | Column is an  integer field |
| unsignedLong | Column is an  unsigned integer field |
| boolean | Column is a  boolean field |

| Timestamp format | Description | Example |
| --- | --- | --- |
| Timestamp format | Description | Example |
| RFC3339 | RFC3339 timestamp | 2020-01-01T00:00:00Z |
| RFC3339Nano | RFC3339 timestamp | 2020-01-01T00:00:00.000000000Z |
| number | Unix timestamp | 1577836800000000000 |

| Timezone | Offset |
| --- | --- |
| Timezone | Offset |
| US Mountain Daylight Time | -0600 |
| Central European Summer Time | +0200 |
| Australia Eastern Standard Time | +1000 |
| Apia Daylight Time | +1400 |