Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 39 additions & 41 deletions content/shared/influxdb3-write-guides/_index.md
Original file line number Diff line number Diff line change
@@ -1,35 +1,36 @@

Use tools like the {{% show-in "cloud-dedicated,clustered" %}}`influxctl`{{% /show-in %}}{{% show-in "cloud-serverless" %}}`influx`{{% /show-in %}}{{% show-in "core,enterprise" %}}`influxdb3`{{% /show-in %}}
CLI, Telegraf, and InfluxDB client libraries
CLI, Telegraf, and InfluxDB client libraries
to write time series data to {{< product-name >}}.
[line protocol](#line-protocol)
is the text-based format used to write data to InfluxDB.

> [!Tip]
> \[!Tip]
> Tools are available to convert other formats (for example—[CSV](/influxdb3/version/write-data/use-telegraf/csv/)) to line protocol.

{{% show-in "core,enterprise" %}}

- [Choose the write endpoint for your workload](#choose-the-write-endpoint-for-your-workload)
- [Timestamp precision across write APIs](#timestamp-precision-across-write-apis)
{{% /show-in %}}
{{% /show-in %}}
- [Line protocol](#line-protocol)
- [Line protocol elements](#line-protocol-elements)
- [Write data to InfluxDB](#write-data-to-influxdb)
{{< children type="anchored-list" >}}

{{% show-in "core,enterprise" %}}

> [!Tip]
> \[!Tip]
>
> #### Choose the write endpoint for your workload
>
>
> When creating new write workloads, use the
> [InfluxDB HTTP API `/api/v3/write_lp` endpoint](/influxdb3/version/write-data/http-api/v3-write-lp/)
> and [client libraries](/influxdb3/version/write-data/client-libraries/).
>
> When bringing existing _v1_ write workloads, use the {{% product-name %}}
> When bringing existing *v1* write workloads, use the {{% product-name %}}
> HTTP API [`/write` endpoint](/influxdb3/core/api/v3/#operation/PostV1Write).
>
> When bringing existing _v2_ write workloads, use the {{% product-name %}}
> When bringing existing *v2* write workloads, use the {{% product-name %}}
> HTTP API [`/api/v2/write` endpoint](/influxdb3/version/api/v3/#operation/PostV2Write).
>
> **For Telegraf**, use the InfluxDB v1.x [`outputs.influxdb`](/telegraf/v1/output-plugins/influxdb/) or v2.x [`outputs.influxdb_v2`](/telegraf/v1/output-plugins/influxdb_v2/) output plugins.
Expand All @@ -40,19 +41,16 @@ is the text-based format used to write data to InfluxDB.
{{% product-name %}} provides multiple write endpoints for compatibility with different InfluxDB versions.
The following table compares timestamp precision support across v1, v2, and v3 write APIs:

| Precision | v1 (`/write`) | v2 (`/api/v2/write`) | v3 (`/api/v3/write_lp`) |
|-----------|---------------|----------------------|-------------------------|
| **Auto detection** | ❌ No | ❌ No | ✅ `auto` (default) |
| **Seconds** | ✅ `s` | ✅ `s` | ✅ `second` |
| **Milliseconds** | ✅ `ms` | ✅ `ms` | ✅ `millisecond` |
| **Microseconds** | ✅ `u` or `µ` | ✅ `us` | ✅ `microsecond` |
| **Nanoseconds** | ✅ `ns` | ✅ `ns` | ✅ `nanosecond` |
| **Minutes** | ✅ `m` | ❌ No | ❌ No |
| **Hours** | ✅ `h` | ❌ No | ❌ No |
| **Default** | Nanosecond | Nanosecond | **Auto** (guessed) |

> [!Note]
> A bug currently prevents abbreviated precision values (`ns`, `n`, `us`, `u`, `ms`, `s`) from working with the `/api/v3/write_lp` endpoint. Use the full names (`nanosecond`, `microsecond`, `millisecond`, `second`) instead. Abbreviated values will be supported in a future release.
| Precision | v1 (`/write`) | v2 (`/api/v2/write`) | v3 (`/api/v3/write_lp`) |
| ------------------ | ------------- | -------------------- | ----------------------- |
| **Auto detection** | ❌ No | ❌ No | ✅ `auto` (default) |
| **Seconds** | ✅ `s` | ✅ `s` | ✅ `second` |
| **Milliseconds** | ✅ `ms` | ✅ `ms` | ✅ `millisecond` |
| **Microseconds** | ✅ `u` or `µ` | ✅ `us` | ✅ `microsecond` |
| **Nanoseconds** | ✅ `ns` | ✅ `ns` | ✅ `nanosecond` |
| **Minutes** | ✅ `m` | ❌ No | ❌ No |
| **Hours** | ✅ `h` | ❌ No | ❌ No |
| **Default** | Nanosecond | Nanosecond | **Auto** (guessed) |

- All write endpoints accept timestamps in line protocol format.
- {{% product-name %}} multiplies timestamps by the appropriate precision value to convert them to nanoseconds for internal storage.
Expand All @@ -61,15 +59,16 @@ The following table compares timestamp precision support across v1, v2, and v3 w
{{% /show-in %}}

{{% hide-in "core,enterprise" %}}
> [!Note]
>

> \[!Note]
>
> #### Choose the write endpoint for your workload
>
>
> When bringing existing v1 write workloads, use the {{% product-name %}}
> HTTP API [`/write` endpoint](/influxdb3/version/guides/api-compatibility/v1/).
> When creating new write workloads, use the HTTP API
> [`/api/v2/write` endpoint](/influxdb3/version/guides/api-compatibility/v2/).
{{% /hide-in %}}
> {{% /hide-in %}}

## Line protocol

Expand All @@ -89,11 +88,11 @@ Each line of line protocol contains the following elements:
- {{< req "\*" >}} **table**: A string that identifies the
table to store the data in.
- **tag set**: Comma-delimited list of key value pairs, each representing a tag.
Tag keys and values are unquoted strings. _Spaces, commas, and equal characters
must be escaped._
Tag keys and values are unquoted strings. *Spaces, commas, and equal characters
must be escaped.*
- {{< req "\*" >}} **field set**: Comma-delimited list of key value pairs, each
representing a field.
Field keys are unquoted strings. _Spaces and commas must be escaped._
Field keys are unquoted strings. *Spaces and commas must be escaped.*
Field values can be [strings](/influxdb3/version/reference/line-protocol/#string)
(quoted),
[floats](/influxdb3/version/reference/line-protocol/#float),
Expand All @@ -102,30 +101,29 @@ Each line of line protocol contains the following elements:
or [booleans](/influxdb3/version/reference/line-protocol/#boolean).
- **timestamp**: [Unix timestamp](/influxdb3/version/reference/line-protocol/#unix-timestamp)
associated with the data. InfluxDB supports up to nanosecond precision.
_If the precision of the timestamp is not in nanoseconds, you must specify the
precision when writing the data to InfluxDB._
*If the precision of the timestamp is not in nanoseconds, you must specify the
precision when writing the data to InfluxDB.*

#### Line protocol element parsing

- **table**: Everything before the _first unescaped comma before the first
whitespace_.
- **tag set**: Key-value pairs between the _first unescaped comma_ and the _first
unescaped whitespace_.
- **field set**: Key-value pairs between the _first and second unescaped whitespaces_.
- **timestamp**: Integer value after the _second unescaped whitespace_.
- **table**: Everything before the *first unescaped comma before the first
whitespace*.
- **tag set**: Key-value pairs between the *first unescaped comma* and the *first
unescaped whitespace*.
- **field set**: Key-value pairs between the *first and second unescaped whitespaces*.
- **timestamp**: Integer value after the *second unescaped whitespace*.
- Lines are separated by the newline character (`\n`).
Line protocol is whitespace sensitive.

---
***

{{< influxdb/line-protocol version="v3" >}}

---
***

_For schema design recommendations, see
[InfluxDB schema design](/influxdb3/version/write-data/best-practices/schema-design/)._
*For schema design recommendations, see
[InfluxDB schema design](/influxdb3/version/write-data/best-practices/schema-design/).*

## Write data to InfluxDB

{{< children >}}

3 changes: 0 additions & 3 deletions content/shared/influxdb3-write-guides/http-api/v3-write-lp.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,6 @@ syntax as previous versions of InfluxDB, and supports the following:
- `millisecond` (milliseconds)
- `second` (seconds)

> \[!Note]
> A bug currently prevents abbreviated precision values (`ns`, `n`, `us`, `u`, `ms`, `s`) from working with the `/api/v3/write_lp` endpoint. Use the full names (`nanosecond`, `microsecond`, `millisecond`, `second`) instead. Abbreviated values will be supported in a future release.

### Auto precision detection

When you use `precision=auto` (or omit the parameter), {{% product-name %}} automatically detects the timestamp precision based on the magnitude of the timestamp value:
Expand Down