diff --git a/api-docs/influxdb3/core/v3/ref.yml b/api-docs/influxdb3/core/v3/ref.yml index 3d21dff42a..dea112b9e4 100644 --- a/api-docs/influxdb3/core/v3/ref.yml +++ b/api-docs/influxdb3/core/v3/ref.yml @@ -204,7 +204,26 @@ tags: - name: Token description: Manage tokens for authentication and authorization - name: Write data - description: Write data to InfluxDB 3 + description: | + Write data to InfluxDB 3 using line protocol format. + + #### Timestamp precision across write APIs + + InfluxDB 3 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` | ✅ `s` or `second` | + | **Milliseconds** | ✅ `ms` | ✅ `ms` | ✅ `ms` or `millisecond` | + | **Microseconds** | ✅ `u` or `µ` | ✅ `us` | ✅ `us` or `microsecond` | + | **Nanoseconds** | ✅ `ns` | ✅ `ns` | ✅ `ns` or `nanosecond` | + | **Minutes** | ✅ `m` | ❌ No | ❌ No | + | **Hours** | ✅ `h` | ❌ No | ❌ No | + | **Default** | Nanosecond | Nanosecond | **Auto** (guessed) | + + All timestamps are stored internally as nanoseconds. paths: /write: post: @@ -430,11 +449,21 @@ paths: Use query parameters to specify options for writing data. #### Features - + - **Partial writes**: Use `accept_partial=true` to allow partial success when some lines in a batch fail - - **Asynchronous writes**: Use `no_sync=true` to skip waiting for WAL synchronization, allowing faster response times but sacrificing durability guarantees + - **Asynchronous writes**: Use `no_sync=true` to skip waiting for WAL synchronization, allowing faster response times but sacrificing durability guarantees - **Flexible precision**: Automatic timestamp precision detection with `precision=auto` (default) + #### Auto precision detection + + When you use `precision=auto` or omit the precision parameter, InfluxDB 3 automatically detects + the timestamp precision based on the magnitude of the timestamp value: + + - Timestamps < 5e9 → Second precision (multiplied by 1,000,000,000 to convert to nanoseconds) + - Timestamps < 5e12 → Millisecond precision (multiplied by 1,000,000) + - Timestamps < 5e15 → Microsecond precision (multiplied by 1,000) + - Larger timestamps → Nanosecond precision (no conversion needed) + #### Related - [Use the InfluxDB v3 write_lp API to write data](/influxdb3/core/write-data/http-api/v3-write-lp/) @@ -1911,13 +1940,24 @@ components: PrecisionWrite: enum: - auto + - ns + - nanosecond + - us + - microsecond + - ms - millisecond + - s - second - - microsecond - - nanosecond type: string description: | The precision for unix timestamps in the line protocol batch. + + Supported values (both short and long forms are accepted): + - `auto` (default): Automatically detects precision based on timestamp magnitude + - `ns` or `nanosecond`: Nanoseconds + - `us` or `microsecond`: Microseconds + - `ms` or `millisecond`: Milliseconds + - `s` or `second`: Seconds QueryRequestObject: type: object properties: diff --git a/api-docs/influxdb3/enterprise/v3/ref.yml b/api-docs/influxdb3/enterprise/v3/ref.yml index 7a1094d877..41e27368f0 100644 --- a/api-docs/influxdb3/enterprise/v3/ref.yml +++ b/api-docs/influxdb3/enterprise/v3/ref.yml @@ -204,7 +204,26 @@ tags: - name: Token description: Manage tokens for authentication and authorization - name: Write data - description: Write data to InfluxDB 3 + description: | + Write data to InfluxDB 3 using line protocol format. + + #### Timestamp precision across write APIs + + InfluxDB 3 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` | ✅ `s` or `second` | + | **Milliseconds** | ✅ `ms` | ✅ `ms` | ✅ `ms` or `millisecond` | + | **Microseconds** | ✅ `u` or `µ` | ✅ `us` | ✅ `us` or `microsecond` | + | **Nanoseconds** | ✅ `ns` | ✅ `ns` | ✅ `ns` or `nanosecond` | + | **Minutes** | ✅ `m` | ❌ No | ❌ No | + | **Hours** | ✅ `h` | ❌ No | ❌ No | + | **Default** | Nanosecond | Nanosecond | **Auto** (guessed) | + + All timestamps are stored internally as nanoseconds. paths: /write: post: @@ -430,11 +449,21 @@ paths: Use query parameters to specify options for writing data. #### Features - + - **Partial writes**: Use `accept_partial=true` to allow partial success when some lines in a batch fail - - **Asynchronous writes**: Use `no_sync=true` to skip waiting for WAL synchronization, allowing faster response times but sacrificing durability guarantees + - **Asynchronous writes**: Use `no_sync=true` to skip waiting for WAL synchronization, allowing faster response times but sacrificing durability guarantees - **Flexible precision**: Automatic timestamp precision detection with `precision=auto` (default) + #### Auto precision detection + + When you use `precision=auto` or omit the precision parameter, InfluxDB 3 automatically detects + the timestamp precision based on the magnitude of the timestamp value: + + - Timestamps < 5e9 → Second precision (multiplied by 1,000,000,000 to convert to nanoseconds) + - Timestamps < 5e12 → Millisecond precision (multiplied by 1,000,000) + - Timestamps < 5e15 → Microsecond precision (multiplied by 1,000) + - Larger timestamps → Nanosecond precision (no conversion needed) + #### Related - [Use the InfluxDB v3 write_lp API to write data](/influxdb3/enterprise/write-data/http-api/v3-write-lp/) @@ -2043,13 +2072,24 @@ components: PrecisionWrite: enum: - auto + - ns + - nanosecond + - us + - microsecond + - ms - millisecond + - s - second - - microsecond - - nanosecond type: string description: | The precision for unix timestamps in the line protocol batch. + + Supported values (both short and long forms are accepted): + - `auto` (default): Automatically detects precision based on timestamp magnitude + - `ns` or `nanosecond`: Nanoseconds + - `us` or `microsecond`: Microseconds + - `ms` or `millisecond`: Milliseconds + - `s` or `second`: Seconds QueryRequestObject: type: object properties: diff --git a/content/shared/influxdb3-write-guides/_index.md b/content/shared/influxdb3-write-guides/_index.md index eb743e572e..b70fb486e4 100644 --- a/content/shared/influxdb3-write-guides/_index.md +++ b/content/shared/influxdb3-write-guides/_index.md @@ -1,29 +1,60 @@ -Use tools like the `influxctl` CLI, Telegraf, and InfluxDB client libraries to -to write time series data to {{< product-name >}}. [Line protocol](#line-protocol) -is the text-based format used to write data to InfluxDB. There are tools -available to covert other formats (for example—[CSV](/influxdb3/version/write-data/use-telegraf/csv/)) -to line protocol. +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 +to write time series data to {{< product-name >}}. +[line protocol](#line-protocol) +is the text-based format used to write data to InfluxDB. +> [!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 %}} - [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" %}} -> [!Note] -> + +> [!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/PostV1Write](/influxdb3/version/api/v3/#operation/PostV2Write)). +> +> **For Telegraf**, use the InfluxDB v1.x [`outputs.influxdb`](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) or v2.x [`outputs.influxdb_v2`](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb_v2/README.md) output plugins. +> See how to [use Telegraf to write data](/influxdb3/version/write-data/use-telegraf/). + +## Timestamp precision across write APIs + +{{% 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` | ✅ `s` or `second` | +| **Milliseconds** | ✅ `ms` | ✅ `ms` | ✅ `ms` or `millisecond` | +| **Microseconds** | ✅ `u` or `µ` | ✅ `us` | ✅ `us` or `microsecond` | +| **Nanoseconds** | ✅ `ns` | ✅ `ns` | ✅ `ns` or `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. +- All timestamps are stored internally as nanoseconds regardless of the precision specified when writing. + {{% /show-in %}} {{% hide-in "core,enterprise" %}} diff --git a/content/shared/influxdb3-write-guides/http-api/_index.md b/content/shared/influxdb3-write-guides/http-api/_index.md index 6122cf589a..044a90e7e2 100644 --- a/content/shared/influxdb3-write-guides/http-api/_index.md +++ b/content/shared/influxdb3-write-guides/http-api/_index.md @@ -1,4 +1,22 @@ Use the InfluxDB HTTP API to write data to {{< product-name >}}. -There are different APIs you can use depending on your integration method. +Different APIs are available depending on your integration method. + +{{% show-in "core,enterprise" %}} +> [!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 %}} +> HTTP API [`/write` endpoint](/influxdb3/core/api/v3/#operation/PostV1Write). +> +> When bringing existing _v2_ write workloads, use the {{% product-name %}} +> HTTP API [`/api/v2/write` endpoint]([/influxdb3/version/api/v3/#operation/PostV1Write](/influxdb3/version/api/v3/#operation/PostV2Write)). +> +> **For Telegraf**, use the InfluxDB v1.x [`outputs.influxdb`](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) or v2.x [`outputs.influxdb_v2`](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb_v2/README.md) output plugins. +> See how to [use Telegraf to write data](/influxdb3/version/write-data/use-telegraf/). +{{% /show-in %}} {{< children >}} diff --git a/content/shared/influxdb3-write-guides/http-api/compatibility-apis.md b/content/shared/influxdb3-write-guides/http-api/compatibility-apis.md index 5f7b821023..6a7f0d586a 100644 --- a/content/shared/influxdb3-write-guides/http-api/compatibility-apis.md +++ b/content/shared/influxdb3-write-guides/http-api/compatibility-apis.md @@ -5,6 +5,22 @@ The `/api/v2/write` (v2-compatible) and `/write` (v1-compatible) HTTP API endpoints work with InfluxDB [client libraries](/influxdb3/version/reference/client-libraries/), [Telegraf](/telegraf/v1/), and third-party integrations to write points as line protocol data to {{% product-name %}}. +> [!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 %}} +> HTTP API [`/write` endpoint](/influxdb3/core/api/v3/#operation/PostV1Write). +> +> When bringing existing v2 write workloads, use the {{% product-name %}} +> HTTP API [`/api/v2/write` endpoint]([/influxdb3/version/api/v3/#operation/PostV1Write](/influxdb3/version/api/v3/#operation/PostV2Write)). +> +> **For Telegraf**, use the InfluxDB v1.x [`outputs.influxdb`](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) or v2.x [`outputs.influxdb_v2`](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb_v2/README.md) output plugins. +> See how to [use Telegraf to write data](/influxdb3/version/write-data/use-telegraf/). + > [!Note] > #### Compatibility APIs differ from native APIs > diff --git a/content/shared/influxdb3-write-guides/http-api/v3-write-lp.md b/content/shared/influxdb3-write-guides/http-api/v3-write-lp.md index 477b3bb2ad..3505629092 100644 --- a/content/shared/influxdb3-write-guides/http-api/v3-write-lp.md +++ b/content/shared/influxdb3-write-guides/http-api/v3-write-lp.md @@ -3,24 +3,81 @@ Use the `/api/v3/write_lp` endpoint to write data to {{% product-name %}}. This endpoint accepts the same [line protocol](/influxdb3/version/reference/line-protocol/) syntax as previous versions of InfluxDB, and supports the following: -##### Query parameters +## Query parameters - `?accept_partial=`: Accept or reject partial writes (default is `true`). - `?no_sync=`: Control when writes are acknowledged: - `no_sync=true`: Acknowledges writes before WAL persistence completes. - `no_sync=false`: Acknowledges writes after WAL persistence completes (default). - `?precision=`: Specify the precision of the timestamp. - By default, {{% product-name %}} uses the timestamp magnitude to auto-detect the precision. + By default, {{% product-name %}} uses the timestamp magnitude to auto-detect the precision (`auto`). To avoid any ambiguity, you can specify the precision of timestamps in your data. - + The {{< product-name >}} `/api/v3/write_lp` API endpoint supports the following timestamp precisions: - - - `ns` (nanoseconds) - - `us` (microseconds) - - `ms` (milliseconds) - - `s` (seconds) -##### Request body + - `auto` (automatic detection, default) + - `ns` or `nanosecond` (nanoseconds) + - `us` or `microsecond` (microseconds) + - `ms` or `millisecond` (milliseconds) + - `s` or `second` (seconds) + +### 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: + +- Timestamps < 5e9 → Second precision (multiplied by 1,000,000,000 to convert to nanoseconds) +- Timestamps < 5e12 → Millisecond precision (multiplied by 1,000,000) +- Timestamps < 5e15 → Microsecond precision (multiplied by 1,000) +- Larger timestamps → Nanosecond precision (no conversion needed) + +### Precision examples + +The following examples show how to write data with different timestamp precisions: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Auto (default)](#) +[Nanoseconds](#) +[Milliseconds](#) +[Seconds](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```bash +# Auto precision (default) - timestamp magnitude determines precision +curl "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors" \ + --header "Authorization: Bearer DATABASE_TOKEN" \ + --data-raw "cpu,host=server1 usage=50.0 1708976567" +``` + +The timestamp `1708976567` is automatically detected as seconds. +{{% /code-tab-content %}} +{{% code-tab-content %}} +```bash +# Explicit nanosecond precision +curl "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=ns" \ + --header "Authorization: Bearer DATABASE_TOKEN" \ + --data-raw "cpu,host=server1 usage=50.0 1708976567000000000" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```bash +# Millisecond precision +curl "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=ms" \ + --header "Authorization: Bearer DATABASE_TOKEN" \ + --data-raw "cpu,host=server1 usage=50.0 1708976567000" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```bash +# Second precision +curl "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=s" \ + --header "Authorization: Bearer DATABASE_TOKEN" \ + --data-raw "cpu,host=server1 usage=50.0 1708976567" +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +## Request body - Line protocol