restructured write guides, start on gs query guide
Scott Anderson
parent
ba7e39cea4
commit
9dc847bf47
|
|
@ -1,5 +1,6 @@
|
|||
---
|
||||
title: Set up InfluxDB 3 Core
|
||||
title: Set up {{% product-name %}}
|
||||
seotitle: Set up InfluxDB | Get started with {{% product-name %}}
|
||||
description: >
|
||||
....
|
||||
menu:
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
---
|
||||
title: Write data to InfluxDB 3 Core
|
||||
title: Write data to {{% product-name %}}
|
||||
seotitle: Write data | Get started with {{% product-name %}}
|
||||
description: >
|
||||
....
|
||||
menu:
|
||||
|
|
@ -9,9 +10,8 @@ menu:
|
|||
parent: Get started
|
||||
weight: 102
|
||||
related:
|
||||
- /influxdb3/core/install/
|
||||
- /influxdb3/core/admin/tokens/
|
||||
- /influxdb3/core/reference/config-options/
|
||||
- /influxdb3/core/write-data/
|
||||
- /influxdb3/core/reference/line-protocol/
|
||||
source: /shared/influxdb3-get-started/write.md
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,21 +1,21 @@
|
|||
---
|
||||
title: Use the HTTP API and client libraries to write data
|
||||
title: Use InfluxDB client libraries to write data
|
||||
description: >
|
||||
Use the `/api/v3/write_lp` HTTP API endpoint and InfluxDB API clients to write points as line protocol data to {{% product-name %}}.
|
||||
Use InfluxDB API clients to write points as line protocol data to {{% product-name %}}.
|
||||
menu:
|
||||
influxdb3_core:
|
||||
name: Use the API and client libraries
|
||||
name: Use client libraries
|
||||
parent: Write data
|
||||
identifier: write-api-client-libs
|
||||
identifier: write-client-libs
|
||||
weight: 100
|
||||
aliases:
|
||||
- /influxdb3/core/write-data/client-libraries/
|
||||
- /influxdb3/core/write-data/api-client-libraries/
|
||||
related:
|
||||
- /influxdb3/core/reference/syntax/line-protocol/
|
||||
- /influxdb3/core/get-started/write/
|
||||
- /influxdb3/core/reference/client-libraries/v3/
|
||||
- /influxdb3/core/api/v3/#operation/PostWriteLP, /api/v3/write_lp endpoint
|
||||
source: /shared/influxdb3-write-guides/api-client-libraries.md
|
||||
source: /shared/influxdb3-write-guides/client-libraries.md
|
||||
---
|
||||
|
||||
<!--
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
---
|
||||
title: Use the InfluxDB HTTP API to write data
|
||||
description: >
|
||||
Use the `/api/v3/write_lp`, `/api/v2/write`, or `/write` HTTP API endpoints
|
||||
to write data to {{% product-name %}}.
|
||||
menu:
|
||||
influxdb3_core:
|
||||
name: Use the HTTP API
|
||||
parent: Write data
|
||||
identifier: write-http-api
|
||||
weight: 100
|
||||
related:
|
||||
- /influxdb3/core/reference/syntax/line-protocol/
|
||||
- /influxdb3/core/get-started/write/
|
||||
- /influxdb3/core/api/v3/#operation/PostWriteLP, /api/v3/write_lp endpoint
|
||||
source: /shared/influxdb3-write-guides/http-api/_index.md
|
||||
---
|
||||
|
||||
<!--
|
||||
The content for this page is at
|
||||
// SOURCE content/shared/influxdb3-write-guides/http-api/_index.md
|
||||
-->
|
||||
|
|
@ -6,21 +6,21 @@ description: >
|
|||
menu:
|
||||
influxdb3_core:
|
||||
name: Use v1 and v2 compatibility APIs
|
||||
parent: Write data
|
||||
identifier: write-compatibility-client-libs
|
||||
weight: 101
|
||||
parent: write-http-api
|
||||
weight: 202
|
||||
aliases:
|
||||
- /influxdb3/core/write-data/client-libraries/
|
||||
- /influxdb3/core/write-data/compatibility-apis/
|
||||
related:
|
||||
- /influxdb3/core/reference/syntax/line-protocol/
|
||||
- /influxdb3/core/get-started/write/
|
||||
- /influxdb3/core/reference/client-libraries/v2/
|
||||
- /influxdb3/core/api/v3/#operation/PostV2Write, /api/v2/write (v2-compatible) endpoint
|
||||
- /influxdb3/core/api/v3/#operation/PostV1Write, /write (v1-compatible) endpoint
|
||||
source: /shared/influxdb3-write-guides/compatibility-apis.md
|
||||
source: /shared/influxdb3-write-guides/http-api/compatibility-apis.md
|
||||
---
|
||||
|
||||
<!--
|
||||
The content for this page is at
|
||||
// SOURCE content/shared/influxdb3-write-guides/compatibility-apis.md
|
||||
// SOURCE content/shared/influxdb3-write-guides/http-api/compatibility-apis.md
|
||||
-->
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
---
|
||||
title: Use the v3 write API to write data
|
||||
description: >
|
||||
Use the `/api/v3/write_lp` HTTP API endpoint to write data to {{% product-name %}}.
|
||||
menu:
|
||||
influxdb3_core:
|
||||
name: Use the v3 write API
|
||||
parent: write-http-api
|
||||
weight: 201
|
||||
related:
|
||||
- /influxdb3/core/reference/syntax/line-protocol/
|
||||
- /influxdb3/core/get-started/write/
|
||||
- /influxdb3/core/api/v3/#operation/PostWriteLP, /api/v3/write_lp endpoint
|
||||
source: /shared/influxdb3-write-guides/http-api/v3-write-lp.md
|
||||
---
|
||||
|
||||
<!--
|
||||
The content for this page is at
|
||||
// SOURCE content/shared/influxdb3-write-guides/http-api/v3-write-lp.md
|
||||
-->
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
---
|
||||
title: Query data in {{% product-name %}}
|
||||
seotitle: Query data | Get started with {{% product-name %}}
|
||||
description: >
|
||||
....
|
||||
menu:
|
||||
influxdb3_enterprise:
|
||||
name: Query data
|
||||
identifier: gs-query-data
|
||||
parent: Get started
|
||||
weight: 103
|
||||
related:
|
||||
- /influxdb3/enterprise/query-data/
|
||||
- /influxdb3/enterprise/reference/sql/
|
||||
- /influxdb3/enterprise/reference/influxql/
|
||||
source: /shared/influxdb3-get-started/query.md
|
||||
---
|
||||
|
||||
<!--
|
||||
The content of this page is at
|
||||
// SOURCE content/shared/influxdb3-get-started/query.md
|
||||
-->
|
||||
|
|
@ -1,5 +1,6 @@
|
|||
---
|
||||
title: Set up InfluxDB 3 Enterprise
|
||||
title: Set up {{% product-name %}}
|
||||
seotitle: Set up InfluxDB | Get started with {{% product-name %}}
|
||||
description: >
|
||||
....
|
||||
menu:
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
---
|
||||
title: Write data to InfluxDB 3 Enterprise
|
||||
title: Write data to {{% product-name %}}
|
||||
seotitle: Write data | Get started with {{% product-name %}}
|
||||
description: >
|
||||
....
|
||||
menu:
|
||||
|
|
@ -9,9 +10,8 @@ menu:
|
|||
parent: Get started
|
||||
weight: 102
|
||||
related:
|
||||
- /influxdb3/enterprise/install/
|
||||
- /influxdb3/enterprise/admin/tokens/
|
||||
- /influxdb3/enterprise/reference/config-options/
|
||||
- /influxdb3/enterprise/write-data/
|
||||
- /influxdb3/enterprise/reference/line-protocol/
|
||||
source: /shared/influxdb3-get-started/write.md
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,24 +1,24 @@
|
|||
---
|
||||
title: Use the HTTP API and client libraries to write data
|
||||
title: Use InfluxDB client libraries to write data
|
||||
description: >
|
||||
Use the `/api/v3/write_lp` HTTP API endpoint and InfluxDB API clients to write points as line protocol data to {{% product-name %}}.
|
||||
Use InfluxDB API clients to write points as line protocol data to {{% product-name %}}.
|
||||
menu:
|
||||
influxdb3_enterprise:
|
||||
name: Use the API and client libraries
|
||||
name: Use client libraries
|
||||
parent: Write data
|
||||
identifier: write-api-client-libs
|
||||
identifier: write-client-libs
|
||||
weight: 100
|
||||
aliases:
|
||||
- /influxdb3/enterprise/write-data/client-libraries/
|
||||
- /influxdb3/enterprise/write-data/api-client-libraries/
|
||||
related:
|
||||
- /influxdb3/enterprise/reference/syntax/line-protocol/
|
||||
- /influxdb3/enterprise/get-started/write/
|
||||
- /influxdb3/enterprise/reference/client-libraries/v3/
|
||||
- /influxdb3/enterprise/api/v3/#operation/PostWriteLP, /api/v3/write_lp endpoint
|
||||
source: /shared/influxdb3-write-guides/api-client-libraries.md
|
||||
source: /shared/influxdb3-write-guides/client-libraries.md
|
||||
---
|
||||
|
||||
<!--
|
||||
The content for this page is at
|
||||
// SOURCE content/shared/influxdb3-write-guides/client-libraries.md
|
||||
-->
|
||||
-->
|
||||
|
|
@ -17,10 +17,10 @@ related:
|
|||
- /influxdb3/enterprise/reference/client-libraries/v2/
|
||||
- /influxdb3/enterprise/api/v3/#operation/PostV2Write, /api/v2/write (v2-compatible) endpoint
|
||||
- /influxdb3/enterprise/api/v3/#operation/PostV1Write, /write (v1-compatible) endpoint
|
||||
source: /shared/influxdb3-write-guides/compatibility-apis.md
|
||||
source: /shared/influxdb3-write-guides/http-api/compatibility-apis.md
|
||||
---
|
||||
|
||||
<!--
|
||||
The content for this page is at
|
||||
// SOURCE content/shared/influxdb3-write-guides/compatibility-apis.md
|
||||
// SOURCE content/shared/influxdb3-write-guides/http-api/compatibility-apis.md
|
||||
-->
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
---
|
||||
title: Use the InfluxDB HTTP API to write data
|
||||
description: >
|
||||
Use the `/api/v3/write_lp`, `/api/v2/write`, or `/write` HTTP API endpoints
|
||||
to write data to {{% product-name %}}.
|
||||
menu:
|
||||
influxdb3_enterprise:
|
||||
name: Use the HTTP API
|
||||
parent: Write data
|
||||
identifier: write-http-api
|
||||
weight: 100
|
||||
related:
|
||||
- /influxdb3/enterprise/reference/syntax/line-protocol/
|
||||
- /influxdb3/enterprise/get-started/write/
|
||||
- /influxdb3/enterprise/api/v3/#operation/PostWriteLP, /api/v3/write_lp endpoint
|
||||
source: /shared/influxdb3-write-guides/http-api/_index.md
|
||||
---
|
||||
|
||||
<!--
|
||||
The content for this page is at
|
||||
// SOURCE content/shared/influxdb3-write-guides/http-api/_index.md
|
||||
-->
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
title: Use compatibility APIs and client libraries to write data
|
||||
description: >
|
||||
Use HTTP API endpoints compatible with InfluxDB v2 and v1 clients to write
|
||||
points as line protocol data to {{% product-name %}}.
|
||||
menu:
|
||||
influxdb3_enterprise:
|
||||
name: Use v1 and v2 compatibility APIs
|
||||
parent: write-http-api
|
||||
weight: 202
|
||||
aliases:
|
||||
- /influxdb3/enterprise/write-data/client-libraries/
|
||||
- /influxdb3/enterprise/write-data/compatibility-apis/
|
||||
related:
|
||||
- /influxdb3/enterprise/reference/syntax/line-protocol/
|
||||
- /influxdb3/enterprise/get-started/write/
|
||||
- /influxdb3/enterprise/reference/client-libraries/v2/
|
||||
- /influxdb3/enterprise/api/v3/#operation/PostV2Write, /api/v2/write (v2-compatible) endpoint
|
||||
- /influxdb3/enterprise/api/v3/#operation/PostV1Write, /write (v1-compatible) endpoint
|
||||
source: /shared/influxdb3-write-guides/http-api/compatibility-apis.md
|
||||
---
|
||||
|
||||
<!--
|
||||
The content for this page is at
|
||||
// SOURCE content/shared/influxdb3-write-guides/http-api/compatibility-apis.md
|
||||
-->
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
---
|
||||
title: Use the v3 write API to write data
|
||||
description: >
|
||||
Use the `/api/v3/write_lp` HTTP API endpoint to write data to {{% product-name %}}.
|
||||
menu:
|
||||
influxdb3_enterprise:
|
||||
name: Use the v3 write API
|
||||
parent: write-http-api
|
||||
weight: 201
|
||||
related:
|
||||
- /influxdb3/enterprise/reference/syntax/line-protocol/
|
||||
- /influxdb3/enterprise/get-started/write/
|
||||
- /influxdb3/enterprise/api/v3/#operation/PostWriteLP, /api/v3/write_lp endpoint
|
||||
source: /shared/influxdb3-write-guides/http-api/v3-write-lp.md
|
||||
---
|
||||
|
||||
<!--
|
||||
The content for this page is at
|
||||
// SOURCE content/shared/influxdb3-write-guides/http-api/v3-write-lp.md
|
||||
-->
|
||||
|
|
@ -1,19 +1,20 @@
|
|||
### Query data
|
||||
|
||||
InfluxDB 3 supports native SQL for querying, in addition to InfluxQL, an
|
||||
SQL-like language customized for time series queries.
|
||||
<!-- COMMENT TO ALLOW STARTING WITH SHORTCODE -->
|
||||
{{% product-name %}} supports both native SQL and InfluxQL for querying data. InfluxQL is
|
||||
an SQL-like query language designed for InfluxDB v1 and customized for time
|
||||
series queries.
|
||||
|
||||
{{% show-in "core" %}}
|
||||
{{< product-name >}} limits
|
||||
query time ranges to 72 hours (both recent and historical) to ensure query performance.
|
||||
For more information about the 72-hour limitation, see the
|
||||
[update on InfluxDB 3 Core’s 72-hour limitation](https://www.influxdata.com/blog/influxdb3-open-source-public-alpha-jan-27/).
|
||||
query time ranges to approximately 72 hours (both recent and historical) to
|
||||
ensure query performance. For more information about the 72-hour limitation, see
|
||||
the [update on InfluxDB 3 Core’s 72-hour limitation](https://www.influxdata.com/blog/influxdb3-open-source-public-alpha-jan-27/).
|
||||
{{% /show-in %}}
|
||||
|
||||
> [!Note]
|
||||
> Flux, the language introduced in InfluxDB 2.0, is **not** supported in InfluxDB 3.
|
||||
> Flux, the language introduced in InfluxDB v2, is **not** supported in InfluxDB 3.
|
||||
|
||||
The quickest way to get started querying is to use the `influxdb3` CLI (which uses the Flight SQL API over HTTP2).
|
||||
The quickest way to get started querying is to use the `influxdb3` CLI
|
||||
(which uses the Flight SQL API over HTTP2).
|
||||
|
||||
The `query` subcommand includes options to help ensure that the right database is queried with the correct permissions. Only the `--database` option is required, but depending on your specific setup, you may need to pass other options, such as host, port, and token.
|
||||
|
||||
|
|
|
|||
|
|
@ -215,186 +215,20 @@ Replace the following placeholders with your values:
|
|||
>
|
||||
> There are many ways to write data to your {{% product-name %}} database, including:
|
||||
>
|
||||
> - [InfluxDB HTTP API](#write-data-using-the-http-api): Recommended for
|
||||
> - [InfluxDB HTTP API](/influxdb3/version/write-data/http-api/): Recommended for
|
||||
> batching and higher-volume write workloads.
|
||||
> - [InfluxDB client libraries](/influxdb3/version/write-data/api-client-libraries/):
|
||||
> - [InfluxDB client libraries](/influxdb3/version/write-data/client-libraries/):
|
||||
> Client libraries that integrate with your code to construct data as time
|
||||
> series points and write the data as line protocol to your {{% product-name %}} database.
|
||||
> series points and write the data as line protocol to your
|
||||
> {{% product-name %}} database.
|
||||
> - [Telegraf](/telegraf/v1/): A data collection agent with over 300 plugins for
|
||||
> collecting, processing, and writing data.
|
||||
>
|
||||
> For more information, see [Write data to {{% product-name %}}](/influxdb3/version/write-data/).
|
||||
|
||||
### Write data using the HTTP API
|
||||
|
||||
{{% product-name %}} provides three write API endpoints that respond to HTTP `POST` requests.
|
||||
The `/api/v3/write_lp` endpoint is the recommended endpoint for writing data and
|
||||
provides additional options for controlling write behavior.
|
||||
|
||||
If you need to write data using InfluxDB v1.x or v2.x tools, use the compatibility API endpoints.
|
||||
Compatibility APIs work with [Telegraf](/telegraf/v1/), InfluxDB v2.x and v1.x [API client libraries](/influxdb3/version/reference/client-libraries), and other tools that support the v1.x or v2.x APIs.
|
||||
|
||||
{{% tabs-wrapper %}}
|
||||
{{% tabs %}}
|
||||
[/api/v3/write_lp](#)
|
||||
[v2 compatibility](#)
|
||||
[v1 compatibility](#)
|
||||
{{% /tabs %}}
|
||||
{{% tab-content %}}
|
||||
<!------------ BEGIN /api/v3/write_lp -------------->
|
||||
{{% product-name %}} adds the `/api/v3/write_lp` endpoint.
|
||||
|
||||
{{<api-endpoint endpoint="/api/v3/write_lp?db=mydb&precision=nanosecond&accept_partial=true&no_sync=false" method="post" >}}
|
||||
|
||||
This endpoint accepts the same line protocol syntax as previous versions,
|
||||
and supports the following parameters:
|
||||
|
||||
- `?accept_partial=<BOOLEAN>`: Accept or reject partial writes (default is `true`).
|
||||
- `?no_sync=<BOOLEAN>`: 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=<PRECISION>`: Specify the precision of the timestamp. The default is nanosecond precision.
|
||||
- request body: The line protocol data to write.
|
||||
|
||||
For more information about the parameters, see [Write data](/influxdb3/version/write-data/).
|
||||
|
||||
##### Example: write data using the /api/v3 HTTP API
|
||||
|
||||
The following examples show how to write data using `curl` and the `/api/3/write_lp` HTTP endpoint.
|
||||
To show the difference between accepting and rejecting partial writes, line `2` in the example contains a `string` value (`"hi"`) for a `float` field (`temp`).
|
||||
|
||||
###### Partial write of line protocol occurred
|
||||
|
||||
With `accept_partial=true` (default):
|
||||
|
||||
```bash
|
||||
curl -v "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto" \
|
||||
--header 'Authorization: Bearer apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0==' \
|
||||
--data-raw 'home,room=Sunroom temp=96
|
||||
home,room=Sunroom temp="hi"'
|
||||
```
|
||||
|
||||
The response is the following:
|
||||
|
||||
```
|
||||
< HTTP/1.1 400 Bad Request
|
||||
...
|
||||
{
|
||||
"error": "partial write of line protocol occurred",
|
||||
"data": [
|
||||
{
|
||||
"original_line": "home,room=Sunroom temp=hi",
|
||||
"line_number": 2,
|
||||
"error_message": "invalid column type for column 'temp', expected iox::column_type::field::float, got iox::column_type::field::string"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Line `1` is written and queryable.
|
||||
The response is an HTTP error (`400`) status, and the response body contains the error message `partial write of line protocol occurred` with details about the problem line.
|
||||
|
||||
###### Parsing failed for write_lp endpoint
|
||||
|
||||
With `accept_partial=false`:
|
||||
|
||||
```bash
|
||||
curl -v "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto&accept_partial=false" \
|
||||
--header 'Authorization: Bearer apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0==' \
|
||||
--data-raw 'home,room=Sunroom temp=96
|
||||
home,room=Sunroom temp="hi"'
|
||||
```
|
||||
|
||||
The response is the following:
|
||||
|
||||
```
|
||||
< HTTP/1.1 400 Bad Request
|
||||
...
|
||||
{
|
||||
"error": "parsing failed for write_lp endpoint",
|
||||
"data": {
|
||||
"original_line": "home,room=Sunroom temp=hi",
|
||||
"line_number": 2,
|
||||
"error_message": "invalid column type for column 'temp', expected iox::column_type::field::float, got iox::column_type::field::string"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
InfluxDB rejects all points in the batch.
|
||||
The response is an HTTP error (`400`) status, and the response body contains `parsing failed for write_lp endpoint` and details about the problem line.
|
||||
|
||||
For more information about the ingest path and data flow, see [Data durability](/influxdb3/version/reference/internals/durability/).
|
||||
<!------------ END /api/v3/write_lp -------------->
|
||||
{{% /tab-content %}}
|
||||
{{% tab-content %}}
|
||||
<!------------ BEGIN /api/v2/write -------------->
|
||||
The `/api/v2/write` InfluxDB v2 compatibility endpoint provides backwards compatibility with clients (such as [Telegraf's InfluxDB v2 output plugin](/telegraf/v1/plugins/#output-influxdb_v2) and [InfluxDB v2 API client libraries](/influxdb3/version/reference/client-libraries/v2/)) that can write data to InfluxDB OSS v2.x and Cloud 2 (TSM).
|
||||
|
||||
{{<api-endpoint endpoint="/api/v2/write?bucket=mydb&precision=ns" method="post" >}}
|
||||
<!------------ END /api/v2/write -------------->
|
||||
{{% /tab-content %}}
|
||||
|
||||
{{% tab-content %}}
|
||||
<!------------ BEGIN /write (v1) ---------------->
|
||||
The `/write` InfluxDB v1 compatibility endpoint provides backwards compatibility for clients that can write data to InfluxDB v1.x.
|
||||
|
||||
{{<api-endpoint endpoint="/write?db=mydb&precision=ns" method="post" >}}
|
||||
|
||||
<!------------ END /write (v1) ---------------->
|
||||
{{% /tab-content %}}
|
||||
{{% /tabs-wrapper %}}
|
||||
|
||||
> [!Note]
|
||||
> #### Compatibility APIs differ from native APIs
|
||||
>
|
||||
> Keep in mind that the compatibility APIs differ from the v1 and v2 APIs in previous versions in the following ways:
|
||||
>
|
||||
> - Tags in a table (measurement) are _immutable_
|
||||
> - A tag and a field can't have the same name within a table.
|
||||
|
||||
#### Write responses
|
||||
|
||||
By default, InfluxDB acknowledges writes after flushing the WAL file to the object store (occurring every second).
|
||||
For high write throughput, you can send multiple concurrent write requests.
|
||||
|
||||
#### Use no_sync for immediate write responses
|
||||
|
||||
To reduce the latency of writes, use the `no_sync` write option, which acknowledges writes _before_ WAL persistence completes.
|
||||
When `no_sync=true`, InfluxDB validates the data, writes the data to the WAL, and then immediately responds to the client, without waiting for persistence to the object store.
|
||||
|
||||
Using `no_sync=true` is best when prioritizing high-throughput writes over absolute durability.
|
||||
|
||||
- Default behavior (`no_sync=false`): Waits for data to be written to the object store before acknowledging the write. Reduces the risk of data loss, but increases the latency of the response.
|
||||
- With `no_sync=true`: Reduces write latency, but increases the risk of data loss in case of a crash before WAL persistence.
|
||||
|
||||
##### Immediate write using the HTTP API
|
||||
|
||||
The `no_sync` parameter controls when writes are acknowledged--for example:
|
||||
|
||||
```bash
|
||||
curl "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto&no_sync=true" \
|
||||
--header 'Authorization: Bearer apiv3_0xxx0o0XxXxx00Xxxx000xXXxoo0==' \
|
||||
--data-raw "home,room=Sunroom temp=96"
|
||||
```
|
||||
|
||||
### Create a database or table
|
||||
|
||||
To create a database without writing data, use the `create` subcommand--for example:
|
||||
|
||||
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
|
||||
```bash
|
||||
influxdb3 create database DATABASE_NAME \
|
||||
--token AUTH_TOKEN
|
||||
```
|
||||
{{% /code-placeholders %}}
|
||||
|
||||
Replace the following placeholders with your values:
|
||||
|
||||
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create
|
||||
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: the {{% token-link "admin" %}} for your {{% product-name %}} server
|
||||
|
||||
To learn more about a subcommand, use the `-h, --help` flag or view the [InfluxDB 3 CLI reference](/influxdb3/version/reference/cli/influxdb3/create):
|
||||
|
||||
```bash
|
||||
influxdb3 create -h
|
||||
```
|
||||
{{% page-nav
|
||||
prev="/influxdb3/version/get-started/setup/"
|
||||
prevText="Set up InfluxDB"
|
||||
next="/influxdb3/version/get-started/query/"
|
||||
nextText="Query data"
|
||||
%}}
|
||||
|
|
|
|||
|
|
@ -15,8 +15,9 @@ to line protocol.
|
|||
>
|
||||
> #### Choose the write endpoint for your workload
|
||||
>
|
||||
> When creating new write workloads, use the HTTP API
|
||||
> [`/api/v3/write_lp` endpoint with client libraries](/influxdb3/version/write-data/api-client-libraries/).
|
||||
> 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).
|
||||
|
|
|
|||
|
|
@ -1,129 +1,6 @@
|
|||
Use the `/api/v3/write_lp` HTTP API endpoint and InfluxDB v3 API clients to write points as line protocol data to {{% product-name %}}.
|
||||
|
||||
- [Use the /api/v3/write\_lp endpoint](#use-the-apiv3write_lp-endpoint)
|
||||
- [Example: write data using the /api/v3 HTTP API](#example-write-data-using-the-apiv3-http-api)
|
||||
- [Write responses](#write-responses)
|
||||
- [Use no\_sync for immediate write responses](#use-no_sync-for-immediate-write-responses)
|
||||
- [Use API client libraries](#use-api-client-libraries)
|
||||
- [Construct line protocol](#construct-line-protocol)
|
||||
- [Set up your project](#set-up-your-project)
|
||||
|
||||
## Use the /api/v3/write_lp endpoint
|
||||
|
||||
{{% product-name %}} adds the `/api/v3/write_lp` endpoint.
|
||||
|
||||
{{<api-endpoint endpoint="/api/v3/write_lp?db=mydb&precision=nanosecond&accept_partial=true&no_sync=false" method="post" >}}
|
||||
|
||||
This endpoint accepts the same line protocol syntax as [previous versions](/influxdb3/version/write-data/compatibility-apis/),
|
||||
and supports the following parameters:
|
||||
|
||||
- `?accept_partial=<BOOLEAN>`: Accept or reject partial writes (default is `true`).
|
||||
- `?no_sync=<BOOLEAN>`: Control when writes are acknowledged:
|
||||
- `no_sync=true`: Acknowledge writes before WAL persistence completes.
|
||||
- `no_sync=false`: Acknowledges writes after WAL persistence completes (default).
|
||||
- `?precision=<PRECISION>`: Specify the precision of the timestamp. The default is nanosecond precision.
|
||||
|
||||
For more information about the parameters, see [Write data](/influxdb3/version/write-data/).
|
||||
|
||||
InfluxData provides supported InfluxDB 3 client libraries that you can integrate with your code
|
||||
to construct data as time series points, and then write them as line protocol to an {{% product-name %}} database.
|
||||
For more information, see how to [use InfluxDB client libraries to write data](/influxdb3/version/write-data/client-libraries/).
|
||||
|
||||
### Example: write data using the /api/v3 HTTP API
|
||||
|
||||
The following examples show how to write data using `curl` and the `/api/3/write_lp` HTTP endpoint.
|
||||
To show the difference between accepting and rejecting partial writes, line `2` in the example contains a string value (`"hi"`) for a float field (`temp`).
|
||||
|
||||
#### Partial write of line protocol occurred
|
||||
|
||||
With `accept_partial=true` (default):
|
||||
|
||||
```bash
|
||||
curl -v "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto" \
|
||||
--data-raw 'home,room=Sunroom temp=96
|
||||
home,room=Sunroom temp="hi"'
|
||||
```
|
||||
|
||||
The response is the following:
|
||||
|
||||
```
|
||||
< HTTP/1.1 400 Bad Request
|
||||
...
|
||||
{
|
||||
"error": "partial write of line protocol occurred",
|
||||
"data": [
|
||||
{
|
||||
"original_line": "home,room=Sunroom temp=hi",
|
||||
"line_number": 2,
|
||||
"error_message": "invalid column type for column 'temp', expected iox::column_type::field::float, got iox::column_type::field::string"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Line `1` is written and queryable.
|
||||
Line `2` is rejected.
|
||||
The response is an HTTP error (`400`) status, and the response body contains the error message `partial write of line protocol occurred` with details about the problem line.
|
||||
|
||||
#### Parsing failed for write_lp endpoint
|
||||
|
||||
With `accept_partial=false`:
|
||||
|
||||
```bash
|
||||
curl -v "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto&accept_partial=false" \
|
||||
--data-raw 'home,room=Sunroom temp=96
|
||||
home,room=Sunroom temp="hi"'
|
||||
```
|
||||
|
||||
The response is the following:
|
||||
|
||||
```
|
||||
< HTTP/1.1 400 Bad Request
|
||||
...
|
||||
{
|
||||
"error": "parsing failed for write_lp endpoint",
|
||||
"data": {
|
||||
"original_line": "home,room=Sunroom temp=hi",
|
||||
"line_number": 2,
|
||||
"error_message": "invalid column type for column 'temp', expected iox::column_type::field::float, got iox::column_type::field::string"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
InfluxDB rejects all points in the batch.
|
||||
The response is an HTTP error (`400`) status, and the response body contains `parsing failed for write_lp endpoint` and details about the problem line.
|
||||
|
||||
For more information about the ingest path and data flow, see [Data durability](/influxdb3/version/reference/internals/durability/).
|
||||
|
||||
### Write responses
|
||||
|
||||
By default, InfluxDB acknowledges writes after flushing the WAL file to the Object store (occurring every second).
|
||||
For high write throughput, you can send multiple concurrent write requests.
|
||||
|
||||
### Use no_sync for immediate write responses
|
||||
|
||||
To reduce the latency of writes, use the `no_sync` write option, which acknowledges writes _before_ WAL persistence completes.
|
||||
When `no_sync=true`, InfluxDB validates the data, writes the data to the WAL, and then immediately responds to the client, without waiting for persistence to the Object store.
|
||||
|
||||
Using `no_sync=true` is best when prioritizing high-throughput writes over absolute durability.
|
||||
|
||||
- Default behavior (`no_sync=false`): Waits for data to be written to the Object store before acknowledging the write. Reduces the risk of data loss, but increases the latency of the response.
|
||||
- With `no_sync=true`: Reduces write latency, but increases the risk of data loss in case of a crash before WAL persistence.
|
||||
|
||||
#### Immediate write using the HTTP API
|
||||
|
||||
The `no_sync` parameter controls when writes are acknowledged--for example:
|
||||
|
||||
```bash
|
||||
curl "http://localhost:8181/api/v3/write_lp?db=sensors&precision=auto&no_sync=true" \
|
||||
--data-raw "home,room=Sunroom temp=96"
|
||||
```
|
||||
|
||||
## Use API client libraries
|
||||
|
||||
Use InfluxDB 3 client libraries that integrate with your code to construct data
|
||||
as time series points, and
|
||||
then write them as line protocol to an {{% product-name %}} database.
|
||||
as time series points, and then write them as line protocol to an
|
||||
{{% product-name %}} database.
|
||||
|
||||
- [Construct line protocol](#construct-line-protocol)
|
||||
- [Example home schema](#example-home-schema)
|
||||
|
|
@ -148,7 +25,7 @@ sensor collects temperature, humidity, and carbon monoxide readings.
|
|||
|
||||
To collect this data, use the following schema:
|
||||
|
||||
<!-- vale InfluxDataDocs.v3Schema = NO -->
|
||||
<!-- vale InfluxDataDocs.v3Schema = YES -->
|
||||
|
||||
- **table**: `home`
|
||||
- **tags**
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Use the InfluxDB HTTP API to write data to {{< product-name >}}.
|
||||
There are different APIs you can use depending on your integration method.
|
||||
|
||||
{{< children >}}
|
||||
|
|
@ -15,14 +15,15 @@ to write points as line protocol data to {{% product-name %}}.
|
|||
|
||||
## InfluxDB v2 compatibility
|
||||
|
||||
The `/api/v2/write` InfluxDB v2 compatibility endpoint provides backwards compatibility with clients that can write data to InfluxDB OSS v2.x and Cloud 2 (TSM).
|
||||
The `/api/v2/write` InfluxDB v2 compatibility endpoint provides backwards
|
||||
compatibility with clients that can write data to InfluxDB OSS v2.x and Cloud 2 (TSM).
|
||||
|
||||
{{<api-endpoint endpoint="/api/v2/write?bucket=mydb&precision=ns" method="post" >}}
|
||||
{{<api-endpoint endpoint="/api/v2/write?bucket=mydb&precision=ns" method="post" api-ref="/influxdb3/version/api/v3/#operation/PostV1Write" >}}
|
||||
|
||||
|
||||
## InfluxDB v1 compatibility
|
||||
|
||||
The `/write` InfluxDB v1 compatibility endpoint provides backwards compatibility with clients that can write data to InfluxDB v1.x.
|
||||
|
||||
{{<api-endpoint endpoint="/write?db=mydb&precision=ns" method="post" >}}
|
||||
{{<api-endpoint endpoint="/write?db=mydb&precision=ns" method="post" api-ref="/influxdb3/version/api/v3/#operation/PostV2Write" >}}
|
||||
|
||||
|
|
@ -0,0 +1,162 @@
|
|||
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
|
||||
|
||||
- `?accept_partial=<BOOLEAN>`: Accept or reject partial writes (default is `true`).
|
||||
- `?no_sync=<BOOLEAN>`: Control when writes are acknowledged:
|
||||
- `no_sync=true`: Acknowledge writes before WAL persistence completes.
|
||||
- `no_sync=false`: Acknowledges writes after WAL persistence completes (default).
|
||||
- `?precision=<PRECISION>`: Specify the precision of the timestamp.
|
||||
The default is `ns` (nanosecond) precision.
|
||||
You can also use `auto` to let InfluxDB automatically determine the timestamp
|
||||
precision by identifying which precisions resolves most closely to _now_.
|
||||
|
||||
##### Request body
|
||||
|
||||
- Line protocol
|
||||
|
||||
{{<api-endpoint endpoint="/api/v3/write_lp?db=mydb&precision=nanosecond&accept_partial=true&no_sync=false" method="post" >}}
|
||||
|
||||
_The following example uses [cURL](https://curl.se/) to send a write request using
|
||||
the {{< influxdb3/home-sample-link >}}, but you can use any HTTP client._
|
||||
|
||||
{{% influxdb/custom-timestamps %}}
|
||||
```bash
|
||||
curl -v "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto" \
|
||||
--data-raw "home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1735545600
|
||||
home,room=Kitchen temp=21.0,hum=35.9,co=0i 1735545600
|
||||
home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1735549200
|
||||
home,room=Kitchen temp=23.0,hum=36.2,co=0i 1735549200
|
||||
home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1735552800
|
||||
home,room=Kitchen temp=22.7,hum=36.1,co=0i 1735552800
|
||||
home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1735556400
|
||||
home,room=Kitchen temp=22.4,hum=36.0,co=0i 1735556400
|
||||
home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1735560000
|
||||
home,room=Kitchen temp=22.5,hum=36.0,co=0i 1735560000
|
||||
home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1735563600
|
||||
home,room=Kitchen temp=22.8,hum=36.5,co=1i 1735563600
|
||||
home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1735567200
|
||||
home,room=Kitchen temp=22.8,hum=36.3,co=1i 1735567200
|
||||
home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1735570800
|
||||
home,room=Kitchen temp=22.7,hum=36.2,co=3i 1735570800
|
||||
home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1735574400
|
||||
home,room=Kitchen temp=22.4,hum=36.0,co=7i 1735574400
|
||||
home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1735578000
|
||||
home,room=Kitchen temp=22.7,hum=36.0,co=9i 1735578000
|
||||
home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1735581600
|
||||
home,room=Kitchen temp=23.3,hum=36.9,co=18i 1735581600
|
||||
home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1735585200
|
||||
home,room=Kitchen temp=23.1,hum=36.6,co=22i 1735585200
|
||||
home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1735588800
|
||||
home,room=Kitchen temp=22.7,hum=36.5,co=26i 1735588800"
|
||||
```
|
||||
{{% /influxdb/custom-timestamps %}}
|
||||
|
||||
- [Partial writes](#partial-writes)
|
||||
- [Accept partial writes](#accept-partial-writes)
|
||||
- [Do not accept partial writes](#do-not-accept-partial-writes)
|
||||
- [Write responses](#write-responses)
|
||||
- [Use no_sync for immediate write responses](#use-no_sync-for-immediate-write-responses)
|
||||
|
||||
> [!Note]
|
||||
> #### InfluxDB client libraries
|
||||
>
|
||||
> InfluxData provides supported InfluxDB 3 client libraries that you can
|
||||
> integrate with your code to construct data as time series points, and then
|
||||
> write them as line protocol to an {{% product-name %}} database.
|
||||
> For more information, see how to [use InfluxDB client libraries to write data](/influxdb3/version/write-data/client-libraries/).
|
||||
|
||||
## Partial writes
|
||||
|
||||
The `/api/v3/write_lp` endpoint lets you accept or reject partial writes using
|
||||
the `accept_partial` parameter. This parameter changes the behavior of the API
|
||||
when the write request contains invalid line protocol or schema conflicts.
|
||||
|
||||
For example, the following line protocol contains two points, each using a
|
||||
different datatype for the `temp` field, which causes a schema conflict:
|
||||
|
||||
```
|
||||
home,room=Sunroom temp=96 1735545600
|
||||
home,room=Sunroom temp="hi" 1735549200
|
||||
```
|
||||
|
||||
### Accept partial writes
|
||||
|
||||
With `accept_partial=true` (default), InfluxDB:
|
||||
|
||||
- Accepts and writes line `1`
|
||||
- Rejects line `2`
|
||||
- Returns a `400 Bad Request` status code and the following response body:
|
||||
|
||||
```
|
||||
< HTTP/1.1 400 Bad Request
|
||||
...
|
||||
{
|
||||
"error": "partial write of line protocol occurred",
|
||||
"data": [
|
||||
{
|
||||
"original_line": "home,room=Sunroom temp=hi 1735549200",
|
||||
"line_number": 2,
|
||||
"error_message": "invalid column type for column 'temp', expected iox::column_type::field::float, got iox::column_type::field::string"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Do not accept partial writes
|
||||
|
||||
With `accept_partial=false`, InfluxDB:
|
||||
|
||||
- Rejects _all_ points in the batch
|
||||
- Returns a `400 Bad Request` status code and the following response body:
|
||||
|
||||
```
|
||||
< HTTP/1.1 400 Bad Request
|
||||
...
|
||||
{
|
||||
"error": "parsing failed for write_lp endpoint",
|
||||
"data": {
|
||||
"original_line": "home,room=Sunroom temp=hi 1735549200",
|
||||
"line_number": 2,
|
||||
"error_message": "invalid column type for column 'temp', expected iox::column_type::field::float, got iox::column_type::field::string"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
_For more information about the ingest path and data flow, see
|
||||
[Data durability](/influxdb3/version/reference/internals/durability/)._
|
||||
|
||||
## Write responses
|
||||
|
||||
By default, {{% product-name %}} acknowledges writes after flushing the WAL file
|
||||
to the Object store (occurring every second).
|
||||
For high write throughput, you can send multiple concurrent write requests.
|
||||
|
||||
### Use no_sync for immediate write responses
|
||||
|
||||
To reduce the latency of writes, use the `no_sync` write option, which
|
||||
acknowledges writes _before_ WAL persistence completes.
|
||||
When `no_sync=true`, InfluxDB validates the data, writes the data to the WAL,
|
||||
and then immediately responds to the client, without waiting for persistence to
|
||||
the Object store.
|
||||
|
||||
> [!Tip]
|
||||
> Using `no_sync=true` is best when prioritizing high-throughput writes over
|
||||
> absolute durability.
|
||||
|
||||
- Default behavior (`no_sync=false`): Waits for data to be written to the Object
|
||||
store before acknowledging the write. Reduces the risk of data loss, but
|
||||
increases the latency of the response.
|
||||
- With `no_sync=true`: Reduces write latency, but increases the risk of data
|
||||
loss in case of a crash before WAL persistence.
|
||||
|
||||
The following example immediately returns a response without waiting for WAL
|
||||
persistence:
|
||||
|
||||
```bash
|
||||
curl "http://localhost:8181/api/v3/write_lp?db=sensors&no_sync=true" \
|
||||
--data-raw "home,room=Sunroom temp=96"
|
||||
```
|
||||
|
|
@ -9,8 +9,9 @@ to write line protocol data to {{< product-name >}}.
|
|||
> #### Use the API for batching and higher-volume writes
|
||||
>
|
||||
> The `influxdb3` CLI lets you quickly get started writing data to {{< product-name >}}.
|
||||
> For batching and higher-volume write workloads, use
|
||||
> [API client libraries](/influxdb3/version/write-data/api/#use-api-client-libraries)
|
||||
> For batching and higher-volume write workloads, use the
|
||||
> [InfluxDB HTTP API](/influxdb3/version/write-data/http-api),
|
||||
> [API client libraries](/influxdb3/version/write-data/client-libraries/)
|
||||
> or [Telegraf](/influxdb3/version/write-data/use-telegraf/).
|
||||
|
||||
## Construct line protocol
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ Write requests return the following status codes:
|
|||
| :-------------------------------| :--------------------------------------------------------------- | :------------- |
|
||||
| `204 "Success"` | | If InfluxDB ingested the data |
|
||||
| `400 "Bad request"` | error details about rejected points, up to 100 points: `line` contains the first rejected line, `message` describes rejections | If some or all request data isn't allowed (for example, if it is malformed or falls outside of the bucket's retention period)--the response body indicates whether a partial write has occurred or if all data has been rejected |
|
||||
| `401 "Unauthorized"` | | If the `Authorization` header is missing or malformed or if the [token](/influxdb3/version/admin/tokens/) doesn't have [permission](/influxdb3/version/reference/cli/influxctl/token/create/#examples) to write to the database. See [examples using credentials](/influxdb3/version/write-data/api-client-libraries/) in write requests. |
|
||||
| `401 "Unauthorized"` | | If the `Authorization` header is missing or malformed or if the [token](/influxdb3/version/admin/tokens/) doesn't have [permission](/influxdb3/version/reference/cli/influxctl/token/create/#examples) to write to the database. See [examples using credentials](/influxdb3/version/write-data/client-libraries/) in write requests. |
|
||||
| `404 "Not found"` | requested **resource type** (for example, "organization" or "database"), and **resource name** | If a requested resource (for example, organization or database) wasn't found |
|
||||
| `500 "Internal server error"` | | Default status for an error |
|
||||
| `503` "Service unavailable" | | If the server is temporarily unavailable to accept writes. The `Retry-After` header describes when to try the write again.
|
||||
|
|
|
|||
Loading…
Reference in New Issue