Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

feature(v3): Cloud Dedicated write API: partial writes write good lines and reject bad li… (#5273) 

* feature(v3): Write: partial writes write good lines and reject bad lines #5160

- Documents the proposed partial writes feature for Serverless and Dedicated.
- Updates Troubleshoot writes and API docs.

* chore(v3): update write status codes (#5160)

* Update content/influxdb/cloud-serverless/write-data/troubleshoot.md

* chore(v3): cleanup partial write descriptions in API ref and troubleshooting guide
pull/5283/head
Jason Stirnaman 2023-12-18 12:43:44 -06:00 committed by GitHub
parent 5314f1df57
commit d61107a3d3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 311 additions and 172 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

234
api-docs/cloud-dedicated/ref.yml
View File

@ -1014,11 +1014,11 @@ components:
properties:
description:
description: |
A description of the bucket.
A description of the database.
type: string
name:
description: |
The name of the bucket.
The name of the database.
type: string
retentionRules:
$ref: '#/components/schemas/PatchRetentionRules'
@ -1442,14 +1442,29 @@ paths:
Use this endpoint to send data in [line protocol](/influxdb/cloud-dedicated/reference/syntax/line-protocol/) format to InfluxDB.
InfluxDB does the following when you send a write request:
InfluxDB Cloud Dedicated does the following when you send a write request:
1. Validates the request
2. If successful, attempts to [ingest the data](/influxdb/cloud-dedicated/reference/internals/durability/#data-ingest); _error_ otherwise.
3. If successful, responds with _success_ (HTTP `204` status code), acknowledging that the data is written and queryable; _error_ otherwise.
1. Validates the request.
2. If successful, attempts to [ingest data](/influxdb/cloud-dedicated/reference/internals/durability/#data-ingest) from the request body; otherwise, responds with an [error status](/influxdb/cloud-dedicated/write-data/troubleshoot/#review-http-status-codes).
3. Ingests or rejects data in the batch and returns one of the following HTTP status codes:
To ensure that InfluxDB Cloud handles writes in the order you request them,
wait for a success response (HTTP `2xx` status code) before you send the next request.
- `204 No Content`: all data in the batch is ingested
- `201 Created` (_If the cluster is configured to allow **partial writes**_): some points in the batch are ingested and queryable, and some points are rejected
- `400 Bad Request`: all data is rejected
The response body contains error details about [rejected points](/influxdb/cloud-dedicated/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points.
Writes are synchronous--the response status indicates the final status of the write and all ingested data is queryable.
To ensure that InfluxDB handles writes in the order you request them,
wait for the response before you send the next request.
#### Write endpoints
The [`/write`](#operation/PostLegacyWrite) and [`/api/v2/write`](#operation/PostWrite) endpoints are functionally equivalent for writing data to InfluxDB Cloud Dedicated.
- Use the [`/write` endpoint](#operation/PostLegacyWrite) for [InfluxDB v1 parameter compatibility](/influxdb/cloud-dedicated/guides/api-compatibility/v1/).
- Use the [`/api/v2/write` endpoint](#operation/PostWrite) for [InfluxDB v2 parameter compatibility](/influxdb/cloud-dedicated/guides/api-compatibility/v2/).
#### Related guides
@ -1576,78 +1591,47 @@ paths:
- [Best practices for optimizing writes](/influxdb/cloud-dedicated/write-data/best-practices/optimize-writes/)
required: true
responses:
'204':
'201':
description: |
Success. Data is written and queryable.
'400':
Success ("Created"). Some points in the batch are written and queryable, and some points are rejected. The response body contains details about the [rejected points](/influxdb/cloud-dedicated/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points.
content:
application/json:
examples:
measurementSchemaFieldTypeConflict:
summary: field type conflict thrown by an explicit database schema
partialWriteErrorWithRejectedPoints:
summary: Partial write rejects points with syntax errors
value:
code: invalid
message: 'failed to parse line protocol: error writing line 2: Unable to insert iox::column_type::field::integer type into column temp with type iox::column_type::field::string'
line: 2
message: "failed to parse line protocol:
errors encountered on line(s):
error message for first rejected point</n>
error message for second rejected point</n>
error message for Nth rejected point (up to 100 rejected points)"
schema:
$ref: '#/components/schemas/LineProtocolError'
'204':
description: Success ("No Content"). All data in the batch is written and queryable.
'400':
description: All data in body was rejected and not written.
content:
application/json:
examples:
rejectsAllPoints:
summary: Rejected all points
value:
code: invalid
line: 2
message: "failed to parse line protocol:
errors encountered on line(s):
error message for first rejected point</n>
error message for second rejected point</n>
error message for Nth rejected point (up to 100 rejected points)"
schema:
$ref: '#/components/schemas/LineProtocolError'
description: |
Bad request. The response body contains detail about the error.
InfluxDB returns this error if the line protocol data in the request is malformed or contains a database schema conflict.
The response body contains the first malformed line in the data, and indicates what was expected.
'401':
$ref: '#/components/responses/AuthorizationError'
'404':
$ref: '#/components/responses/ResourceNotFoundError'
'413':
content:
application/json:
examples:
dataExceedsSizeLimitOSS:
summary: InfluxDB OSS response
value: |
{"code":"request too large","message":"unable to read data: points batch is too large"}
schema:
$ref: '#/components/schemas/LineProtocolLengthError'
text/html:
examples:
dataExceedsSizeLimit:
summary: InfluxDB Cloud response
value: |
<html>
<head><title>413 Request Entity Too Large</title></head>
<body>
<center><h1>413 Request Entity Too Large</h1></center>
<hr>
<center>nginx</center>
</body>
</html>
schema:
type: string
description: |
The request payload is too large.
InfluxDB rejected the batch and did not write any data.
InfluxDB returns this error if the payload exceeds the size limit.
'429':
description: |
Too many requests.
#### InfluxDB Cloud
- Returns this error if a **read** or **write** request exceeds your plan's [adjustable service quotas](/influxdb/cloud-dedicated/account-management/limits/#adjustable-service-quotas)
or if a **delete** request exceeds the maximum [global limit](/influxdb/cloud-dedicated/account-management/limits/#global-limits).
- For rate limits that reset automatically, returns a `Retry-After` header that describes when to try the write again.
- For limits that can't reset (for example, **cardinality limit**), doesn't return a `Retry-After` header.
Rates (data-in (writes), queries (reads), and deletes) accrue within a fixed five-minute window.
Once a rate limit is exceeded, InfluxDB returns an error response until the current five-minute window resets.
headers:
Retry-After:
description: Non-negative decimal integer indicating seconds to wait before retrying the request.
schema:
format: int32
type: integer
'500':
$ref: '#/components/responses/InternalServerError'
'503':
@ -1809,9 +1793,45 @@ paths:
summary: Query using the InfluxDB v1 API
tags:
- Query
- Data I/O endpoints
/write:
post:
operationId: PostLegacyWrite
description: |
Writes data to a database.
Use this endpoint for [InfluxDB v1 parameter compatibility](/influxdb/cloud-dedicated/guides/api-compatibility/v1/) when sending data in [line protocol](/influxdb/cloud-dedicated/reference/syntax/line-protocol/) format to InfluxDB.
InfluxDB Cloud Dedicated does the following when you send a write request:
1. Validates the request.
2. If successful, attempts to [ingest data](/influxdb/cloud-dedicated/reference/internals/durability/#data-ingest) from the request body; otherwise, responds with an [error status](/influxdb/cloud-dedicated/write-data/troubleshoot/#review-http-status-codes).
3. Ingests or rejects data in the batch and returns one of the following HTTP status codes:
- `204 No Content`: all data in the batch is ingested
- `201 Created` (_If the cluster is configured to allow **partial writes**_): some points in the batch are ingested and queryable, and some points are rejected
- `400 Bad Request`: all data is rejected
The response body contains error details about [rejected points](/influxdb/cloud-dedicated/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points.
Writes are synchronous--the response status indicates the final status of the write and all ingested data is queryable.
To ensure that InfluxDB handles writes in the order you request them,
wait for the response before you send the next request.
#### Write endpoints
The [`/write`](#operation/PostLegacyWrite) and [`/api/v2/write`](#operation/PostWrite) endpoints are functionally equivalent for writing data to InfluxDB Cloud Dedicated.
- Use the [`/write` endpoint](#operation/PostLegacyWrite) for [InfluxDB v1 parameter compatibility](/influxdb/cloud-dedicated/guides/api-compatibility/v1/).
- Use the [`/api/v2/write` endpoint](#operation/PostWrite) for [InfluxDB v2 parameter compatibility](/influxdb/cloud-dedicated/guides/api-compatibility/v2/).
#### Related guides
- [Get started writing data](/influxdb/cloud-dedicated/get-started/write/)
- [Write data](/influxdb/cloud-dedicated/write-data/)
- [Best practices for writing data](/influxdb/cloud-dedicated/write-data/best-practices/)
- [Troubleshoot issues writing data](/influxdb/cloud-dedicated/write-data/troubleshoot/)
parameters:
- $ref: '#/components/parameters/TraceSpan'
- description: The InfluxDB 1.x username to authenticate the request.
@ -1858,15 +1878,44 @@ paths:
description: Line protocol body
required: true
responses:
'204':
description: Write data is correctly formatted and accepted for writing to the database.
'400':
'201':
description: |
Success ("Created"). Some points in the batch are written and queryable, and some points are rejected. The response body contains details about the [rejected points](/influxdb/cloud-dedicated/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points.
content:
application/json:
examples:
partialWriteErrorWithRejectedPoints:
summary: Partial write rejects points with syntax errors
value:
code: invalid
line: 2
message: "failed to parse line protocol:
errors encountered on line(s):
error message for first rejected point</n>
error message for second rejected point</n>
error message for Nth rejected point (up to 100 rejected points)"
schema:
$ref: '#/components/schemas/LineProtocolError'
description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written.
'401':
'204':
description: Success ("No Content"). All data in the batch is written and queryable.
'400':
description: Bad Request. All data in body was rejected and not written.
content:
application/json:
examples:
rejectsAllPoints:
summary: Rejected all points
value:
code: invalid
line: 2
message: "failed to parse line protocol:
errors encountered on line(s):
error message for first rejected point</n>
error message for second rejected point</n>
error message for Nth rejected point (up to 100 rejected points)"
schema:
$ref: '#/components/schemas/LineProtocolError'
"401":
content:
application/json:
schema:
@ -1906,27 +1955,9 @@ paths:
schema:
$ref: '#/components/schemas/Error'
description: Internal server error
description: |
Writes data to a database.
Use this InfluxDB v1-compatible endpoint to send data in [line protocol](/influxdb/cloud-dedicated/reference/syntax/line-protocol/) format to InfluxDB using v1 API parameters and authorization.
InfluxDB does the following when you send a write request:
1. Validates the request
2. If successful, attempts to [ingest the data](/influxdb/cloud-dedicated/reference/internals/durability/#data-ingest); _error_ otherwise.
3. If successful, responds with _success_ (HTTP `204` status code), acknowledging that the data is written and queryable; _error_ otherwise.
To ensure that InfluxDB handles writes in the order you request them,
wait for a success response (HTTP `2xx` status code) before you send the next request.
#### Related guides
- [Write data with the InfluxDB API](/influxdb/cloud-dedicated/get-started/write/)
- [Optimize writes to InfluxDB](/influxdb/cloud-dedicated/write-data/best-practices/optimize-writes/)
- [Troubleshoot issues writing data](/influxdb/cloud-dedicated/write-data/troubleshoot/)
summary: Write data using the InfluxDB v1 API
tags:
- Data I/O endpoints
- Write
security:
- BearerAuthentication: []
@ -1941,8 +1972,8 @@ tags:
InfluxDB Cloud Dedicated provides the following HTTP API endpoints for writing data:
- **Recommended**: [`/api/v2/write` endpoint](/influxdb/cloud-dedicated/api/#operation/PostWrite) for new write workloads or for bringing existing InfluxDB v2 write workloads to v3.
- [`/write` endpoint](/influxdb/cloud-dedicated/api/#operation/PostLegacyWrite) for bringing existing InfluxDB v1 write workloads to v3.
- **Recommended**: [`/api/v2/write` endpoint](#operation/PostWrite) for new write workloads or for bringing existing InfluxDB v2 write workloads to v3.
- [`/write` endpoint](#operation/PostLegacyWrite) for bringing existing InfluxDB v1 write workloads to v3.
Both endpoints accept the same line protocol format and process data in the same way.
@ -1951,18 +1982,18 @@ tags:
InfluxDB Cloud Dedicated provides the following protocols for executing a query:
- **Recommended**: _Flight+gRPC_ request that contains an SQL or InfluxQL query. See how to [get started querying InfluxDB using Flight and SQL](/influxdb/cloud-dedicated/get-started/query/).
- HTTP API [`/query` request](/influxdb/cloud-dedicated/api/#operation/GetLegacyQuery) that contains an InfluxQL query.
- HTTP API [`/query` request](#operation/GetLegacyQuery) that contains an InfluxQL query.
Use this protocol when bringing existing InfluxDB v1 query workloads to v3.
### InfluxDB v2 compatibility
The HTTP API [`/api/v2/write` endpoint](/influxdb/cloud-dedicated/api/#operation/PostWrite) works with the [`Bearer`](#section/Authentication/BearerAuthentication) and [`Token`](#section/Authentication/TokenAuthentication) authentication schemes and existing InfluxDB 2.x tools and code for [writing data](/influxdb/cloud-dedicated/write-data/).
The HTTP API [`/api/v2/write` endpoint](#operation/PostWrite) works with the [`Bearer`](#section/Authentication/BearerAuthentication) and [`Token`](#section/Authentication/TokenAuthentication) authentication schemes and existing InfluxDB 2.x tools and code for [writing data](/influxdb/cloud-dedicated/write-data/).
See how to [use the InfluxDB v2 API with InfluxDB Cloud Dedicated](/influxdb/cloud-dedicated/guides/api-compatibility/v2/).
### InfluxDB v1 compatibility
The HTTP API [`/write` endpoint](/influxdb/cloud-dedicated/api/#operation/PostLegacyWrite) and [`/query` endpoint](/influxdb/cloud-dedicated/api/#operation/GetLegacyQuery) work with InfluxDB 1.x username/password [authentication schemes](#section/Authentication/) and existing InfluxDB 1.x tools and code.
The HTTP API [`/write` endpoint](#operation/PostLegacyWrite) and [`/query` endpoint](#operation/GetLegacyQuery) work with InfluxDB 1.x username/password [authentication schemes](#section/Authentication/) and existing InfluxDB 1.x tools and code.
See how to [use the InfluxDB v1 API with InfluxDB Cloud Dedicated](/influxdb/cloud-dedicated/guides/api-compatibility/v1/).
name: API compatibility
@ -2010,7 +2041,7 @@ tags:
- description: |
Query data stored in a database.
- HTTP clients can query the v1 [`/query` endpoint](/influxdb/cloud-dedicated/api/#operation/GetLegacyQuery)
- HTTP clients can query the v1 [`/query` endpoint](#operation/GetLegacyQuery)
using **InfluxQL** and retrieve data in **CSV** or **JSON** format.
- The `/api/v2/query` endpoint can't query InfluxDB Cloud Dedicated.
- _Flight + gRPC_ clients can query using **SQL** or **InfluxQL** and retrieve data in **Arrow** format.
@ -2039,14 +2070,13 @@ tags:
| &nbsp;Code&nbsp; | Status | Description |
|:-----------:|:------------------------ |:--------------------- |
| `200` | Success | |
| `204` | Success. No content | InfluxDB doesn't return data for the request. For example, a successful write request returns `204` status code, acknowledging that data is written and queryable. |
| `400` | Bad request | InfluxDB can't parse the request due to an incorrect parameter or bad syntax. If line protocol in the request body is malformed. The response body contains the first malformed line and indicates what was expected. For partial writes, the number of points written and the number of points rejected are also included. |
| `201` | Created | One or more resources are created. The response body contains details about the resource. |
| `204` | No content | The request is successful and no data is returned. For example, The [`/write` and `/api/v2/write` endpoints](#tag/Write) return this status code if all data in the batch is written and queryable. |
| `400` | Bad request | InfluxDB can't parse the request due to an incorrect parameter or bad syntax. For _writes_, the error may indicate one of the following problems: <ul><li>[Rejected points](/influxdb/cloud-dedicated/write-data/troubleshoot/#troubleshoot-rejected-points)</li><li>`Authorization` header is missing or malformed or the API token doesn't have permission for the operation.</li></ul> |
| `401` | Unauthorized | May indicate one of the following: <ul><li>`Authorization: Token` header is missing or malformed</li><li>API token value is missing from the header</li><li>API token doesn't have permission. For more information about token types and permissions, see [Manage tokens](/influxdb/cloud-dedicated/admin/tokens/)</li></ul> |
| `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested resource. |
| `405` | Method not allowed | The API path doesn't support the HTTP method used in the request--for example, you send a `POST` request to an endpoint that only allows `GET`. |
| `413` | Request entity too large | Request payload exceeds the size limit. |
| `422` | Unprocessable entity | Request data is invalid. `code` and `message` in the response body provide details about the problem. |
| `429` | Too many requests | API token is temporarily over the request quota. The `Retry-After` header describes when to try the request again. |
| `500` | Internal server error | |
| `503` | Service unavailable | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. |
name: Response codes

100
api-docs/cloud-serverless/ref.yml
View File

@ -13841,12 +13841,26 @@ paths:
InfluxDB does the following when you send a write request:
1. Validates the request
2. If successful, attempts to [ingest the data](/influxdb/cloud-serverless/reference/internals/durability/#data-ingest); _error_ otherwise.
3. If successful, responds with _success_ (HTTP `204` status code), acknowledging that the data is written and queryable; _error_ otherwise.
1. Validates the request.
2. If successful, attempts to [ingest data](/influxdb/cloud-serverless/reference/internals/durability/#data-ingest) from the request body; otherwise, responds with an [error status](/influxdb/cloud-serverless/write-data/troubleshoot/#review-http-status-codes).
3. Ingests or rejects the entire batch and returns one of the following HTTP status codes:
To ensure that InfluxDB Cloud handles writes in the order you request them,
wait for a success response (HTTP `2xx` status code) before you send the next request.
- `204 No Content`: all data is ingested
- `400 Bad Request`: all data is rejected
The response body contains error details about [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points.
Writes are synchronous--the response status indicates the final status of the write and all ingested data is queryable.
To ensure that InfluxDB handles writes in the order you request them,
wait for the response before you send the next request.
#### Write endpoints
The [`/write`](#operation/PostLegacyWrite) and [`/api/v2/write`](#operation/PostWrite) endpoints are functionally equivalent for writing data to InfluxDB Cloud Serverless.
- Use the [`/write` endpoint](#operation/PostLegacyWrite) for [InfluxDB v1 parameter compatibility](/influxdb/cloud-serverless/guides/api-compatibility/v1/).
- Use [`/api/v2/write` endpoint](#operation/PostWrite) for [InfluxDB v2 parameter compatibility](/influxdb/cloud-serverless/guides/api-compatibility/v2/).
#### Rate limits
@ -14237,6 +14251,44 @@ paths:
/write:
post:
operationId: PostLegacyWrite
description: |
Writes data to a bucket.
Use this endpoint for [InfluxDB v1 parameter compatibility](/influxdb/cloud-serverless/guides/api-compatibility/v1/) when sending data in [line protocol](/influxdb/cloud-serverless/reference/syntax/line-protocol/) format to InfluxDB.
InfluxDB Cloud Serverless does the following when you send a write request:
1. Validates the request.
2. If successful, attempts to [ingest data](/influxdb/cloud-serverless/reference/internals/durability/#data-ingest) from the request body; otherwise, responds with an [error status](/influxdb/cloud-serverless/write-data/troubleshoot/#review-http-status-codes).
3. Ingests or rejects the entire batch and returns one of the following HTTP status codes:
- `204 No Content`: all data is ingested
- `400 Bad Request`: all data is rejected
The response body contains error details about [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points.
Writes are synchronous--the response status indicates the final status of the write and all ingested data is queryable.
To ensure that InfluxDB handles writes in the order you request them,
wait for the response before you send the next request.
#### Write endpoints
The [`/write`](#operation/PostLegacyWrite) and [`/api/v2/write`](#operation/PostWrite) endpoints are functionally equivalent for writing data to InfluxDB Cloud Serverless.
- Use the [`/write` endpoint](#operation/PostLegacyWrite) for [InfluxDB v1 parameter compatibility](/influxdb/cloud-serverless/guides/api-compatibility/v1/).
- Use [`/api/v2/write` endpoint](#operation/PostWrite) for [InfluxDB v2 parameter compatibility](/influxdb/cloud-serverless/guides/api-compatibility/v2/).
#### Rate limits
_Write_ rate limits apply.
For more information, see [limits and adjustable quotas](/influxdb/cloud-serverless/admin/billing/limits/).
#### Related guides
- [Write data with the InfluxDB API](/influxdb/cloud-serverless/get-started/write/)
- [Optimize writes to InfluxDB](/influxdb/cloud-serverless/write-data/best-practices/optimize-writes/)
- [Troubleshoot issues writing data](/influxdb/cloud-serverless/write-data/troubleshoot/)
parameters:
- $ref: '#/components/parameters/TraceSpan'
- description: The InfluxDB 1.x username to authenticate the request.
@ -14284,7 +14336,7 @@ paths:
required: true
responses:
'204':
description: Write data is correctly formatted and accepted for writing to the bucket.
description: Success. Data is ingested and queryable.
'400':
content:
application/json:
@ -14331,30 +14383,6 @@ paths:
schema:
$ref: '#/components/schemas/Error'
description: Internal server error
description: |
Writes data to a bucket.
Use this InfluxDB v1-compatible endpoint to send data in [line protocol](/influxdb/cloud-serverless/reference/syntax/line-protocol/) format to InfluxDB using v1 API parameters and authorization.
InfluxDB does the following when you send a write request:
1. Validates the request
2. If successful, attempts to [ingest the data](/influxdb/cloud-serverless/reference/internals/durability/#data-ingest); _error_ otherwise.
3. If successful, responds with _success_ (HTTP `204` status code), acknowledging that the data is written and queryable; _error_ otherwise.
To ensure that InfluxDB handles writes in the order you request them,
wait for a success response (HTTP `2xx` status code) before you send the next request.
#### Rate limits
`write` rate limits apply.
For more information, see [limits and adjustable quotas](/influxdb/cloud-serverless/admin/billing/limits/).
#### Related guides
- [Write data with the InfluxDB API](/influxdb/cloud-serverless/get-started/write/)
- [Optimize writes to InfluxDB](/influxdb/cloud-serverless/write-data/best-practices/optimize-writes/)
- [Troubleshoot issues writing data](/influxdb/cloud-serverless/write-data/troubleshoot/)
summary: Write data using the InfluxDB v1 API
tags:
- Write
@ -14368,9 +14396,9 @@ tags:
InfluxDB Cloud Serverless provides the following HTTP API endpoints for writing data:
- **Recommended**: `/api/v2/write` endpoint
- **Recommended**: [`/api/v2/write` endpoint](#operation/PostWrite)
for new write workloads or for bringing existing InfluxDB v2 write workloads to v3.
- [`/write` endpoint]((/influxdb/cloud-serverless/api/#operation/PostLegacyWrite)) for bringing existing InfluxDB v1 write workloads to v3.
- [`/write` endpoint](#operation/PostLegacyWrite) for bringing existing InfluxDB v1 write workloads to v3.
Both endpoints accept the same line protocol format and process data in the same way.
@ -14384,13 +14412,13 @@ tags:
### InfluxDB v2 compatibility
The HTTP API [`/api/v2/write` endpoint](/influxdb/cloud-serverless/api/#operation/PostWrite) works with the [`Token` authentication scheme](#section/Authentication/TokenAuthentication) and existing InfluxDB 2.x tools and code for [writing data](/influxdb/cloud-serverless/write-data/).
The HTTP API [`/api/v2/write` endpoint](#operation/PostWrite) works with the [`Token` authentication scheme](#section/Authentication/TokenAuthentication) and existing InfluxDB 2.x tools and code for [writing data](/influxdb/cloud-serverless/write-data/).
See how to [use the InfluxDB v2 API with InfluxDB Cloud Serverless](/influxdb/cloud-serverless/guides/api-compatibility/v2/).
### InfluxDB v1 compatibility
The HTTP API [`/write` endpoint](/influxdb/cloud-serverless/api/#operation/PostLegacyWrite) and [`/query` endpoint](/influxdb/cloud-serverless/api/#operation/GetLegacyQuery) work with InfluxDB 1.x username/password [authentication schemes](#section/Authentication/) and existing InfluxDB 1.x tools and code.
The HTTP API [`/write` endpoint](#operation/PostLegacyWrite) and [`/query` endpoint](#operation/GetLegacyQuery) work with InfluxDB 1.x username/password [authentication schemes](#section/Authentication/) and existing InfluxDB 1.x tools and code.
See how to [use the InfluxDB v1 API with InfluxDB Cloud Serverless](/influxdb/cloud-serverless/guides/api-compatibility/v1/).
name: API compatibility
@ -14601,8 +14629,8 @@ tags:
| &nbsp;Code&nbsp; | Status | Description |
|:-----------:|:------------------------ |:--------------------- |
| `200` | Success | |
| `204` | Success. No content | InfluxDB doesn't return data for the request. For example, a successful write request returns `204` status code, acknowledging that data is written and queryable. |
| `400` | Bad request | InfluxDB can't parse the request due to an incorrect parameter or bad syntax. For _writes_, the error may indicate one of the following problems: <ul><li>Line protocol is malformed. The response body contains the first malformed line in the data and indicates what was expected. For partial writes, the number of points written and the number of points rejected are also included.</li><li>`Authorization` header is missing or malformed or the API token doesn't have permission for the operation.</li></ul> |
| `204` | No content | The request is successful and no data is returned. For example, The [`/write` and `/api/v2/write` endpoints](#tag/Write) return this status code if all data in the batch is written and queryable. |
| `400` | Bad request | InfluxDB can't parse the request due to an incorrect parameter or bad syntax. For _writes_, the error may indicate one of the following problems: <ul><li>[Rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points)</li><li>`Authorization` header is missing or malformed or the API token doesn't have permission for the operation.</li></ul> |
| `401` | Unauthorized | May indicate one of the following: <ul><li>`Authorization: Token` header is missing or malformed</li><li>API token value is missing from the header</li><li>API token doesn't have permission. For more information about token types and permissions, see [Manage API tokens](/influxdb/cloud-serverless/security/tokens/)</li></ul> |
| `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested resource. |
| `405` | Method not allowed | The API path doesn't support the HTTP method used in the request--for example, you send a `POST` request to an endpoint that only allows `GET`. |

5
content/influxdb/cloud-dedicated/guides/api-compatibility/v1/_index.md
View File

@ -185,9 +185,8 @@ Replace the following:
## Responses
InfluxDB API responses use standard HTTP status codes.
For successful writes, InfluxDB responds with a `204 No Content` status code.
Error responses contain a JSON object with `code` and `message` properties that describe the error.
InfluxDB HTTP API responses use standard [HTTP status codes](/influxdb/cloud-dedicated/api/#tag/Response-codes).
The response body for [partial writes](/influxdb/cloud-dedicated/write-data/troubleshoot/#troubleshoot-rejected-points) and errors contains a JSON object with `code` and `message` properties that describe the error.
Response body messages may differ across {{% product-name %}} v1 API, v2 API, InfluxDB Cloud, and InfluxDB OSS.
### Error examples

5
content/influxdb/cloud-dedicated/guides/api-compatibility/v2/_index.md
View File

@ -97,9 +97,8 @@ Replace the following:
## Responses
InfluxDB API responses use standard HTTP status codes.
For successful writes, InfluxDB responds with a `204 No Content` status code.
Error responses contain a JSON object with `code` and `message` properties that describe the error.
InfluxDB HTTP API responses use standard [HTTP status codes](/influxdb/cloud-dedicated/api/#tag/Response-codes).
The response body for [partial writes](/influxdb/cloud-dedicated/write-data/troubleshoot/#troubleshoot-rejected-points) and errors contains a JSON object with `code` and `message` properties that describe the error.
Response body messages may differ across {{% product-name %}} v1 API, v2 API, InfluxDB Cloud, and InfluxDB OSS.
### Error examples

74
content/influxdb/cloud-dedicated/write-data/troubleshoot.md
View File

@ -26,34 +26,47 @@ Learn how to avoid unexpected results and recover from errors when writing to {{
## Handle write responses
In {{% product-name %}}, writes are synchronous.
After InfluxDB validates the request and ingests the data, it sends a _success_ response (HTTP `204` status code) as an acknowledgement that the data is written and queryable.
To ensure that InfluxDB handles writes in the order you request them, wait for the acknowledgement before you send the next request.
{{% product-name %}} does the following when you send a write request:
If InfluxDB successfully writes all the request data to the database, it returns _success_ (HTTP `204` status code).
The first rejected point in a batch causes InfluxDB to reject the entire batch and respond with an [HTTP error status](#review-http-status-codes).
1. Validates the request.
2. If successful, attempts to [ingest data](/influxdb/cloud-dedicated/reference/internals/durability/#data-ingest) from the request body; otherwise, responds with an [error status](#review-http-status-codes).
3. Ingests or rejects data in the batch and returns one of the following HTTP status codes:
- `204 No Content`: all data in the batch is ingested
- `201 Created` (_If the cluster is configured to allow **partial writes**_): some points in the batch are ingested and queryable, and some points are rejected
- `400 Bad Request`: all data is rejected
The response body contains error details about [rejected points](#troubleshoot-rejected-points), up to 100 points.
Writes are synchronous--the response status indicates the final status of the write and all ingested data is queryable.
To ensure that InfluxDB handles writes in the order you request them,
wait for the response before you send the next request.
### Review HTTP status codes
InfluxDB uses conventional HTTP status codes to indicate the success or failure of a request.
The `message` property of the response body may contain additional details about the error.
Write requests return the following status codes:
{{< product-name >}} returns one the following HTTP status codes for a write request:
| HTTP response code | Message | Description |
| :-------------------------------| :--------------------------------------------------------------- | :------------- |
| `204 "Success"` | | If InfluxDB ingested the data |
| `400 "Bad request"` | `message` contains the first malformed line | If data is malformed |
| `401 "Unauthorized"` | | If the `Authorization` header is missing or malformed or if the [token](/influxdb/cloud-dedicated/admin/tokens/) doesn't have [permission](/influxdb/cloud-dedicated/reference/cli/influxctl/token/create/#examples) to write to the database. See [examples using credentials](/influxdb/cloud-dedicated/get-started/write/#write-line-protocol-to-influxdb) 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.
| HTTP response code | Response body | Description |
|:------------------------------|:------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `201 "Created"` | error details about rejected points, up to 100 points: `line` contains the first rejected line, `message` describes rejections | _If **partial writes** are configured for the cluster_, and if some of the data is ingested and some of the data is rejected |
| `204 No Content"` | no response body | If InfluxDB ingested all of the data in the batch |
| `400 "Bad request"` | error details about rejected points, up to 100 points: `line` contains the first rejected line, `message` describes rejections line | If request data is malformed |
| `401 "Unauthorized"` | | If the `Authorization` header is missing or malformed or if the [token](/influxdb/cloud-dedicated/admin/tokens/) doesn't have [permission](/influxdb/cloud-dedicated/reference/cli/influxctl/token/create/#examples) to write to the database. See [examples using credentials](/influxdb/cloud-dedicated/get-started/write/#write-line-protocol-to-influxdb) 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 contains the number of seconds to wait before trying the write again.
The `message` property of the response body may contain additional details about the error.
If your data did not write to the database, see how to [troubleshoot rejected points](#troubleshoot-rejected-points).
## Troubleshoot failures
If you notice data is missing in your database, do the following:
- Check the [HTTP status code](#review-http-status-codes) in the response.
- Check the `message` property in the response body for details about the error.
- If the `message` describes a field error, [troubleshoot rejected points](#troubleshoot-rejected-points).
- Verify all lines contain valid syntax ([line protocol](/influxdb/cloud-dedicated/reference/syntax/line-protocol/)).
@ -62,6 +75,37 @@ If you notice data is missing in your database, do the following:
## Troubleshoot rejected points
InfluxDB rejects points that fall within the same partition (default partitioning is measurement and day) as existing bucket data and have a different data type for an existing field.
When writing points from a batch, InfluxDB rejects points that have syntax errors or schema conflicts.
If InfluxDB processes the data in your batch and then rejects points, the [HTTP response](#handle-write-responses) body contains the following properties that describe rejected points:
- `code`: `"invalid"`
- `line`: the line number of the _first_ rejected point in the batch.
- `message`: a string that contains line-separated error messages, one message for each rejected point in the batch, up to 100 rejected points.
InfluxDB rejects points for the following reasons:
- a line protocol parsing error
- an invalid timestamp
- a schema conflict
Schema conflicts occur when you try to write data that contains any of the following:
- a wrong data type: the point falls within the same partition (default partitioning is measurement and day) as existing bucket data and contains a different data type for an existing field
- a tag and a field that use the same key
### Example
The following example shows a response body for a write request that contains two rejected points:
```json
{
"code": "invalid",
"line": 2,
"message": "failed to parse line protocol:
errors encountered on line(s):
error parsing line 2 (1-based): Invalid measurement was provided
error parsing line 4 (1-based): Unable to parse timestamp value '123461000000000000000000000000'"
}
```
Check for [field data type](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#data-types-and-format) differences between the rejected data point and points within the same database and partition--for example, did you attempt to write `string` data to an `int` field?

5
content/influxdb/cloud-serverless/guides/api-compatibility/v1/_index.md
View File

@ -189,9 +189,8 @@ Replace the following:
## Responses
InfluxDB API responses use standard HTTP status codes.
For successful writes, InfluxDB responds with a `204 No Content` status code.
Error responses contain a JSON object with `code` and `message` properties that describe the error.
InfluxDB HTTP API responses use standard [HTTP status codes](/influxdb/cloud-serverless/api/#tag/Response-codes).
The response body for [partial writes](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points) and errors contains a JSON object with `code` and `message` properties that describe the error.
Response body messages may differ across {{% product-name %}} v1 API, v2 API, InfluxDB Cloud, and InfluxDB OSS.
### Error examples

5
content/influxdb/cloud-serverless/guides/api-compatibility/v2/_index.md
View File

@ -81,9 +81,8 @@ Replace the following:
## Responses
InfluxDB API responses use standard HTTP status codes.
For successful writes, InfluxDB responds with a `204 No Content` status code.
Error responses contain a JSON object with `code` and `message` properties that describe the error.
InfluxDB HTTP API responses use standard [HTTP status codes](/influxdb/cloud-serverless/api/#tag/Response-codes).
The response body for [partial writes](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points) and errors contains a JSON object with `code` and `message` properties that describe the error.
Response body messages may differ across {{% product-name %}} v1 API, v2 API, InfluxDB Cloud, and InfluxDB OSS.
### Error examples

55
content/influxdb/cloud-serverless/write-data/troubleshoot.md
View File

@ -28,18 +28,27 @@ Learn how to avoid unexpected results and recover from errors when writing to {{
## Handle write responses
In {{% product-name %}}, writes are synchronous.
After InfluxDB validates the request and ingests the data, it sends a _success_ response (HTTP `204` status code) as an acknowledgement that the data is written and queryable.
To ensure that InfluxDB handles writes in the order you request them, wait for the acknowledgement before you send the next request.
{{% product-name %}} does the following when you send a write request:
If InfluxDB successfully writes all the request data to the database, it returns _success_ (HTTP `204` status code).
The first rejected point in a batch causes InfluxDB to reject the entire batch and respond with an [HTTP error status](#review-http-status-codes).
1. Validates the request.
2. If successful, attempts to [ingest data](/influxdb/cloud-serverless/reference/internals/durability/#data-ingest) from the request body; otherwise, responds with an [error status](#review-http-status-codes).
3. Ingests or rejects the entire batch and returns one of the following HTTP status codes:
- `204 No Content`: all data is ingested
- `400 Bad Request`: all data is rejected
The response body contains error details about [rejected points](#troubleshoot-rejected-points), up to 100 points.
Writes are synchronous--the response status indicates the final status of the write and all ingested data is queryable.
To ensure that InfluxDB handles writes in the order you request them,
wait for the response before you send the next request.
### Review HTTP status codes
InfluxDB uses conventional HTTP status codes to indicate the success or failure of a request.
The `message` property of the response body may contain additional details about the error.
Write requests return the following status codes:
{{< product-name >}} returns one the following HTTP status codes for a write request:
| HTTP response code | Message | Description |
| :-------------------------------| :-----------------------------------------------------------------------| :------------- |
@ -60,6 +69,7 @@ If your data did not write to the bucket, see how to [troubleshoot rejected poin
If you notice data is missing in your database, do the following:
- Check the [HTTP status code](#review-http-status-codes) in the response.
- Check the `message` property in the response body for details about the error.
- If the `message` describes a field error, [troubleshoot rejected points](#troubleshoot-rejected-points).
- Verify all lines contain valid syntax ([line protocol](/influxdb/cloud-serverless/reference/syntax/line-protocol/)).
@ -68,6 +78,37 @@ If you notice data is missing in your database, do the following:
## Troubleshoot rejected points
InfluxDB rejects points that fall within the same partition (measurement and day) as existing bucket data and have a different data type for an existing field.
When writing points from a batch, InfluxDB rejects points that have syntax errors or schema conflicts.
If InfluxDB processes the data in your batch and then rejects points, the [HTTP response](#handle-write-responses) body contains the following properties that describe rejected points:
- `code`: `"invalid"`
- `line`: the line number of the _first_ rejected point in the batch.
- `message`: a string that contains line-separated error messages, one message for each rejected point in the batch, up to 100 rejected points.
InfluxDB rejects points for the following reasons:
- a line protocol parsing error
- an invalid timestamp
- a schema conflict
Schema conflicts occur when you try to write data that contains any of the following:
- a wrong data type: the point falls within the same partition (default partitioning is measurement and day) as existing bucket data and contains a different data type for an existing field
- a tag and a field that use the same key
### Example
The following example shows a response body for a write request that contains two rejected points:
```json
{
"code": "invalid",
"line": 2,
"message": "failed to parse line protocol:
errors encountered on line(s):
error parsing line 2 (1-based): Invalid measurement was provided
error parsing line 4 (1-based): Unable to parse timestamp value '123461000000000000000000000000'"
}
```
Check for [field data type](/influxdb/cloud-serverless/reference/syntax/line-protocol/#data-types-and-format) differences between the rejected data point and points in the bucket that have the same measurement and day--for example, did you attempt to write `string` data to an `int` field?