-5. In the **Create table** dialog, provide a **Table name**.
-6. Make sure the **Use default partitioning** toggle is set to **Off**
-7. Provide the following:
- - **Custom partition template time format**: The time part for partitioning data.
- - _Optional_: **Custom partition template tag parts**: The tag parts for partitioning data.
- - _Optional_: **Custom partition template tag bucket parts**: The tag bucket parts for partitioning data.
-8. _Optional_: To add more parts to the partition template, click the **Add Tag** button.
-9. Click the **Create Table** button to create the table.
+ {{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-create-table-default.png" alt="Create table dialog" />}}
+
+6. In the **Create table** dialog, provide a **Table name**.
+7. Toggle **Use custom partitioning** to **On**.
+ The **Custom partition template** section displays.
+
+ {{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-create-table-custom-partitioning.png" alt="Create table dialog with custom partitioning" />}}
+
+8. Provide the following:
+
+ - **Custom partition template time format**: The time part for partitioning data (yearly, monthly, or daily).
+ - _Optional_: **Custom partition template tag parts**: The [tag parts](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/#tag-part-templates) for partitioning data.
+ - _Optional_: **Custom partition template tag bucket parts**: The [tag bucket parts](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/#tag-bucket-part-templates) for partitioning data.
+9. _Optional_: To add more parts to the partition template, click the **Add Tag** button. For more information, see [Partition template requirements and guidelines](#partition-template-requirements-and-guidelines).
+10. Click the **Create Table** button to create the table.
The new table displays in the list of tables for the cluster.
{{% /tab-content %}}
-
{{% tab-content %}}
1. If you haven't already, [download and install the `influxctl` CLI](/influxdb3/cloud-dedicated/get-started/setup/#download-install-and-configure-the-influxctl-cli).
@@ -220,7 +231,6 @@ Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the [database](/influxdb3/cloud-dedicated/admin/databases/) to create the table in
- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name you want for the new table
{{% /tab-content %}}
-
{{% tab-content %}}
_This example uses [cURL](https://curl.se/) to send a Management HTTP API request, but you can use any HTTP client._
diff --git a/content/influxdb3/cloud-dedicated/reference/admin-ui.md b/content/influxdb3/cloud-dedicated/reference/admin-ui.md
index ca143ff4a..eef8a8cc6 100644
--- a/content/influxdb3/cloud-dedicated/reference/admin-ui.md
+++ b/content/influxdb3/cloud-dedicated/reference/admin-ui.md
@@ -6,7 +6,7 @@ description: >
menu:
influxdb3_cloud_dedicated:
parent: Reference
-weight: 6
+weight: 105
---
The Administrative (Admin) UI for {{% product-name %}} is a browser-based, no-code way to manage your {{% product-name %}} environment and perform administrative tasks, such as creating and managing clusters, databases, and tokens.
diff --git a/content/influxdb3/cloud-dedicated/reference/api/_index.md b/content/influxdb3/cloud-dedicated/reference/api/_index.md
index f1ed454af..806c248ae 100644
--- a/content/influxdb3/cloud-dedicated/reference/api/_index.md
+++ b/content/influxdb3/cloud-dedicated/reference/api/_index.md
@@ -9,7 +9,7 @@ menu:
influxdb3_cloud_dedicated:
parent: Reference
name: InfluxDB HTTP API
-weight: 104
+weight: 105
influxdb3/cloud-dedicated/tags: [api]
---
diff --git a/content/influxdb3/cloud-dedicated/reference/cli/_index.md b/content/influxdb3/cloud-dedicated/reference/cli/_index.md
index 7287515b2..1a9997f4d 100644
--- a/content/influxdb3/cloud-dedicated/reference/cli/_index.md
+++ b/content/influxdb3/cloud-dedicated/reference/cli/_index.md
@@ -10,11 +10,9 @@ menu:
parent: Reference
name: CLIs
weight: 104
-draft: true
+# draft: true
---
-
-
The following command line interfaces (CLIs) are available:
{{< children >}}
diff --git a/content/influxdb3/cloud-dedicated/reference/client-libraries/_index.md b/content/influxdb3/cloud-dedicated/reference/client-libraries/_index.md
index 76fd68ac2..9771b37a0 100644
--- a/content/influxdb3/cloud-dedicated/reference/client-libraries/_index.md
+++ b/content/influxdb3/cloud-dedicated/reference/client-libraries/_index.md
@@ -4,7 +4,7 @@ description: >
InfluxDB client libraries are language-specific tools that integrate with InfluxDB APIs.
View the list of available client libraries.
list_title: API client libraries
-weight: 105
+weight: 106
aliases:
- /influxdb3/cloud-dedicated/reference/api/client-libraries/
- /influxdb3/cloud-dedicated/tools/client-libraries/
diff --git a/content/influxdb3/cloud-serverless/reference/syntax/delete-predicate.md b/content/influxdb3/cloud-serverless/reference/syntax/delete-predicate.md
index 67eb5b02d..dcff10aac 100644
--- a/content/influxdb3/cloud-serverless/reference/syntax/delete-predicate.md
+++ b/content/influxdb3/cloud-serverless/reference/syntax/delete-predicate.md
@@ -5,7 +5,7 @@ description: >
InfluxDB uses an InfluxQL-like predicate syntax to determine what data points to delete.
menu:
influxdb3_cloud_serverless:
- parent: Syntax
+ parent: Other syntaxes
name: Delete predicate
weight: 104
influxdb3/cloud-serverless/tags: [syntax, delete]
diff --git a/content/influxdb3/clustered/_index.md b/content/influxdb3/clustered/_index.md
index dc7d7d656..64079c17a 100644
--- a/content/influxdb3/clustered/_index.md
+++ b/content/influxdb3/clustered/_index.md
@@ -18,7 +18,7 @@ The InfluxDB time series platform is designed to handle high write and query loa
Learn how to use and leverage InfluxDB Clustered for your specific
time series use case.
-Run an {{% product-name %}} proof of concept (PoC)
+Run an {{% product-name %}} proof of concept (PoC)
Get started with InfluxDB Clustered
## InfluxDB 3
diff --git a/content/influxdb3/clustered/admin/backup-restore.md b/content/influxdb3/clustered/admin/backup-restore.md
index e5dfebd7c..d321c81c3 100644
--- a/content/influxdb3/clustered/admin/backup-restore.md
+++ b/content/influxdb3/clustered/admin/backup-restore.md
@@ -55,7 +55,12 @@ snapshot. When a snapshot is restored to the Catalog store, the Compactor
A _soft delete_ refers to when, on compaction, the Compactor sets a `deleted_at`
timestamp on the Parquet file entry in the Catalog.
The Parquet file is no
-longer queryable, but remains intact in the object store.
+longer queryable, but remains intact in the object store.
+
+> [!Note]
+> Soft deletes are a mechanism of the {{% product-name %}} Catalog, not of the
+> underlying object storage provider. Soft deletes do not modify objects in the
+> object store; only Catalog entries that reference objects in the object store.
## Hard delete
@@ -219,6 +224,15 @@ written on or around the beginning of the next hour.
Use the following process to restore your InfluxDB cluster to a recovery point
using Catalog store snapshots:
+> [!Warning]
+>
+> #### Use the same InfluxDB Clustered version used to generate the snapshot
+>
+> When restoring an InfluxDB cluster to a recovery point, use the same version
+> of InfluxDB Clustered used to generate the Catalog store snapshot.
+> You may need to [downgrade to a previous version](/influxdb3/clustered/admin/upgrade/)
+> before restoring.
+
1. **Install prerequisites:**
- `kubectl` CLI for managing your Kubernetes deployment.
@@ -273,7 +287,8 @@ using Catalog store snapshots:
metadata:
name: influxdb
namespace: influxdb
- pause: true
+ spec:
+ pause: true
# ...
```
@@ -331,7 +346,8 @@ using Catalog store snapshots:
metadata:
name: influxdb
namespace: influxdb
- pause: false
+ spec:
+ pause: false
# ...
```
@@ -349,8 +365,6 @@ Your InfluxDB cluster is now restored to the recovery point.
When the Garbage Collector runs, it identifies what Parquet files are not
associated with the recovery point and [soft deletes](#soft-delete) them.
-
-
## Resources
### prep\_pg\_dump.awk
diff --git a/content/influxdb3/clustered/admin/databases/delete.md b/content/influxdb3/clustered/admin/databases/delete.md
index 72c42b14c..9f39e8fd5 100644
--- a/content/influxdb3/clustered/admin/databases/delete.md
+++ b/content/influxdb3/clustered/admin/databases/delete.md
@@ -22,9 +22,9 @@ to delete a database from your InfluxDB cluster.
1. If you haven't already, [download and install the `influxctl` CLI](/influxdb3/clustered/reference/cli/influxctl/#download-and-install-influxctl).
2. Run the `influxctl database delete` command and provide the following:
- - Name of the database to delete
+ - The name of the database to delete
-3. Confirm that you want to delete the database.
+3. Confirm that you want to delete the database.
{{% code-placeholders "DATABASE_NAME" %}}
```sh
@@ -37,9 +37,12 @@ influxctl database delete DATABASE_NAME
>
> Once a database is deleted, data stored in that database cannot be recovered.
>
-> #### Cannot reuse database names
->
-> After a database is deleted, you cannot reuse the same name for a new database.
+> #### Wait before writing to a new database with the same name
+>
+> After deleting a database from your {{% product-name omit=" Clustered" %}}
+> cluster, you can reuse the name to create a new database, but **wait two to
+> three minutes** after deleting the previous database before writing to the new
+> database to allow write caches to clear.
>
> #### Never directly modify the Catalog
>
diff --git a/content/influxdb3/clustered/admin/tokens/database/delete.md b/content/influxdb3/clustered/admin/tokens/database/delete.md
deleted file mode 100644
index cef34cba3..000000000
--- a/content/influxdb3/clustered/admin/tokens/database/delete.md
+++ /dev/null
@@ -1,55 +0,0 @@
----
-title: Delete a database token
-description: >
- Use the [`influxctl token delete` command](/influxdb3/clustered/reference/cli/influxctl/token/delete/)
- to delete a token from your InfluxDB cluster and revoke all
- permissions associated with the token.
- Provide the ID of the token you want to delete.
-menu:
- influxdb3_clustered:
- parent: Database tokens
-weight: 203
-list_code_example: |
- ```sh
- influxctl token delete `value` (Any): Any Python object to cache
`ttl` (Optional[float], default=None): Time in seconds before expiration
`use_global` (bool, default=False): If True, uses global namespace | None | Stores a value in the cache with an optional time-to-live | +| `get` | `key` (str): The key to retrieve
`default` (Any, default=None): Value to return if key not found
`use_global` (bool, default=False): If True, uses global namespace | Any | Retrieves a value from the cache or returns default if not found | +| `delete` | `key` (str): The key to delete
`use_global` (bool, default=False): If True, uses global namespace | bool | Deletes a value from the cache. Returns True if deleted, False if not found | + +### Understanding cache namespaces + +The cache system offers two distinct namespaces: + +| Namespace | Scope | Best For | +| --- | --- | --- | +| **Trigger-specific** (default) | Isolated to a single trigger | Plugin state, counters, timestamps specific to one plugin | +| **Global** | Shared across all triggers | Configuration, lookup tables, service states that should be available to all plugins | + +### Common cache operations + +- [Store and retrieve cached data](#store-and-retrieve-cached-data) +- [Store cached data with expiration](#store-cached-data-with-expiration) +- [Share data across plugins](#share-data-across-plugins) +- [Build a counter](#build-a-counter) + +### Store and retrieve cached data + +```python +# Store a value +influxdb3_local.cache.put("last_run_time", time.time()) + +# Retrieve a value with a default if not found +last_time = influxdb3_local.cache.get("last_run_time", default=0) + +# Delete a cached value +influxdb3_local.cache.delete("temporary_data") +``` + +### Store cached data with expiration + +```python +# Cache with a 5-minute TTL (time-to-live) +influxdb3_local.cache.put("api_response", response_data, ttl=300) +``` + +### Share data across plugins + +```python +# Store in the global namespace +influxdb3_local.cache.put("config", {"version": "1.0"}, use_global=True) + +# Retrieve from the global namespace +config = influxdb3_local.cache.get("config", use_global=True) +``` + +### Building a counter + +You can track how many times a plugin has run: + +```python +# Get current counter or default to 0 +counter = influxdb3_local.cache.get("execution_count", default=0) + +# Increment counter +counter += 1 + +# Store the updated value +influxdb3_local.cache.put("execution_count", counter) + +influxdb3_local.info(f"This plugin has run {counter} times") +``` + +## Guidelines for in-memory caching + +To get the most out of the in-memory cache, follow these guidelines: + +- [Use the trigger-specific namespace](#use-the-trigger-specific-namespace) +- [Use TTL appropriately](#use-ttl-appropriately) +- [Cache computation results](#cache-computation-results) +- [Warm the cache](#warm-the-cache) +- [Consider cache limitations](#consider-cache-limitations) + +### Use the trigger-specific namespace + +The Processing Engine provides a cache that supports stateful operations while maintaining isolation between different triggers. For most use cases, use the trigger-specific namespace to keep plugin state isolated. Use the global namespace only when you need to share data across triggers. + +### Use TTL appropriately + +Set appropriate expiration times based on how frequently your data changes: + +```python +# Cache external API responses for 5 minutes +influxdb3_local.cache.put("weather_data", api_response, ttl=300) +``` + +### Cache computation results + +Store the results of expensive calculations that you frequently utilize: + +```python +# Cache aggregated statistics +influxdb3_local.cache.put("daily_stats", calculate_statistics(data), ttl=3600) +``` + +### Warm the cache + +For critical data, prime the cache at startup. This can be especially useful for global namespace data where multiple triggers need the data: + +```python +# Check if cache needs to be initialized +if not influxdb3_local.cache.get("lookup_table"): + influxdb3_local.cache.put("lookup_table", load_lookup_data()) +``` + +### Consider cache limitations + +- **Memory Usage**: Since the system stores cache contents in memory, monitor your memory usage when caching large datasets. +- **Server Restarts**: Because the server clears the cache on restart, design your plugins to handle cache initialization (as noted above). +- **Concurrency**: Be cautious of accessing inaccurate or out-of-date data when multiple trigger instances might simultaneously update the same cache key. + +## Next Steps + +With an understanding of the InfluxDB 3 Shared Plugin API, you can start building data workflows that transform, analyze, and respond to your time series data. + +To find example plugins you can extend, visit the [influxdb3_plugins repository](https://github.com/influxdata/influxdb3_plugins) on GitHub. \ No newline at end of file diff --git a/content/shared/influxdb-client-libraries-reference/flight/csharp-flight.md b/content/shared/influxdb-client-libraries-reference/flight/csharp-flight.md index 1163b3a2e..ad0984cfd 100644 --- a/content/shared/influxdb-client-libraries-reference/flight/csharp-flight.md +++ b/content/shared/influxdb-client-libraries-reference/flight/csharp-flight.md @@ -8,5 +8,5 @@ For more information, see the [C# client example on GitHub](https://github.com/a > We recommend using the [`influxdb3-csharp` C# client library](/influxdb3/version/reference/client-libraries/v3/csharp/) for integrating InfluxDB 3 with your C# application code. > > [InfluxDB 3 client libraries](/influxdb3/version/reference/client-libraries/v3/) wrap Apache Arrow Flight clients -> and provide convenient methods for [writing](/influxdb3/version/get-started/write/#write-line-protocol-to-influxdb), [querying](/influxdb3/version/get-started/query/#execute-an-sql-query), and processing data stored in {{% product-name %}}. +> and provide convenient methods for [writing](/influxdb3/version/write-data/api-client-libraries/), [querying](/influxdb3/version/query-data/execute-queries/), and processing data stored in {{% product-name %}}. > Client libraries can query using SQL or InfluxQL. diff --git a/content/shared/influxdb-client-libraries-reference/flight/go-flight.md b/content/shared/influxdb-client-libraries-reference/flight/go-flight.md index cc1b97109..93e588f95 100644 --- a/content/shared/influxdb-client-libraries-reference/flight/go-flight.md +++ b/content/shared/influxdb-client-libraries-reference/flight/go-flight.md @@ -6,7 +6,7 @@ > We recommend using the [`influxdb3-go` Go client library](/influxdb3/version/reference/client-libraries/v3/go/) for integrating InfluxDB 3 with your Go application code. > > [InfluxDB 3 client libraries](/influxdb3/version/reference/client-libraries/v3/) wrap Apache Arrow Flight clients -> and provide convenient methods for [writing](/influxdb3/version/get-started/write/#write-line-protocol-to-influxdb), [querying](/influxdb3/version/get-started/query/#execute-an-sql-query), and processing data stored in {{% product-name %}}. +> and provide convenient methods for [writing](/influxdb3/version/write-data/api-client-libraries/), [querying](/influxdb3/version/query-data/execute-queries/), and processing data stored in {{% product-name %}}. > Client libraries can query using SQL or InfluxQL. ## Flight SQL client diff --git a/content/shared/influxdb-client-libraries-reference/flight/java-flightsql.md b/content/shared/influxdb-client-libraries-reference/flight/java-flightsql.md index b0a57d52e..e29b31da5 100644 --- a/content/shared/influxdb-client-libraries-reference/flight/java-flightsql.md +++ b/content/shared/influxdb-client-libraries-reference/flight/java-flightsql.md @@ -6,7 +6,7 @@ > We recommend using the [`influxdb3-java` Java client library](/influxdb3/version/reference/client-libraries/v3/java/) for integrating InfluxDB 3 with your Java application code. > > [InfluxDB 3 client libraries](/influxdb3/version/reference/client-libraries/v3/) wrap Apache Arrow Flight clients -> and provide convenient methods for [writing](/influxdb3/version/get-started/write/#write-line-protocol-to-influxdb), [querying](/influxdb3/version/get-started/query/#execute-an-sql-query), and processing data stored in {{% product-name %}}. +> and provide convenient methods for [writing](/influxdb3/version/write-data/api-client-libraries/), [querying](/influxdb3/version/query-data/execute-queries/), and processing data stored in {{% product-name %}}. > Client libraries can query using SQL or InfluxQL. diff --git a/content/shared/influxdb-client-libraries-reference/flight/python-flight.md b/content/shared/influxdb-client-libraries-reference/flight/python-flight.md index 5fa77472c..207f9bec7 100644 --- a/content/shared/influxdb-client-libraries-reference/flight/python-flight.md +++ b/content/shared/influxdb-client-libraries-reference/flight/python-flight.md @@ -6,21 +6,20 @@ > We recommend using the [`influxdb3-python` Python client library](/influxdb3/version/reference/client-libraries/v3/python/) for integrating InfluxDB 3 with your Python application code. > > [InfluxDB 3 client libraries](/influxdb3/version/reference/client-libraries/v3/) wrap Apache Arrow Flight clients -> and provide convenient methods for [writing](/influxdb3/version/get-started/write/#write-line-protocol-to-influxdb), [querying](/influxdb3/version/get-started/query/#execute-an-sql-query), and processing data stored in {{% product-name %}}. +> and provide convenient methods for [writing](/influxdb3/version/write-data/api-client-libraries/), [querying](/influxdb3/version/query-data/execute-queries/), and processing data stored in {{% product-name %}}. > Client libraries can query using SQL or InfluxQL. The following examples show how to use the `pyarrow.flight` and `pandas` Python modules to query and format data stored in an {{% product-name %}} database: -{{% code-tabs-wrapper %}} +{{< code-tabs-wrapper >}} {{% code-tabs %}} [SQL](#sql-python) [InfluxQL](#influxql-python) {{% /code-tabs %}} - {{% code-tab-content %}} {{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} -```py +```python # Using pyarrow>=12.0.0 FlightClient from pyarrow.flight import FlightClient, Ticket, FlightCallOptions import json @@ -62,7 +61,7 @@ print(data_frame.to_markdown()) {{% code-tab-content %}} {{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} -```py +```python # Using pyarrow>=12.0.0 FlightClient from pyarrow.flight import FlightClient, Ticket, FlightCallOptions import json @@ -97,6 +96,7 @@ print(data_frame.to_markdown()) {{% /code-placeholders %}} {{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} Replace the following: @@ -104,5 +104,3 @@ Replace the following: - {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [database token](/influxdb3/version/admin/tokens/database/) with sufficient permissions to the specified database - -{{% /code-tabs-wrapper %}} diff --git a/content/shared/influxdb-client-libraries-reference/flight/python-flightsql-dbapi.md b/content/shared/influxdb-client-libraries-reference/flight/python-flightsql-dbapi.md index 2350510c5..61d75e8da 100644 --- a/content/shared/influxdb-client-libraries-reference/flight/python-flightsql-dbapi.md +++ b/content/shared/influxdb-client-libraries-reference/flight/python-flightsql-dbapi.md @@ -6,7 +6,7 @@ The [Python `flightsql-dbapi` Flight SQL DBAPI library](https://github.com/influ > We recommend using the [`influxdb3-python` Python client library](/influxdb3/version/reference/client-libraries/v3/python/) for integrating InfluxDB 3 with your Python application code. > > [InfluxDB 3 client libraries](/influxdb3/version/reference/client-libraries/v3/) wrap Apache Arrow Flight clients -> and provide convenient methods for [writing](/influxdb3/version/get-started/write/#write-line-protocol-to-influxdb), [querying](/influxdb3/version/get-started/query/#execute-an-sql-query), and processing data stored in {{% product-name %}}. +> and provide convenient methods for [writing](/influxdb3/version/write-data/api-client-libraries/), [querying](/influxdb3/version/query-data/execute-queries/), and processing data stored in {{% product-name %}}. > Client libraries can query using SQL or InfluxQL. ## Installation @@ -32,7 +32,7 @@ from flightsql import FlightSQLClient ``` - `flightsql.FlightSQLClient` class: an interface for [initializing -a client](#initialization) and interacting with a Flight SQL server. +a client](#initialize-a-client) and interacting with a Flight SQL server. ## API reference @@ -41,11 +41,11 @@ a client](#initialization) and interacting with a Flight SQL server. - [Initialize a client](#initialize-a-client) - [Instance methods](#instance-methods) - [FlightSQLClient.execute](#flightsqlclientexecute) - - [Syntax {#execute-query-syntax}](#syntax-execute-query-syntax) - - [Example {#execute-query-example}](#example-execute-query-example) + - [Syntax](#execute-query-syntax) + - [Example](#execute-query-example) - [FlightSQLClient.do_get](#flightsqlclientdo_get) - - [Syntax {#retrieve-data-syntax}](#syntax-retrieve-data-syntax) - - [Example {#retrieve-data-example}](#example-retrieve-data-example) + - [Syntax](#retrieve-data-syntax) + - [Example](#retrieve-data-example) ## Class FlightSQLClient diff --git a/content/shared/influxdb-v2/write-data/troubleshoot.md b/content/shared/influxdb-v2/write-data/troubleshoot.md new file mode 100644 index 000000000..fa1d04166 --- /dev/null +++ b/content/shared/influxdb-v2/write-data/troubleshoot.md @@ -0,0 +1,345 @@ + +Learn how to avoid unexpected results and recover from errors when writing to InfluxDB. + +{{% show-in "v2,cloud" %}} + +- [Handle `write` and `delete` responses](#handle-write-and-delete-responses) +- [Troubleshoot failures](#troubleshoot-failures) +- [Troubleshoot rejected points](#troubleshoot-rejected-points) + +{{% /show-in %}} + +## Handle `write` and `delete` responses + +{{% show-in "cloud" %}} + +In InfluxDB Cloud, writes and deletes are asynchronous and eventually consistent. +Once InfluxDB validates your request and [queues](/influxdb/cloud/reference/internals/durability/#backup-on-write) the write or delete, it sends a _success_ response (HTTP `204` status code) as an acknowledgement. +To ensure that InfluxDB handles writes and deletes in the order you request them, wait for the acknowledgement before you send the next request. +Because writes are asynchronous, keep the following in mind: + +- Data might not yet be queryable when you receive _success_ (HTTP `204` status code). +- InfluxDB may still reject points after you receive _success_ (HTTP `204` status code). + +{{% /show-in %}} + +{{% show-in "v2" %}} + +{{% product-name %}} does the following when you send a write request: + + 1. Validates the request. + 2. If successful, attempts to [ingest data](/influxdb/v2/reference/internals/durability/#data-ingest) from the request body; otherwise, responds with an [error status](#review-http-status-codes). + 3. Ingests or rejects data from the batch and returns one of the following HTTP status codes: + + - `204 No Content`: All of the data is ingested and queryable. + - `422 Unprocessable Entity`: Some or all of the data has been rejected. Data that has not been rejected is ingested and queryable. + + The response body contains error details about [rejected points](#troubleshoot-rejected-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. + +{{% /show-in %}} + +### Review HTTP status codes + +InfluxDB uses conventional HTTP status codes to indicate the success or failure of a request. +Write requests return the following status codes: + +{{% show-in "cloud" %}} + +| HTTP response code | Message | Description | +| :-------------------------------| :--------------------------------------------------------------- | :------------- | +| `204 "Success"` | | If InfluxDB validated the request data format and queued the data for writing to the bucket | +| `400 "Bad request"` | `message` contains the first malformed line | If data is malformed | +| `401 "Unauthorized"` | | If the [`Authorization: Token` header](/influxdb/cloud/api-guide/api_intro/#authentication) is missing or malformed or if the [API token](/influxdb/cloud/api-guide/api_intro/#authentication) doesn't have [permission](/influxdb/cloud/admin/tokens/) to write to the bucket | +| `404 "Not found"` | requested **resource type** (for example, "organization") and **resource name** | If a requested resource, such as an organization or bucket, wasn't found | +| `413 "Request too large"` | cannot read data: points in batch is too large | If a **write** request exceeds the maximum [global limit](/influxdb/cloud/account-management/limits/#global-limits) | +| `429 “Too many requests”` | `Retry-After` header: xxx (seconds to wait before retrying the request) | If a **read** or **write** request exceeds your plan's [adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas) or if a **delete** request exceeds the maximum [global limit](/influxdb/cloud/account-management/limits/#global-limits) | +| `500 "Internal server error"` | | Default status for an error | +| `503 “Service unavailable“` | Series cardinality exceeds your plan's service quota | If **series cardinality** exceeds your plan's [adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas) | + +{{% /show-in %}} + +{{% show-in "v2" %}} + +- `204` **Success**: All request data was written to the bucket. +- `400` **Bad request**: + The response body contains the first malformed line in the data. All request data was rejected and not written. +- `401` **Unauthorized**: May indicate one of the following: + - [`Authorization: Token` header](/influxdb/v2/api-guide/api_intro/#authentication) is missing or malformed. + - [API token](/influxdb/v2/api-guide/api_intro/#authentication) value is missing from the header. + - API token does not have sufficient permissions to write to the organization and the bucket. For more information about token types and permissions, see [Manage API tokens](/influxdb/v2/admin/tokens/). +- `404` **Not found**: A requested resource, such as an organization or bucket, was not found. The response body contains the requested resource type (for example, "organization") and resource name. +- `413` **Request entity too large**: All request data was rejected and not written. InfluxDB OSS only returns this error if the [Go (golang) `ioutil.ReadAll()`](https://pkg.go.dev/io/ioutil#ReadAll) function raises an error. +- `422` **Unprocessable entity**: The request was well-formed, but some or all the points were rejected due to semantic errors--for example, schema conflicts or retention policy violations. +- `500` **Internal server error**: Default HTTP status for an error. +- `503` **Service unavailable**: Server is temporarily unavailable to accept writes. The `Retry-After` header describes when to try the write again. + +{{% /show-in %}} + +The `message` property of the response body may contain additional details about the error. +If some of your data did not write to the bucket, see how to [troubleshoot rejected points](#troubleshoot-rejected-points). + +{{% show-in "cloud" %}} + +### Troubleshoot partial writes + +For example, a partial write may occur when InfluxDB writes all points that conform to the bucket schema, but rejects points that have the wrong data type in a field. +To check for writes that fail asynchronously, create a [task](/influxdb/cloud/process-data/manage-tasks/) to [check the _monitoring bucket for rejected points](#review-rejected-points). +To resolve partial writes and rejected points, see [troubleshoot failures](#troubleshoot-failures). + +{{% /show-in %}} + +## Troubleshoot failures + +{{% show-in "v2" %}} + +If you notice data is missing in your bucket, 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--for example, `partial write` indicates [rejected points](#troubleshoot-rejected-points). +- Verify all lines contain valid syntax ([line protocol](/influxdb/v2/reference/syntax/line-protocol/) or [CSV](/influxdb/v2/reference/syntax/annotated-csv/)). +- Verify the timestamps match the [precision parameter](/influxdb/v2/write-data/#timestamp-precision) in your request. +- Minimize payload size and network errors by [optimizing writes](/influxdb/v2/write-data/best-practices/optimize-writes/). + +{{% /show-in %}} + +{{% show-in "cloud" %}} +If you notice data is missing in your bucket, do the following: + +- Check the `message` property in the response body for details about the error--for example, `partial write error` indicates [rejected points](#troubleshoot-rejected-points). +- Check for [rejected points](#troubleshoot-rejected-points) in your organization's `_monitoring` bucket. +- Verify all lines contain valid syntax ([line protocol](/influxdb/cloud/reference/syntax/line-protocol/) or [CSV](/influxdb/cloud/reference/syntax/annotated-csv/)). See how to [find parsing errors](#find-parsing-errors). +- Verify the data types match the [series](/influxdb/cloud/reference/key-concepts/data-elements/#series) or [bucket schema](/influxdb/cloud/admin/buckets/bucket-schema/). See how to resolve [explicit schema rejections](#resolve-explicit-schema-rejections). +- Verify the timestamps match the [precision parameter](/influxdb/cloud/write-data/#timestamp-precision). +- Minimize payload size and network errors by [optimizing writes](/influxdb/cloud/write-data/best-practices/optimize-writes/). + +{{% /show-in %}} + +## Troubleshoot rejected points + +{{% show-in "v2" %}} + +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`: `"unprocessable entity"` +- `message`: a string that describes the reason points were rejected and may provide details, such as database, retention policy, and which bound was violated. + +For example, the following `message` indicates that points were rejected because the timestamps fall outside the `1d` retention policy: + +```text +failure writing points to database: partial write: dropped 4 points outside retention policy of duration 24h0m0s - oldest point home,room=Living\\ Room at 1970-01-01T00:00:01.541Z dropped because it violates a Retention Policy Lower Bound at 2025-05-20T19:06:17.612973Z, newest point home,room=Living\\ Room at 1970-01-01T00:00:01.5410006Z dropped because it violates a Retention Policy Lower Bound at 2025-05-20T19:06:17.612973Z dropped=4 for database: 9f282d63c7d3a5c0 for retention policy: autogen +``` + +InfluxDB rejects points for the following reasons: + +- a line protocol parsing error +- an invalid timestamp +- a schema conflict +- retention policy violation + +Schema conflicts occur when you try to write data that contains any of the following: + +- The **batch** contains another point with the same series, but one of the fields has a different value type. +- The **bucket** contains another point with the same series, but one of the fields has a different value type. + +Check for [field type](/influxdb/v2/reference/key-concepts/data-elements/#field-value) differences between the missing data point and other points that have the same [series](/influxdb/v2/reference/key-concepts/data-elements/#series)--for example, did you attempt to write `string` data to an `int` field? + +{{% /show-in %}} + +{{% show-in "cloud" %}} + +When you receive an HTTP `204` (Success) status code, InfluxDB has validated your request format and queued your data for writing. +However, {{% product-name %}} processes data asynchronously, which means points may still be rejected after you receive a success response. + +InfluxDB may reject points for several reasons: +- Line protocol parsing errors +- Invalid timestamps +- Data type conflicts with existing schema +- Retention policy violations +- Series cardinality exceeding your plan's limits + +To verify if your data was successfully written, query your data or check the `_monitoring` bucket for rejected points. + +- [Review rejected points](#review-rejected-points) + - [Find parsing errors](#find-parsing-errors) + - [Find data type conflicts and schema rejections](#find-data-type-conflicts-and-schema-rejections) +- [Resolve data type conflicts](#resolve-data-type-conflicts) +- [Resolve explicit schema rejections](#resolve-explicit-schema-rejections) + +### Review rejected points + +To get a log of rejected points, query the [`rejected_points` measurement](/influxdb/cloud/reference/internals/system-buckets/#_monitoring-bucket-schema) in your organization's `_monitoring` bucket. +To more quickly locate `rejected_points`, keep the following in mind: + +- If your line protocol batch contains single lines with multiple [fields](/influxdb/cloud/reference/syntax/line-protocol/#field-set), InfluxDB logs an entry for each point (each unique field) that is rejected. +- Each entry contains a `reason` tag that describes why the point was rejected. +- Entries for [data type conflicts and schema rejections](#find-data-type-conflicts-and-schema-rejections) have a `count` field value of `1`. +- Entries for [parsing errors](#find-parsing-errors) contain an `error` field (and don't contain a `count` field). + +#### rejected_points schema + +| Name | Value | +|:------ |:----- | +| `_measurement`| `rejected_points` | +| `_field` | [`count`](#find-data-type-conflicts-and-schema-rejections) or [`error`](#find-parsing-errors) | +| `_value` | [`1`](#find-data-type-conflicts-and-schema-rejections) or [error details](#find-parsing-errors) | +| `bucket` | ID of the bucket that rejected the point | +| `measurement` | Measurement name of the point | +| `field` | Name of the field that caused the rejection | +| `reason` | Brief description of the problem. See specific reasons in [data type conflicts and schema rejections](#find-data-type-conflicts-and-schema-rejections) | +| `gotType` | Received [field](/influxdb/cloud/reference/key-concepts/data-elements/#field-value) type: `Boolean`, `Float`, `Integer`, `String`, or `UnsignedInteger` | +| `wantType` | Expected [field](/influxdb/cloud/reference/key-concepts/data-elements/#field-value) type: `Boolean`, `Float`, `Integer`, `String`, or `UnsignedInteger` | +| `