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

Reorganize Serverless DBRP for v1 queries and writes, explain DBRP and auto bucket defaults (#5257) 

* chore(v3): DBRP: Update Serverless API ref (#5234)

* chore(ci): Tests: substitute placeholders in JSON body parameters

* chore(v3): DBRP: copy page from influxql to admin/dbrps.

* chore(ci): Trying to prevent "a Influx..."

* chore(ci): Allow autogen

* chore(serverless): DBRP glossary entry

* chore(v2): add default DBRP note

* chore(v3): use product-name shortcode

* chore(v3): use product-name shortcode, clarify retention period and mapping

* chore(serverless): Create Bucket:

- add missing example for Data Explorer
- move Retention Period syntax and define retentionRules syntax
- setup for tests

* chore(serverless): Create Bucket:

- add missing example for Data Explorer
- move Retention Period syntax and define retentionRules syntax
- setup for tests

* chore(serverless): Update bucket: alias to match other products

* chore(v3): Serverless for prototyping: update with DBRP behavior

* Serverless auto-generated buckets have 3-day default retention period
Fixes #5234

- v1-compat guide:
  - passes tests
  - explains DBRPs (default, automatic, and management)
  - migrate DBRP content from query-data/influxql/dbrp
- v2-compat guide:
  - fix TOC
  - add list code example
- rename influxdb-v1-api to api/v1-http, migrate params from v1-compat guide, and explain DBRP in context
- add write-data/api/v1-http and migrate content from v1-compat guide
- move optimize and troubleshooting up to /query-data
- add Related items support for paths containing http
- substitute placeholders in tests

* chore(test): update configuration in README

* fix(serverless): Optimize queries parent

* fix(serverless): create-bucket cleanup

* fix: cleanup

* fix: close tag

* Apply suggestions from code review

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* fix(v3): permission to create dbrp-mapped bucket

---------

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
pull/5259/head^2
Jason Stirnaman 2023-12-05 16:48:25 -06:00 committed by GitHub
parent ad4ceabbb0
commit de0f526bdf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
25 changed files with 1279 additions and 838 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.ci/vale/styles/InfluxDataDocs/Branding.yml
View File

@ -9,3 +9,4 @@ swap:
"FlightSQL": Flight SQL
"java[ -]?scripts?": JavaScript
"SQL Alchemy": SQLAlchemy
"a {{% product-name %}}": an {{% product-name %}}

1
.ci/vale/styles/InfluxDataDocs/Terms/configuration-terms.txt
View File

@ -1,3 +1,4 @@
autogen
batchBucket
batchInterval
commentPrefix

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

@ -14188,7 +14188,10 @@ paths:
text/csv:
schema:
$ref: '#/components/schemas/InfluxqlCsvResponse'
description: Query results
description: |
Query results.
If a DBRP doesn't exist for the `db=DATABASE_NAME` and `rp=RETENTION_POLICY_NAME` combination in the query request, the response body contains an error message, for example `"database not found:..."`.
headers:
Content-Encoding:
description: Lists encodings (usually compression algorithms) that have been applied to the response payload.

9
content/influxdb/cloud-dedicated/admin/databases/create.md
View File

@ -53,8 +53,9 @@ Use the `--retention-period` flag to define a specific
[retention period](/influxdb/cloud-dedicated/admin/databases/#retention-periods)
for the database.
The retention period value is a time duration value made up of a numeric value
plus a duration unit. For example, `30d` means 30 days.
A zero duration retention period is infinite and data will not expire.
plus a duration unit.
For example, `30d` means 30 days.
A zero duration (`0d`) retention period is infinite and data won't expire.
The retention period value cannot be negative or contain whitespace.
{{< flex >}}
@ -99,14 +100,14 @@ Database names must adhere to the following naming restrictions:
In InfluxDB 1.x, data is stored in [databases](/influxdb/v1/concepts/glossary/#database)
and [retention policies](/influxdb/v1/concepts/glossary/#retention-policy-rp).
In InfluxDB Cloud Dedicated, databases and retention policies have been merged into
In {{% product-name %}}, databases and retention policies have been merged into
_databases_, where databases have a retention period, but retention policies
are no longer part of the data model.
Because InfluxQL uses the 1.x data model, a database must be mapped to a v1
database and retention policy (DBRP) to be queryable with InfluxQL.
**When naming a database that you want to query with InfluxQL**, use the following
naming convention to automatically map v1 DBRP combinations to a database:
naming convention to automatically map v1 DBRP combinations to an {{% product-name %}} database:
```sh
database_name/retention_policy_name

36
content/influxdb/cloud-serverless/admin/buckets/_index.md
View File

@ -17,10 +17,44 @@ alt_links:
---
A **bucket** is a named location where time series data is stored.
All buckets have a **retention period**, a duration of time that each data point persists.
All buckets have a [retention period](#retention-period), a duration of time that each data point persists.
InfluxDB drops all points with timestamps older than the bucket's retention period.
A bucket belongs to an organization.
{{% note %}}
**If coming from InfluxDB v1**, the concepts of databases and retention policies
have been combined into a single concept--_bucket_.
Retention policies are no longer part of the InfluxDB data model.
However, {{% product-name %}} does
support InfluxQL and the InfluxDB v1 API `/write` and `/query` endpoints, which require databases and retention policies.
See how to [map v1 databases and retention policies to buckets](/influxdb/cloud-serverless/guides/api-compatibility/v1/#map-v1-databases-and-retention-policies-to-buckets).
**If coming from InfluxDB v2 or InfluxDB Cloud**, _buckets_ are functionally equivalent.
{{% /note %}}
## Retention period
A bucket **retention period** is the maximum age of data stored in the bucket.
The age of data is determined by the timestamp associated with each point.
When a point's timestamp is beyond the retention period (relative to now), the
point is marked for deletion and is removed from the bucket the next time the
retention enforcement service runs.
The _minimum_ retention period for an InfluxDB bucket is 1 hour.
The _maximum_ retention period is infinite meaning data does not expire and will
never be removed by the retention enforcement service.
You can [update a bucket](#update-a-bucket) to change the retention period.
## Table and column limits
In {{< product-name >}}, table (measurement) and column are limited per bucket.
Each measurement is represented by a table.
Time, fields, and tags are each represented by a column.
**Maximum number of tables**: 500
**Maximum number of columns**: 200
The following articles provide information about managing buckets:
{{< children sort="weight">}}

201
content/influxdb/cloud-serverless/admin/buckets/create-bucket.md
View File

@ -4,24 +4,65 @@ seotitle: Create a bucket in InfluxDB Cloud Serverless
description: >
Create buckets to store time series data in InfluxDB Cloud Serverless
using the InfluxDB UI, influx CLI, or InfluxDB HTTP API.
Map DBRPs to buckets for querying with InfluxQL and using the InfluxDB API `/write` and `/query` endpoints.
menu:
influxdb_cloud_serverless:
name: Create a bucket
parent: Manage buckets
weight: 201
related:
- /influxdb/cloud-serverless/admin/buckets/manage-explicit-bucket-schemas/
- /influxdb/cloud-serverless/query-data/influxql/dbrp/
- /influxdb/cloud-serverless/guides/migrate-data/migrate-1x-to-v3/
- /influxdb/cloud-serverless/guides/api-compatibility/v1/
aliases:
- /influxdb/cloud-serverless/organizations/buckets/create-bucket/
- /influxdb/cloud-serverless/admin/buckets/create/
alt_links:
cloud: /influxdb/cloud/admin/buckets/create-bucket/
---
Use the InfluxDB user interface (UI), `influx` command line interface (CLI), or InfluxDB HTTP API
to create a bucket.
Use the InfluxDB user interface (UI), `influx` command line interface (CLI), or InfluxDB HTTP API to create a bucket.
- [Bucket naming restrictions](#bucket-naming-restrictions)
- [Table and column limits](#table-and-column-limits)
- [Auto-generate buckets on write](#auto-generate-buckets-on-write)
- [Create a bucket](#create-a-bucket)
- [Retention period syntax](#retention-period-syntax)
- [/api/v2 retentionRules syntax](#apiv2-retentionrules-syntax)
- [retentionRules example](#retentionrules-example)
## Bucket naming restrictions
Bucket names must adhere to the following naming restrictions:
- Must contain two or more characters
- Cannot start with an underscore (`_`)
- Cannot contain a double quote (`"`)
Names must be unique within the organization.
When you send a request such as writing or querying, {{% product-name %}} uses the bucket name and token in your request to find the bucket within the organization.
## Table and column limits
In {{< product-name >}}, table (measurement) and column are limited per bucket.
Each measurement is represented by a table.
Time, fields, and tags are each represented by a column.
**Maximum number of tables**: 500
**Maximum number of columns**: 200
### Auto-generate buckets on write
InfluxDB can [automatically create DBRP mappings and associated buckets](/influxdb/cloud-serverless/guides/api-compatibility/v1/#automatic-dbrp-mapping) for you during the following operations:
- Writing to the [v1 `/write` endpoint](/influxdb/cloud-serverless/guides/api-compatibility/v1/#write-data)
- [Migrating from InfluxDB 1.x to {{% product-name %}}](/influxdb/cloud-serverless/guides/migrate-data/migrate-1x-to-v3/)
<!-- Invisible anchor for "Create a bucket" -->
<span id="create-a-bucket"></span>
### Create a bucket
Create a bucket using the InfluxDB UI, `influx` CLI, or InfluxDB HTTP API.
{{< tabs-wrapper >}}
{{% tabs %}}
@ -29,16 +70,15 @@ to create a bucket.
[influx CLI](#)
[InfluxDB API](#)
{{% /tabs %}}
<!------------------------------ BEGIN UI CONTENT ----------------------------->
{{% tab-content %}}
<!------------------------------ BEGIN UI CONTENT ----------------------------->
There are two places you can create a bucket in the UI.
- [Create a bucket from the Load Data menu](#create-a-bucket-from-the-load-data-menu)
- [Create a bucket in the Data Explorer](#create-a-bucket-in-the-data-explorer)
### Create a bucket from the Load Data menu
#### Create a bucket from the Load Data menu
1. In the navigation menu on the left, select **Load Data** > **Buckets**.
@ -51,33 +91,95 @@ There are two places you can create a bucket in the UI.
- **Older than** to choose a specific retention period.
5. Click **Create** to create the bucket.
{{% /tab-content %}}
#### Create a bucket in the Data Explorer
1. In the navigation menu on the left, select **Explore* (**Data Explorer**).
{{< nav-icon "data-explorer" >}}
2. In the header bar, toggle the "Switch to old Data Explorer" button to the "on" position to display the Flux Builder.
3. In the **From** panel in the Flux Builder, select `+ Create Bucket`.
4. Enter a **Name** for the bucket
_(see [Bucket naming restrictions](#bucket-naming-restrictions))_.
5. Select when to **Delete Data**:
- **Never** to retain data forever.
- **Older than** to choose a specific retention period.
6. Click **Create** to create the bucket.
<!------------------------------- END UI CONTENT ------------------------------>
<!----------------------------- BEGIN CLI CONTENT ----------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!----------------------------- BEGIN CLI CONTENT ----------------------------->
To create a bucket with the `influx` CLI, use the [`influx bucket create` command](/influxdb/cloud-serverless/reference/cli/influx/bucket/create)
and specify values for the following flags:
- `-o`, `--org`: Organization name
- `-n`, `--name`: Bucket name
- `-r`, `--retention`: Retention period duration
- `-r`, `--retention`: [Retention period duration](#retention-period-syntax)
The following example creates a bucket with a retention period of 72 hours:
<!--test
```sh
influx bucket delete \
--name BUCKET_NAME
```
-->
<!--pytest-codeblocks:cont-->
{{% code-placeholders "ORG|BUCKET_NAME|72h" %}}
```sh
influx bucket create \
--name my-bucket \
--org {INFLUX_ORG} \
--name BUCKET_NAME \
--retention 72h
```
{{% /code-placeholders %}}
{{% /tab-content %}}
## Retention period syntax
Retention rules specify the bucket retention period, the duration that data is stored before it expires.
The retention period also defines the minimum timestamp that you can write to the bucket; the bucket rejects data older than the retention period.
Use the `--retention` flag to specify a
[retention period](/influxdb/cloud-serverless/admin/databases/#retention-periods)
for the bucket.
The retention period value is a time duration value made up of a numeric value
plus a duration unit.
For example, `30d` means 30 days.
A zero duration (`0d`) retention period is infinite and data won't expire.
The retention period value cannot be negative or contain whitespace.
{{< flex >}}
{{% flex-content %}}
##### Valid durations units include
- **m**: minute
- **h**: hour
- **d**: day
- **w**: week
- **mo**: month
- **y**: year
{{% /flex-content %}}
{{% flex-content %}}
##### Example retention period values
- `0d`: infinite/none
- `3d`: 3 days
- `6w`: 6 weeks
- `1mo`: 1 month (30 days)
- `1y`: 1 year
- `30d30d`: 60 days
- `2.5d`: 60 hours
{{% /flex-content %}}
{{< /flex >}}
<!------------------------------ END CLI CONTENT ------------------------------>
<!----------------------------- BEGIN API CONTENT ----------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!----------------------------- BEGIN API CONTENT ----------------------------->
To create a bucket with the InfluxDB HTTP API, send a request to the following endpoint:
@ -96,18 +198,75 @@ Include the following in your request:
- {{< req "\*" >}} **retentionRules:** JSON array containing a single object
with the following fields:
- **type:** expire
- **everySecond**: Number of seconds to retain data _(0 means forever)_
- **everySecond**: Retention period as a number of seconds _(0 means forever)_
- **shardGroupDuration**: Number of seconds to retain shard groups _(0 means forever)_
The following example creates a bucket with a retention period of `86,400` seconds, or 24 hours:
<!--test
```sh
{{% get-shared-text "api/v2.0/buckets/oss/create.sh" %}}
influx bucket delete --name BUCKET_NAME
```
-->
<!--pytest-codeblocks:cont-->
{{% code-placeholders "API_TOKEN|ORG_ID|86400" %}}
```sh
curl --silent -w "%{response_code}: %{errormsg}\n" \
-XPOST "https://{{< influxdb/host >}}/api/v2/buckets" \
--header "Authorization: Token API_TOKEN" \
--header "Content-type: application/json" \
--data @- << EOF
{
"orgID": "ORG_ID",
"name": "BUCKET_NAME",
"retentionRules": [
{
"type": "expire",
"everySeconds": 86400
}
]
}
EOF
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: the name of the bucket
- {{% code-placeholder-key %}}`86400`{{% /code-placeholder-key %}}: the number of seconds data is stored before it expires. Default is `infinite`--data won't expire.
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the specified bucket
If successful, the output is an HTTP `201: Created` status code and the bucket; otherwise, an error status and message.
## /api/v2 retentionRules syntax
Retention rules specify the bucket [retention period](/influxdb/cloud-serverless/admin/databases/#retention-periods).
The retention period also defines the minimum timestamp that you can write to the bucket; the bucket rejects data older than the retention period.
The default retention period is `infinite`--data won't expire.
To specify the retention period, set the `retentionRules.everySeconds` property to the number of seconds.
A zero seconds (`0`) retention period is infinite.
The retention period value can't be negative or contain whitespace.
### retentionRules example
```json
{
"orgID": "ORG_ID",
"name": "BUCKET_NAME",
"retentionRules": [
{
"type": "expire",
"everySeconds": "RETENTION_PERIOD_SECONDS"
}
]
}
```
_For information about **InfluxDB API options and response codes**, see
[InfluxDB API Buckets reference documentation](/influxdb/cloud-serverless/api/#operation/PostBuckets)._
{{% /tab-content %}}
<!------------------------------ END API CONTENT ------------------------------>
{{% /tab-content %}}
{{< /tabs-wrapper >}}

1
content/influxdb/cloud-serverless/admin/buckets/update-bucket.md
View File

@ -9,6 +9,7 @@ menu:
weight: 202
aliases:
- /influxdb/cloud-serverless/organizations/buckets/update-bucket/
- /influxdb/cloud-serverless/admin/buckets/update/
alt_links:
cloud: /influxdb/cloud/admin/buckets/update-bucket/
---

1
content/influxdb/cloud-serverless/admin/buckets/view-buckets.md
View File

@ -11,6 +11,7 @@ menu:
weight: 202
aliases:
- /influxdb/cloud-serverless/organizations/buckets/view-buckets/
- /influxdb/cloud-serverless/admin/buckets/view/
alt_links:
cloud: /influxdb/cloud/admin/buckets/view-buckets/
---

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

@ -1,5 +1,5 @@
---
title: Use the InfluxDB v1 API
title: Use the InfluxDB v1 HTTP API
description: >
Use InfluxDB v1 API authentication, endpoints, and tools when bringing existing 1.x workloads to InfluxDB Cloud Serverless.
weight: 3
@ -7,57 +7,44 @@ menu:
influxdb_cloud_serverless:
parent: API compatibility
name: v1 API
influxdb/cloud-serverless/tags: [write, line protocol]
aliases:
- /influxdb/cloud-serverless/primers/api/v1/
- /influxdb/cloud-serverless/api-compatibility/v1/
influxdb/cloud-serverless/tags: [write, line protocol]
- /influxdb/cloud-serverless/query-data/influxql/dbrp/
related:
- /influxdb/cloud-serverless/query-data/sql/
- /influxdb/cloud-serverless/query-data/influxql/
- /influxdb/cloud-serverless/write-data/
- /influxdb/cloud-serverless/write-data/use-telegraf/configure/
- /influxdb/cloud-serverless/query-data/execute-queries/v1-http/
- /influxdb/cloud-serverless/write-data/api/v1-http/
- /influxdb/cloud-serverless/reference/api/
- /influxdb/cloud-serverless/reference/client-libraries/
list_code_example: |
```sh
curl "https://{{< influxdb/host >}}/query" \
--user "":"API_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "rp=RETENTION_POLICY" \
--data-urlencode "q=SELECT * FROM MEASUREMENT"
```
---
Use the InfluxDB v1 API `/write` and `/query` endpoints with v1 workloads that you bring to {{% product-name %}}.
The v1 endpoints work with username/password authentication and existing InfluxDB 1.x tools and code.
The InfluxDB v1 API `/write` endpoint works with InfluxDB 1.x client libraries and the [Telegraf v1 Output Plugin](/telegraf/v1/plugins/#output-influxdb).
The InfluxDB v1 API `/query` endpoint supports InfluxQL and third-party integrations like [Grafana](https://grafana.com).
Learn how to authenticate requests, adjust request parameters for existing v1 workloads, and find compatible tools for writing and querying data stored in an {{% product-name %}} database.
<!-- TOC -->
Learn how to authenticate requests, map databases and retention policies to buckets, adjust request parameters for existing v1 workloads, and find compatible tools for writing and querying data stored in an {{% product-name %}} database.
- [Authenticate API requests](#authenticate-api-requests)
- [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme)
- [Basic authentication](#basic-authentication)
- [Syntax](#syntax)
- [Example](#example)
- [Query string authentication](#query-string-authentication)
- [Syntax](#syntax)
- [Example](#example)
- [Authenticate with a token scheme](#authenticate-with-a-token-scheme)
- [Syntax](#syntax)
- [Examples](#examples)
- [Responses](#responses)
- [Error examples](#error-examples)
- [Map v1 databases and retention policies to buckets](#map-v1-databases-and-retention-policies-to-buckets)
- [Required permissions](#required-permissions)
- [Default DBRP](#default-dbrp)
- [Automatic DBRP mapping](#automatic-dbrp-mapping)
- [Manage DBRPs](#manage-dbrps)
- [Write data](#write-data)
- [v1 API /write parameters](#v1-api-write-parameters)
- [Timestamp precision](#timestamp-precision)
- [Tools for writing to the v1 API](#tools-for-writing-to-the-v1-api)
- [Telegraf](#telegraf)
- [Other Telegraf configuration options](#other-telegraf-configuration-options)
- [Interactive clients](#interactive-clients)
- [v1 CLI not supported](#v1-cli-not-supported)
- [Client libraries](#client-libraries)
- [Query data](#query-data)
- [Tools to execute queries](#tools-to-execute-queries)
- [v1 API /query parameters](#v1-api-query-parameters)
- [Timestamp precision](#timestamp-precision)
- [Bucket management with InfluxQL not supported](#bucket-management-with-influxql-not-supported)
- [Bucket management with InfluxQL (not supported)](#bucket-management-with-influxql-not-supported)
<!-- /TOC -->
## Authenticate API requests
@ -108,9 +95,9 @@ The following example shows how to use cURL with the `Basic` authentication sche
# to query the InfluxDB v1 API
#######################################
curl --get "https://{{< influxdb/host >}}/query" \
curl "https://{{< influxdb/host >}}/query" \
--user "":"API_TOKEN" \
--data-urlencode "db=BUCKET_NAME" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "rp=RETENTION_POLICY" \
--data-urlencode "q=SELECT * FROM MEASUREMENT"
```
@ -118,9 +105,9 @@ curl --get "https://{{< influxdb/host >}}/query" \
Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} bucket
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: your {{% product-name %}} retention policy
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the specified bucket
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the mapped bucket
#### Query string authentication
@ -147,7 +134,7 @@ The following example shows how to use cURL with query string authentication and
curl --get "https://{{< influxdb/host >}}/query" \
--data-urlencode "p=API_TOKEN" \
--data-urlencode "db=BUCKET_NAME" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "rp=RETENTION_POLICY" \
--data-urlencode "q=SELECT * FROM MEASUREMENT"
```
@ -155,9 +142,9 @@ curl --get "https://{{< influxdb/host >}}/query" \
Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: your {{% product-name %}} retention policy
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the specified bucket
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the [database](#map-databases-and-retention-policies-to-buckets)
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: the [retention policy](#map-databases-and-retention-policies-to-buckets)
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the mapped bucket
### Authenticate with a token scheme
@ -181,18 +168,24 @@ Use `Token` to authenticate a write request:
# to write data.
########################################################
curl -i "https://{{< influxdb/host >}}/write?db=BUCKET_NAME&rp=RETENTION_POLICY&precision=ms" \
curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&rp=RETENTION_POLICY&precision=ms" \
--header "Authorization: Token API_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--data-binary 'home,room=kitchen temp=72 1682358973500'
```
<!-- after-test
```sh
influx bucket delete -n DATABASE_NAME/RETENTION_POLICY_NAME
```
-->
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: your {{% product-name %}} retention policy
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the specified bucket
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the [database](#map-databases-and-retention-policies-to-buckets)
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: the [retention policy](#map-databases-and-retention-policies-to-buckets)
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the mapped bucket
## Responses
@ -216,7 +209,7 @@ Response body messages may differ across {{% product-name %}} v1 API, v2 API, In
```
The `?db=` parameter value is missing in the request.
Provide the [bucket](/influxdb/cloud-serverless/admin/buckets/) name.
Provide the [DBRP database name](#map-v1-databases-and-retention-policies-to-buckets).
- **Failed to deserialize db/rp/precision**
@ -234,262 +227,503 @@ Response body messages may differ across {{% product-name %}} v1 API, v2 API, In
The `?precision=` parameter contains an unknown value.
Provide a [timestamp precision](#timestamp-precision).
## Write data
## Map v1 databases and retention policies to buckets
Write data with your existing workloads that already use the InfluxDB v1 or v1.x-compatibility `/write` API endpoint.
{{% api-endpoint endpoint="https://{{< influxdb/host >}}/write" method="post" %}}
- [`/api/v2/write` parameters](#v1-api-write-parameters)
- [Tools for writing to the v1 API](#tools-for-writing-to-the-v1-api)
#### v1 API /write parameters
For {{% product-name %}} v1 API `/write` requests, set parameters as listed in the following table:
Parameter | Allowed in | Ignored | Value
-----------------------|--------------|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`consistency` | Query string | Ignored | N/A
`db` {{% req " \*" %}} | Query string | Honored | Bucket name
`precision` | Query string | Honored | [Timestamp precision](#timestamp-precision)
`rp` | Query string | Honored | [Retention policy](#retention-policy-and-dbrp-mapping)
`u` | Query string | Ignored | For [query string authentication](#query-string-authentication), any arbitrary string
`p` | Query string | Honored | For [query string authentication](#query-string-authentication), a [token](/influxdb/cloud-serverless/admin/tokens/) with permission to write to the bucket
`Content-Encoding` | Header | Honored | `gzip` (compressed data) or `identity` (uncompressed)
`Authorization` | Header | Honored | `Token API_TOKEN`, or `Basic <base64 [USERNAME]:API_TOKEN>`
{{% caption %}}{{% req " \*" %}} = {{% req "Required" %}}{{% /caption %}}
#### Timestamp precision
Use one of the following `precision` values in v1 API `/write` requests:
- `ns`: nanoseconds
- `us`: microseconds
- `ms`: milliseconds
- `s`: seconds
- `m`: minutes
- `h`: hours
#### Retention policy and DBRP mapping
In {{< product-name >}}, databases and retention policies are
combined and replaced by InfluxDB [buckets](/influxdb/cloud-serverless/reference/glossary/#bucket).
Writing data with the InfluxDB v1 `/write` endpoint or querying data using InfluxQL requires first mapping a database retention policy (DBRP) combination to a bucket.
If you specify an existing DBRP in the `rp=` parameter or if a default DBRP exists for the bucket, InfluxDB writes to the specified bucket.
Otherwise, if no DBRP exists for the bucket specified in `db=BUCKET_NAME`, and you use an [All-Access API token](/influxdb/cloud-serverless/admin/tokens/#all-access-api-token) to authorize the write request, InfluxDB auto-generates a new bucket named `BUCKET_NAME/autogen` and a DBRP mapping named `autogen`, and then writes the data to the new bucket.
### Tools for writing to the v1 API
The following tools work with the {{% product-name %}} `/write` endpoint:
- [Telegraf](#telegraf)
- [Interactive clients](#interactive-clients)
- [Client libraries](#client-libraries)
#### Telegraf
If you have existing v1 workloads that use Telegraf,
you can use the [InfluxDB v1.x `influxdb` Telegraf output plugin](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) to write data.
Before you can write data using the InfluxDB v1 `/write` endpoint or query data using the v1 `/query` endpoint, the bucket must be mapped to a [database retention policy (DBRP)](/influxdb/cloud-serverless/admin/dbrps/) combination.
{{% note %}}
See how to [use Telegraf and the v2 API](/influxdb/cloud-serverless/write-data/use-telegraf/) for new workloads that don't already use the v1 API.
To query using Flight with InfluxQL or SQL, you don't need to map DBRPs to buckets.
{{% /note %}}
The following table shows `outputs.influxdb` plugin parameters and values for writing to the {{% product-name %}} v1 API:
In InfluxDB 1.x, data is stored in [databases](/influxdb/cloud-serverless/reference/glossary/#database)
and [retention policies](/influxdb/cloud-serverless/reference/glossary/#retention-period).
In {{% product-name %}}, the concepts of database and retention policy have been merged into
_buckets_, where buckets have a [retention period](/influxdb/cloud-serverless/reference/glossary/#retention-period), but retention policies are no longer part of the data model.
Parameter | Ignored | Value
-------------------------|--------------------------|---------------------------------------------------------------------------------------------------
`database` | Honored | Bucket name
`retention_policy` | Honored | [Duration](/influxdb/cloud-serverless/reference/glossary/#duration)
`username` | Ignored | String or empty
`password` | Honored | [API token](/influxdb/cloud-serverless/admin/tokens/) with permission to write to the bucket
`content_encoding` | Honored | `gzip` (compressed data) or `identity` (uncompressed)
`skip_database_creation` | Ignored | N/A (see how to [create a bucket](/influxdb/cloud-serverless/admin/buckets/create-bucket/))
InfluxDB can [automatically map buckets to DBRPs](#automatic-dbrp-mapping) for you or you can [manage DBRP mappings](#manage-dbrps) yourself using the `influx v1 dbrp` CLI commands or the InfluxDB v2 API `/api/v2/dbrps` endpoints.
To configure the v1.x output plugin for writing to {{% product-name %}}, add the following `outputs.influxdb` configuration in your `telegraf.conf` file:
- [Authenticate API requests](#authenticate-api-requests)
- [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme)
- [Authenticate with a token scheme](#authenticate-with-a-token-scheme)
- [Responses](#responses)
- [Error examples](#error-examples)
- [Map v1 databases and retention policies to buckets](#map-v1-databases-and-retention-policies-to-buckets)
- [Required permissions](#required-permissions)
- [Default DBRP](#default-dbrp)
- [Automatic DBRP mapping](#automatic-dbrp-mapping)
- [Manage DBRPs](#manage-dbrps)
- [Write data](#write-data)
- [Query data](#query-data)
- [Bucket management with InfluxQL (not supported)](#bucket-management-with-influxql-not-supported)
{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}}
```toml
[[outputs.influxdb]]
urls = ["https://{{< influxdb/host >}}"]
database = "BUCKET_NAME"
skip_database_creation = true
retention_policy = "RETENTION_POLICY"
username = "ignored"
password = "API_TOKEN"
content_encoding = "gzip”
### Required permissions
Managing DBRP mappings requires a [token](/influxdb/cloud-serverless/admin/tokens/) with the necessary permissions.
- **write dbrp**: to create (automatically or manually), update, or delete DBRP mappings.
- **read dbrp**: to list DBRP mappings
- **write bucket**: to automatically create a bucket for a DBRP mapping when using the v1 write API
{{% note %}}
#### Permission required to create mapped buckets
If you use the v1 write API to write to a database (`db`) and retention policy (`rp`) combination that doesn't exist, InfluxDB tries to create a new bucket using the specified parameter values.
If the token doesn't have permission to create a bucket, then the write request fails with an authorization error.
{{% /note %}}
### Default DBRP
Each unique database name in DBRP mappings has a **default** mapping (the `default` property is equal to `true`).
If you send a request to the v1 `/write` or v1 `/query` endpoint and don't specify a retention policy name (`rp=`),
then InfluxDB uses the database's default DBRP mapping to determine the bucket.
### Automatic DBRP mapping
{{< product-name >}} automatically creates DBRP mappings for you during the
following operations:
- [Writing to the v1 `/write` endpoint](/influxdb/cloud-serverless/write-data/api/v1-http/)
- [Migrating from InfluxDB 1.x to {{% product-name %}}](/influxdb/cloud-serverless/guides/migrate-data/migrate-1x-to-v3/)
For InfluxDB to automatically create DBRP mappings and buckets, you must use a [token](/influxdb/cloud-serverless/admin/tokens/) that has write permissions for DBRPs and buckets.
Auto-generated buckets use the [name syntax for mapped buckets](/influxdb/cloud-serverless/guides/api-compatibility/v1/#name-syntax-for-mapped-buckets) and a default retention period equal to the bucket's created date minus 3 days.
To set a bucket's retention period, see how to [update a bucket](/influxdb/cloud-serverless/admin/buckets/update-bucket/).
#### Name syntax for mapped buckets
InfluxDB uses the following naming convention to map database and retention policy names to bucket names:
```text
DATABASE_NAME/RETENTION_POLICY_NAME
```
{{% /code-placeholders %}}
Replace the following:
#### Bucket naming examples
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: your {{% product-name %}} retention policy
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the specified bucket
| v1 Database name | v1 Retention Policy name | Bucket name |
| :--------------- | :----------------------- | :------------------------ |
| db | rp | db/rp |
| telegraf | autogen | telegraf/autogen |
| webmetrics | 1w-downsampled | webmetrics/1w-downsampled |
##### Other Telegraf configuration options
{{% note %}}
To avoid having to add configuration parameters to each CLI command, [set up an active InfluxDB configuration](/influxdb/cloud-serverless/reference/cli/influx/config/set/).
{{% /note %}}
`influx_uint_support`: supported in InfluxDB v3.
### Manage DBRPs
For more plugin options, see [`influxdb`](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) on GitHub.
#### Create DBRP mappings
#### Interactive clients
To create DBRP mappings, use the `influx` CLI or the
InfluxDB HTTP API.
To test InfluxDB v1 API writes interactively from the command line, use common HTTP clients such as cURL and Postman.
{{% note %}}
#### A DBRP combination can only be mapped to a single bucket
Include the following in your request:
- A `db` query string parameter with the name of the bucket to write to.
- A request body that contains a string of data in [line protocol](/influxdb/cloud-serverless/reference/syntax/line-protocol/) syntax.
- a [token](/influxdb/cloud-serverless/admin/tokens/) in one of the following authentication schemes: [Basic authentication](#basic-authentication), [query string authentication](#query-string-authentication), or [token authentication](#authenticate-with-a-token).
- Optional [parameters](#v1-api-write-parameters).
The following example shows how to use the **cURL** command line tool and the {{% product-name %}} v1 API to write line protocol data to a bucket:
{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}}
```sh
curl -i "https://{{< influxdb/host >}}/write?db=BUCKET_NAME&rp=RETENTION_POLICY&precision=s" \
--header "Authorization: Token API_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--data-binary 'home,room=kitchen temp=72 1463683075'
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: your {{% product-name %}} retention policy
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the specified bucket
##### v1 CLI (not supported)
Don't use the v1 CLI with {{% product-name %}}.
While it may coincidentally work, it isn't officially supported.
#### Client libraries
Use language-specific [v1 client libraries](/influxdb/v1/tools/api_client_libraries/) and your custom code to write data to InfluxDB.
v1 client libraries send data in [line protocol](/influxdb/cloud-serverless/reference/syntax/line-protocol/) syntax to the v1 API `/write` endpoint.
The following samples show how to configure **v1** client libraries for writing to {{% product-name %}}:
Each unique DBRP combination can only be mapped to a single bucket.
If you map a DBRP combination that is already mapped to another bucket,
it overwrites the existing DBRP mapping.
{{% /note %}}
{{< tabs-wrapper >}}
{{% tabs %}}
[Node.js](#nodejs)
[Python](#python)
[influx CLI](#)
[InfluxDB API](#)
{{% /tabs %}}
{{% tab-content %}}
<!-- Start NodeJS -->
Create a v1 API client using the [node-influx](/influxdb/v1/tools/api_client_libraries/#javascriptnodejs) JavaScript client library:
Use the [`influx v1 dbrp create` command](/influxdb/cloud-serverless/reference/cli/influx/v1/dbrp/create/)
to map a database and retention policy to a bucket.
Include the following:
{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}}
```js
const Influx = require('influx')
{{< req type="key" >}}
// Instantiate a client for writing to {{% product-name %}} v1 API
const client = new Influx.InfluxDB({
host: '{{< influxdb/host >}}',
port: 443,
protocol: 'https'
database: 'BUCKET_NAME',
username: 'ignored',
password: 'API_TOKEN'
})
- {{< req "\*" >}} a [token](/influxdb/cloud-serverless/admin/tokens/) that has the [necessary permissions](#authorization).
- {{< req "\*" >}} the **database name** to map
- {{< req "\*" >}} the **retention policy** name to map
- {{< req "\*" >}} the [bucket ID](/influxdb/cloud-serverless/admin/buckets/view-buckets/#view-buckets-in-the-influxdb-ui) to map to
- **Default flag** to set the provided retention policy as the [default DBRP mapping](#default-dbrp) for the database.
// When calling write or query functions, specify the retention policy name in options.
<!-- before-test
```sh
influx bucket create -n DATABASE_NAME -r 24h
INFLUX_BUCKET_ID=$(influx bucket list -n DATABASE_NAME | grep 24h0m0s | cut -b 1-16)
```
{{% /code-placeholders %}}
-->
<!-- End NodeJS -->
{{% /tab-content %}}
{{% tab-content %}}
<!-- Start Python -->
<!--pytest-codeblocks:cont-->
Create a v1 API client using the [influxdb-python](/influxdb/v1/tools/api_client_libraries/#python) Python client library:
{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}}
```py
from influxdb import InfluxDBClient
# Instantiate a client for writing to {{% product-name %}} v1 API
client = InfluxDBClient(
host='{{< influxdb/host >}}',
ssl=True,
database='BUCKET_NAME',
username='',
password='API_TOKEN'
headers={'Content-Type': 'text/plain; charset=utf-8'}
)
# When calling write or query functions, specify the retention policy name in options.
{{% code-placeholders "(DATABASE|RETENTION_POLICY|BUCKET|API)_(NAME|TOKEN|ID)" %}}
```sh
influx v1 dbrp create \
--token API_TOKEN \
--org ORG_ID \
--db DATABASE_NAME \
--rp RETENTION_POLICY_NAME \
--bucket-id BUCKET_ID \
--default
```
{{% /code-placeholders %}}
<!-- End Python -->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
<!--pytest-codeblocks:cont-->
<!-- after-test
```sh
test_dbrp=$(influx v1 dbrp list --db DATABASE_NAME --rp RETENTION_POLICY_NAME | grep DATABASE_NAME | cut -b 1-16)
influx v1 dbrp delete --id $test_dbrp
```
-->
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: your {{% product-name %}} retention policy
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the specified bucket
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) that has the [necessary permissions](#authorization)
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the database name to map to the bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY_NAME`{{% /code-placeholder-key %}}: the retention policy name to map to the bucket
- {{% code-placeholder-key %}}`BUCKET_ID`{{% /code-placeholder-key %}}: the [bucket ID](/influxdb/cloud-serverless/admin/buckets/view-buckets/) to map to
The output is the DBRP.
{{% /tab-content %}}
{{% tab-content %}}
Use the [`/api/v2/dbrps` API endpoint](/influxdb/cloud-serverless/api/#operation/PostDBRP)
to create a new DBRP mapping.
{{< api-endpoint endpoint="https://{{< influxdb/host >}}/api/v2/dbrps" method="POST" api-ref="/influxdb/cloud-serverless/api/#operation/PostDBRP" >}}
Include the following:
- **Request method:** `POST`
- **Headers:**
- **Authorization:** `Token` scheme with a [token](/influxdb/cloud-serverless/admin/tokens/) that has the [necessary permissions](#authorization)
- **Content-type:** `application/json`
- **Request body:** JSON object with the following fields:
- **bucketID:** the [bucket ID](/influxdb/cloud-serverless/admin/buckets/view-buckets/) to map to
- **database:** the database name to map to the bucket
- **org** or **orgID:** your organization name or [organization ID](/influxdb/cloud-serverless/admin/organizations/view-orgs/#view-your-organization-id)
- **retention_policy:** the retention policy name to map to the bucket
- Optional: **default:** `true` sets the database name's [default DBRP mapping](#default-dbrp).
{{% code-placeholders "(DATABASE|RETENTION_POLICY|BUCKET|API|ORG)_(NAME|TOKEN|ID)" %}}
```sh
curl --request POST https://{{< influxdb/host >}}/api/v2/dbrps \
--header "Authorization: Token API_TOKEN" \
--header 'Content-type: application/json' \
--data '{
"bucketID": "BUCKET_ID",
"database": "DATABASE_NAME",
"default": true,
"orgID": "ORG_ID",
"retention_policy": "RETENTION_POLICY_NAME"
}'
```
{{% /code-placeholders %}}
If successful, the response status code is `201: Created` and the response body contains the DBRP.
{{% /tab-content %}}
{{< /tabs-wrapper >}}
#### List DBRP mappings
Use the [`influx` CLI](/influxdb/cloud-serverless/reference/cli/influx/) or the
[InfluxDB HTTP API](/influxdb/cloud-serverless/reference/api/) to list all DBRP
mappings and verify that the buckets you want to query are mapped to a database and
retention policy.
{{< tabs-wrapper >}}
{{% tabs %}}
[influx CLI](#)
[InfluxDB HTTP API](#)
{{% /tabs %}}
{{% tab-content %}}
Use the [`influx v1 dbrp list` command](/influxdb/cloud-serverless/reference/cli/influx/v1/dbrp/list/)
to list DBRP mappings.
##### View all DBRP mappings
{{% code-placeholders "(DATABASE|RETENTION_POLICY|BUCKET|API|ORG)_(NAME|TOKEN|ID)" %}}
```sh
influx v1 dbrp list --token API_TOKEN --org ORG_ID \
```
##### Filter DBRP mappings by database
```sh
influx v1 dbrp list \
--token API_TOKEN \
--org ORG_ID \
--db DATABASE_NAME
```
##### Filter DBRP mappings by bucket ID
<!-- before-test
```sh
INFLUX_BUCKET_ID=$(influx bucket list -n DATABASE_NAME | grep 24h | cut -b 1-16)
```
-->
<!--pytest-codeblocks:cont-->
```sh
influx v1 dbrp list \
--token API_TOKEN \
--org ORG_ID \
--bucket-id BUCKET_ID
```
{{% /code-placeholders %}}
{{% /tab-content %}}
{{% tab-content %}}
Use the [`/api/v2/dbrps` API endpoint](/influxdb/cloud-serverless/api/#operation/GetDBRPs) to list DBRP mappings.
{{< api-endpoint endpoint="https://{{< influxdb/host >}}/api/v2/dbrps" method="GET" api-ref="/influxdb/cloud-serverless/api/#operation/GetDBRPs" >}}
Include the following:
- **Request method:** `GET`
- **Headers:**
- **Authorization:** `Token` scheme with your [token](/influxdb/cloud-serverless/admin/tokens/) that has the [necessary permissions](#authorization)
- **Query parameters:**
{{< req type="key" >}}
- {{< req "\*" >}} **orgID:** your [organization ID](/influxdb/cloud-serverless/admin/organizations/view-orgs/#view-your-organization-id)
- **bucketID:** a [bucket ID](/influxdb/cloud-serverless/admin/buckets/view-buckets/) _(to list DBRP mappings for a specific bucket)_
- **database:** a database name _(to list DBRP mappings with a specific database name)_
- **rp:** a retention policy name _(to list DBRP mappings with a specific retention policy name)_
- **id:** a DBRP mapping ID _(to list a specific DBRP mapping)_
{{% code-placeholders "(DATABASE|RETENTION_POLICY|BUCKET|API|ORG)_(NAME|TOKEN|ID)" %}}
##### View all DBRP mappings
```sh
curl --request GET \
https://{{< influxdb/host >}}/api/v2/dbrps \
--header "Authorization: Token API_TOKEN" \
--data-urlencode "orgID=ORG_ID"
```
##### Filter DBRP mappings by database
```sh
curl --request GET \
https://{{< influxdb/host >}}/api/v2/dbrps \
--header "Authorization: Token API_TOKEN" \
--data-urlencode "orgID=ORG_ID" \
--data-urlencode "db=DATABASE_NAME"
```
##### Filter DBRP mappings by bucket ID
```sh
curl --request GET \
https://{{< influxdb/host >}}/api/v2/dbrps \
--header "Authorization: Token API_TOKEN" \
--data-urlencode "orgID=ORG_ID" \
--data-urlencode "bucketID=BUCKET_ID"
```
{{% /code-placeholders %}}
{{% /tab-content %}}
{{% /tabs-wrapper %}}
#### Update a DBRP mapping
Use the [`influx` CLI](/influxdb/cloud-serverless/reference/cli/influx/) or the
[InfluxDB HTTP API](/influxdb/cloud-serverless/reference/api/) to update a DBRP mapping--for example, to change the retention policy name or set the mapping as the [default](#default-dbrp) for the database name.
{{< tabs-wrapper >}}
{{% tabs %}}
[influx CLI](#)
[InfluxDB HTTP API](#)
{{% /tabs %}}
{{% tab-content %}}
Use the [`influx v1 dbrp update` command](/influxdb/cloud-serverless/reference/cli/influx/v1/dbrp/update/)
to update a DBRP mapping.
Include the following:
- a [token](/influxdb/cloud-serverless/admin/tokens/) that has the [necessary permissions](#authorization)
- **DBRP mapping ID** to update
- Optional: **Retention policy** name to update to
- Optional: **Default flag** to set the retention policy as the [default DBRP mapping](#default-dbrp) for the database name.
<!-- before-test
```sh
INFLUX_BUCKET_ID=$(influx bucket list -n DATABASE_NAME | grep 24h | cut -b 1-16)
influx v1 dbrp create --bucket-id $INFLUX_BUCKET_ID --db DATABASE_NAME --rp RETENTION_POLICY
dbrp_id=$(influx v1 dbrp list --bucket-id $INFLUX_BUCKET_ID --db DATABASE_NAME --rp RETENTION_POLICY \
| grep RETENTION_POLICY | cut -b 1-16)
INFLUX_DBRP_ID="$dbrp_id"
```
-->
<!--pytest-codeblocks:cont-->
##### Update the default retention policy
{{% code-placeholders "(DBRP|RETENTION_POLICY|API|ORG)_(NAME|TOKEN|ID)" %}}
```sh
influx v1 dbrp update \
--token API_TOKEN \
--org ORG_ID \
--id DBRP_ID \
--rp RETENTION_POLICY_NAME \
--default
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) that has the [necessary permissions](#authorization)
- {{% code-placeholder-key %}}`DBRP_ID`{{% /code-placeholder-key %}}: the DBRP ID to update
- {{% code-placeholder-key %}}`RETENTION_POLICY_NAME`{{% /code-placeholder-key %}}: a retention policy name to map to the bucket
The output is the DBRP.
{{% /tab-content %}}
{{% tab-content %}}
Use the [`/api/v2/dbrps/{dbrpID}` API endpoint](/influxdb/cloud-serverless/api/#operation/GetDBRPs) to update DBRP mappings.
{{< api-endpoint endpoint="https://{{< influxdb/host >}}/api/v2/dbrps/{dbrpID}" method="PATCH" api-ref="/influxdb/cloud-serverless/api/#operation/PatchDBRPID" >}}
Include the following:
{{< req type="key" >}}
- **Request method:** `PATCH`
- **Headers:**
- {{< req "\*" >}} the **Authorization:** `Token` scheme with a [token](/influxdb/cloud-serverless/admin/tokens/) that has the [necessary permissions](#authorization)
- **Path parameters:**
- {{< req "\*" >}} **id:** the DBRP mapping ID to update
- **Query parameters:**
- {{< req "\*" >}} **orgID:** your [organization ID](/influxdb/cloud-serverless/admin/organizations/view-orgs/#view-your-organization-id)
- **Request body (JSON):**
- **rp:** retention policy name to update to
- **default:** set the retention policy as the [default DBRP mapping](#default-dbrp) for the database name
##### Update the default retention policy
{{% code-placeholders "(DBRP|RETENTION_POLICY|API|ORG)_(NAME|TOKEN|ID)" %}}
```sh
curl --request PATCH \
https://{{< influxdb/host >}}/api/v2/dbrps/DBRP_ID \
--header "Authorization: Token API_TOKEN" \
--data-urlencode "orgID=ORG_ID" \
--data '{
"rp": "RETENTION_POLICY_NAME",
"default": true
}'
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) that has the [necessary permissions](#authorization)
- {{% code-placeholder-key %}}`DBRP_ID`{{% /code-placeholder-key %}}: the DBRP ID to update
- {{% code-placeholder-key %}}`RETENTION_POLICY_NAME`{{% /code-placeholder-key %}}: a retention policy name to map to the bucket
The output is the DBRP.
{{% /tab-content %}}
{{% /tabs-wrapper %}}
#### Delete a DBRP mapping
Use the [`influx` CLI](/influxdb/cloud-serverless/reference/cli/influx/) or the
[InfluxDB API](/influxdb/cloud-serverless/reference/api/) to delete a DBRP mapping.
{{< tabs-wrapper >}}
{{% tabs %}}
[influx CLI](#)
[InfluxDB API](#)
{{% /tabs %}}
{{% tab-content %}}
Use the [`influx v1 dbrp delete` command](/influxdb/cloud-serverless/reference/cli/influx/v1/dbrp/delete/)
to delete a DBRP mapping.
Include the following:
{{< req type="key" >}}
- {{< req "\*" >}} a [token](/influxdb/cloud-serverless/admin/tokens/) that has the [necessary permissions](#authorization)
- {{< req "\*" >}} **DBRP mapping ID** to delete
<!-- before-test
```sh
INFLUX_BUCKET_ID=$(influx bucket list -n DATABASE_NAME | grep 24h | cut -b 1-16)
influx v1 dbrp create --bucket-id $INFLUX_BUCKET_ID --db DATABASE_NAME --rp RETENTION_POLICY
dbrp_id=$(influx v1 dbrp list --bucket-id $INFLUX_BUCKET_ID --db DATABASE_NAME --rp RETENTION_POLICY \
| grep RETENTION_POLICY | cut -b 1-16)
INFLUX_DBRP_ID="$dbrp_id"
```
-->
<!--pytest-codeblocks:cont-->
{{% code-placeholders "(DBRP|API)_(TOKEN|ID)" %}}
```sh
influx v1 dbrp delete \
--token API_TOKEN \
--org ORG_ID \
--id DBRP_ID
```
{{% /code-placeholders %}}
The output is the DBRP.
{{% /tab-content %}}
{{% tab-content %}}
Use the [`/api/v2/dbrps/{dbrpID}` API endpoint](/influxdb/cloud-serverless/api/#operation/DeleteDBRPID)
to delete a DBRP mapping.
{{< api-endpoint endpoint="https://{{< influxdb/host >}}/api/v2/dbrps/{dbrpID}" method="DELETE" api-ref="/influxdb/cloud-serverless/api/#operation/DeleteDBRPID" >}}
Include the following:
{{< req type="key" >}}
- **Request method:** `DELETE`
- **Headers:**
- {{< req "\*" >}} the **Authorization:** `Token` scheme with a [token](/influxdb/cloud-serverless/admin/tokens/) that has the [necessary permissions](#authorization)
- **Path parameters:**
- {{< req "\*" >}} **id:** DBRP mapping ID to update
- **Query parameters:**
- {{< req "\*" >}} **orgID:** [organization ID](/influxdb/cloud-serverless/admin/organizations/view-orgs/#view-your-organization-id)
{{% code-placeholders "(DBRP|API|ORG)_(TOKEN|ID)" %}}
```sh
curl --request DELETE \
https://{{< influxdb/host >}}/api/v2/dbrps/DBRP_ID \
--header "Authorization: Token API_TOKEN" \
--data-urlencode "orgID=ORG_ID"
```
{{% /code-placeholders %}}
{{% /tab-content %}}
{{% /tabs-wrapper %}}
Replace the following:
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) that has the [necessary permissions](#authorization)
- {{% code-placeholder-key %}}`DBRP_ID`{{% /code-placeholder-key %}}: the DBRP ID to update
- {{% code-placeholder-key %}}`ORG_ID`{{% /code-placeholder-key %}}: the [organization ID](/influxdb/cloud-serverless/admin/organizations/view-orgs/#view-your-organization-id)
## Write data
See how to [use the {{% product-name %}} HTTP write API](/influxdb/cloud-serverless/write-data/api/v1-http/) for InfluxDB v1 or v1.x-compatibility workloads.
## Query data
{{% product-name %}} provides the following protocols for executing a query:
See how to [use the {{% product-name %}} HTTP query API](/influxdb/cloud-serverless/query-data/execute-queries/v1-http/) for InfluxDB v1 or v1.x-compatibility workloads.
- [Flight+gRPC](https://arrow.apache.org/docs/format/Flight.html) request that contains an SQL or InfluxQL query.
To learn how to query {{% product-name %}} using Flight and SQL, see the [Get started](/influxdb/cloud-serverless/get-started/) tutorial.
- InfluxDB v1 API `/query` request that contains an InfluxQL query. Use this endpoint with {{% product-name %}} when you bring InfluxDB 1.x workloads that already use [InfluxQL](/influxdb/cloud-serverless/reference/glossary/#influxql) and the v1 API `/query` endpoint.
{{% note %}}
#### Tools to execute queries
{{% product-name %}} supports many different tools for querying data, including:
- [`influx3` data CLI](https://github.com/InfluxCommunity/influxdb3-python-cli)
- [InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/)
- [Flight clients](/influxdb/cloud-serverless/reference/client-libraries/flight-sql/)
- [Superset](/influxdb/cloud-serverless/query-data/sql/execute-queries/superset/)
- [Grafana](/influxdb/cloud-serverless/query-data/sql/execute-queries/grafana/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-serverless/query-data/execute-queries/influxdb-v1-api/)
- [Chronograf](/chronograf/v1/)
{{% /note %}}
### v1 API /query parameters
For {{% product-name %}} v1 API `/query` requests, set parameters as listed in the following table:
Parameter | Allowed in | Ignored | Value
------------|--------------|---------|-------------------------------------------------------------------------
`chunked` | | Ignored | N/A _(Note that an unbounded query might return a large amount of data)_
`db` | Query string | Honored | Bucket name
`epoch` | Query string | Honored | [Timestamp precision](#timestamp-precision)
`pretty` | Query string | Ignored | N/A
`u` | Query string | Ignored | For [query string authentication](#query-string-authentication), any arbitrary string
`p` | Query string | Honored | For [query string authentication](#query-string-authentication), a [token](/influxdb/cloud-serverless/admin/tokens) with permission to write to the bucket
`rp` | Query string | Honored | Retention policy
{{% note %}}
When bringing v1 API workloads to {{% product-name %}}, you'll need to adjust request parameters in your client configuration or code.
{{% /note %}}
#### Timestamp precision
Use one of the following values for timestamp precision:
- `ns`: nanoseconds
- `us`: microseconds
- `ms`: milliseconds
- `s`: seconds
- `m`: minutes
- `h`: hours
### Bucket management with InfluxQL (not supported)
## Bucket management with InfluxQL (not supported)
{{% product-name %}} doesn't allow InfluxQL commands for managing or modifying buckets.
You can't use the following InfluxQL commands:
@ -506,3 +740,10 @@ ALTER
SET
KILL
```
<!-- after-test
```sh
influx bucket delete -n DATABASE_NAME
influx bucket delete -n DATABASE_NAME/RETENTION_POLICY_NAME; exit 0
```
-->

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

@ -20,6 +20,13 @@ related:
- /influxdb/cloud-serverless/write-data/use-telegraf/configure/
- /influxdb/cloud-serverless/reference/api/
- /influxdb/cloud-serverless/reference/client-libraries/
list_code_example: |
```sh
curl \
--post "https://{{< influxdb/host >}}/api/v2/write?bucket=BUCKET_NAME&precision=s" \
--header "Authorization: Token API_TOKEN" \
--data-binary 'home,room=kitchen temp=72 1463683075'
```
---
{{% product-name %}} is compatible with the InfluxDB v2 API `/api/v2/write` endpoint and existing InfluxDB 2.x tools and code.
@ -28,26 +35,15 @@ Use the InfluxDB v2 API for new write workloads and existing v2 write workloads
InfluxDB v2 API endpoints won't work for managing resources or querying data in {{% product-name %}}.
To query data, use the _Flight+gRPC_ protocol or the InfluxDB v1 `/query` HTTP API endpoint and [associated tools](#tools-to-execute-queries).
<!-- TOC -->
- [Authenticate API requests](#authenticate-api-requests)
- [Authenticate with a token](#authenticate-with-a-token)
- [Syntax](#syntax)
- [Examples](#examples)
- [Responses](#responses)
- [Error examples](#error-examples)
- [Write data](#write-data)
- [/api/v2/write parameters](#apiv2write-parameters)
- [Timestamp precision](#timestamp-precision)
- [Tools for writing to the v2 API](#tools-for-writing-to-the-v2-api)
- [Telegraf](#telegraf)
- [Interactive clients](#interactive-clients)
- [Client libraries](#client-libraries)
- [Query data](#query-data)
- [Tools to execute queries](#tools-to-execute-queries)
- [Avoid using /api/v2/query](#avoid-using-apiv2query)
<!-- /TOC -->
## Authenticate API requests

15
content/influxdb/cloud-serverless/guides/prototype-evaluation.md
View File

@ -81,12 +81,14 @@ impact using Cloud Serverless for evaluation, prototyping, or staging.
### InfluxQL data retention policy mapping differences
InfluxDB utilizes database and retention policy (DBRP) mappings to support
InfluxQL queries written for InfluxDB 1.x. To query using InfluxQL, InfluxDB
Cloud Serverless requires that customers first create DBRP mappings
(via the CLI or API) for the bucket.
In Cloud Dedicated, DBRP mapping is handled through naming conventions and
InfluxQL queries written for the InfluxDB 1.x `/query` endpoint.
In InfluxDB Cloud Dedicated, DBRP mapping is handled through naming conventions and
doesn’t require customers to configure a mapping for InfluxQL queries.
InfluxDB Cloud Serverless requires that a DBRP mapping be created
for a bucket before customers can use the v1 `/query` endpoint to query data from the bucket. InfluxDB Cloud Serverless can automatically create a bucket and an associated DBRP mapping, or customers can create them using the CLI or API.
### Query Language Differences
InfluxDB Cloud Serverless and Cloud Dedicated support SQL and InfluxQL.
@ -96,15 +98,14 @@ InfluxDB Cloud Serverless and Cloud Dedicated support SQL and InfluxQL.
| SQL | Natively supported | Natively supported |
| InfluxQL | Natively supported | Natively supported |
The v2 API (which uses the Flux language for querying) is reachable in InfluxDB
The v2 query API (which uses the Flux language for querying) is reachable in InfluxDB
Cloud Serverless, but isn't supported. If you plan to use InfluxDB Cloud
Serverless as an evaluation or staging platform for InfluxDB Cloud Dedicated,
use SQL or InfluxQL.
### API and client library differences
Because the v2 Query API uses Flux, customers should avoid using the v2 API when
querying InfluxDB Cloud Serverless as an evaluation, staging, or prototyping
Because the v2 query API uses Flux, customers should avoid using the v2 query API and its associated tooling when querying InfluxDB Cloud Serverless as an evaluation, staging, or prototyping
platform for InfluxDB Cloud Dedicated.
For writing data, InfluxDB Cloud Dedicated and InfluxDB Cloud Serverless both

2
content/influxdb/cloud-serverless/query-data/_index.md
View File

@ -19,7 +19,7 @@ Learn to query data stored in InfluxDB.
#### Choose the query method for your workload
- For new query workloads, use one of the many available [Flight clients](/influxdb/cloud-serverless/tags/flight-client/) and SQL or InfluxQL.
- [Use the HTTP API `/query` endpoint and InfluxQL](/influxdb/cloud-serverless/query-data/execute-queries/influxdb-v1-api/) when you bring existing v1 query workloads to {{% product-name %}}.
- [Use the HTTP API `/query` endpoint and InfluxQL](/influxdb/cloud-serverless/query-data/execute-queries/v1-http/) when you bring existing v1 query workloads to {{% product-name %}}.
{{% /note %}}

21
content/influxdb/cloud-serverless/query-data/execute-queries/_index.md
View File

@ -16,16 +16,21 @@ aliases:
Use tools and libraries to query data stored in an {{% product-name %}} bucket.
InfluxDB client libraries and Flight clients can use the Flight+gRPC protocol to query with SQL or InfluxQL and retrieve data in the [Arrow in-memory format](https://arrow.apache.org/docs/format/Columnar.html).
HTTP clients can use the InfluxDB v1 `/query` REST API to query with InfluxQL and retrieve data in JSON format.
InfluxDB v3 supports the following APIs and languages for querying data:
{{% note %}}
#### Map databases and retention policies to buckets
- Flight+RPC with SQL or InfluxQL.
Use InfluxDB client libraries and Flight+RPC clients to query with SQL or InfluxQL and retrieve data in [Arrow in-memory format](https://arrow.apache.org/docs/format/Columnar.html).
- Flight SQL with SQL or InfluxQL.
Use Flight SQL clients to query with SQL or InfluxQL and retrieve data in [Arrow in-memory format](https://arrow.apache.org/docs/format/Columnar.html).
- HTTP `/query` endpoint for InfluxDB v1 compatibility when you bring workloads and code from v1.x to v3.
Use the `/query` endpoint with InfluxQL and tools such as Telegraf, HTTP clients, and InfluxDB v1 client libraries to query and retrieve data in JSON or CSV format.
Before using InfluxQL, make sure database and retention policy (DBRP)
combinations are mapped to buckets. For more information, see
[Map databases and retention policies to buckets](/influxdb/cloud-serverless/query-data/influxql/dbrp/).
{{% /note %}}
{{% warn %}}
#### /api/v2/query endpoint can't query InfluxDB v3
{{% product-name %}} doesn't support the InfluxDB v2 HTTP `/api/v2/query` endpoint and isn't optimized for the Flux query language.
Use SQL or InfluxQL to query data stored in InfluxDB v3.
{{% /warn %}}
Learn how to connect to InfluxDB and query your data using the following tools:

137
content/influxdb/cloud-serverless/query-data/execute-queries/influxdb-v1-api.md
View File

@ -1,137 +0,0 @@
---
title: Use the InfluxDB v1 HTTP query API and InfluxQL to query data
seotitle: Use InfluxQL and InfluxDB v1 HTTP query API
list_title: Use the v1 query API and InfluxQL
description: >
Use the InfluxDB v1 HTTP query API to query data in InfluxDB Cloud Serverless
with InfluxQL.
weight: 301
menu:
influxdb_cloud_serverless:
parent: Execute queries
name: Use the v1 query API
influxdb/cloud-serverless/tags: [query, influxql, python]
metadata: [InfluxQL]
related:
- /influxdb/cloud-serverless/guides/api-compatibility/v1/
aliases:
- /influxdb/cloud-serverless/query-data/influxql/execute-queries/influxdb-v1-api/
list_code_example: |
```sh
curl --get https://{{< influxdb/host >}}/query \
--header "Authorization: Token API_TOKEN" \
--data-urlencode "db=BUCKET_NAME" \
--data-urlencode "q=SELECT * FROM home"
```
---
Use the InfluxDB v1 HTTP query API to query data in {{< product-name >}}
with InfluxQL.
The examples below use **cURL** to send HTTP requests to the InfluxDB v1 HTTP API,
but you can use any HTTP client.
{{% note %}}
#### Databases and retention policies map to InfluxDB buckets
InfluxQL **databases** and **retention policies** are used to route queries to
an InfluxDB **bucket** based on database and retention policy (DBRP) mappings.
For more information, see
[Map databases and retention policies to buckets](/influxdb/cloud-serverless/query-data/influxql/dbrp/).
{{% /note %}}
{{% warn %}}
#### InfluxQL feature support
InfluxQL is being rearchitected to work with the InfluxDB v3 storage engine.
This process is ongoing and some InfluxQL features are still being implemented.
For information about the current implementation status of InfluxQL features,
see [InfluxQL feature support](/influxdb/cloud-serverless/reference/influxql/feature-support/).
{{% /warn %}}
Use the v1 `/query` endpoint and the `GET` request method to query data with InfluxQL:
{{< api-endpoint endpoint="https://{{< influxdb/host >}}/query" method="get" api-ref="/influxdb/cloud-serverless/api/#tag/Query" >}}
Provide the following with your request:
- **Headers:**
- **Authorization:** `Token API_TOKEN`
- **Query parameters:**
- **db**: the database (bucket) to query
- **rp**: the [retention policy](/influxdb/cloud-serverless/query-data/influxql/dbrp/) to query.
Required if you haven't configured a default retention policy for the bucket.
- **q**: URL-encoded InfluxQL query
{{% code-placeholders "DATABASE_NAME|API_TOKEN" %}}
```sh
curl --get https://{{< influxdb/host >}}/query \
--header "Authorization: Token API_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM home"
```
{{% /code-placeholders %}}
Replace the following configuration values:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
the name of the [database (bucket)](/influxdb/cloud-serverless/admin/buckets/) to query
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}:
an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the specified database.
{{% note %}}
#### Authenticate with username and password
If using basic authentication or query string authentication (username and password)
to interact with the v1 HTTP query API, provide the following credentials:
- **username**: an arbitrary string _({{< product-name >}} ignores the username)_
- **password**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the specified database.
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[Basic Auth](#)
[Query String Auth](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}}
```sh
curl --get https://{{< influxdb/host >}}/query \
--header "Authorization: Basic ignored:DATABASE_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM home"
```
{{% /code-placeholders %}}
{{% /code-tab-content %}}
{{% code-tab-content %}}
{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}}
```sh
curl --get https://{{< influxdb/host >}}/query \
--data-urlencode "u=ignored" \
--data-urlencode "p=DATABASE_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM home"
```
{{% /code-placeholders %}}
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
{{% /note %}}
## Return results as JSON or CSV
By default, the `/query` endpoint returns results in **JSON**, but it can also
return results in **CSV**. To return results as CSV, include the `Accept` header
with the `application/csv` or `text/csv` MIME type:
{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}}
```sh
curl --get https://{{< influxdb/host >}}/query \
--header "Authorization: Token DATABASE_TOKEN" \
--header "Accept: application/csv" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM home"
```
{{% /code-placeholders %}}

176
content/influxdb/cloud-serverless/query-data/execute-queries/v1-http.md Normal file
View File

@ -0,0 +1,176 @@
---
title: Use the InfluxDB v1 HTTP query API and InfluxQL
seotitle: Use InfluxQL and InfluxDB v1 HTTP query API
list_title: Use the v1 query API and InfluxQL
description: >
Use the InfluxDB v1 HTTP query API to query data in InfluxDB Cloud Serverless
with InfluxQL.
weight: 301
menu:
influxdb_cloud_serverless:
parent: Execute queries
name: Use the v1 HTTP query API
influxdb/cloud-serverless/tags: [query, influxql, python]
metadata: [InfluxQL]
related:
- /influxdb/cloud-serverless/guides/api-compatibility/v1/
aliases:
- /influxdb/cloud-serverless/query-data/influxql/execute-queries/influxdb-v1-api/
- /influxdb/cloud-serverless/query-data/execute-queries/influxdb-v1-api/
list_code_example: |
```sh
curl https://{{< influxdb/host >}}/query \
--header "Authorization: Token API_TOKEN" \
--data-urlencode "db=BUCKET_NAME" \
--data-urlencode "q=SELECT * FROM home"
```
---
Use the InfluxDB v1 HTTP API `/query` endpoint and InfluxQL to query data stored in {{< product-name >}} and return results in JSON or CSV format.
The `/query` endpoint provides compatibility for InfluxDB 1.x workloads that you bring to InfluxDB v3.
_Before you can use the v1 query API,
[databases and retention policies must be mapped to buckets](/influxdb/cloud-serverless/guides/api-compatibility/v1/#map-v1-databases-and-retention-policies-to-buckets)._
{{% note %}}
#### Flight queries don't use DBRP mappings
When using Flight RPC or Flight SQL to query InfluxDB, specify the **bucket name**.
Flight queries don't use DBRP mappings.
See how to [get started querying with Flight and SQL or InfluxQL](/influxdb/cloud-serverless/get-started/query/).
{{% /note %}}
- [Query the v1 /query endpoint](#query-the-v1-query-endpoint)
- [Parameters](#parameters)
- [Authorization](#authorization)
- [Return results as JSON or CSV](#return-results-as-json-or-csv)
- [Tools for querying the v1 API](#tools-for-querying-the-v1-api)
- [Interactive clients](#interactive-clients)
- [Troubleshoot failures](#troubleshoot-failures)
- [Database not found](#database-not-found)
- [Quota and limit errors](#quota-and-limit-errors)
## Query the v1 /query endpoint
To query using HTTP and InfluxQL, send a `GET` or `POST` request to the v1 `/query` endpoint.
{{< api-endpoint endpoint="https://{{< influxdb/host >}}/query" method="get" api-ref="/influxdb/cloud-serverless/api/#operation/GetLegacyQuery" >}}
### Parameters
For {{% product-name %}} v1 API `/query` requests, set parameters as listed in the following table:
Parameter | Allowed in | Ignored | Value
------------|--------------|---------|-------------------------------------------------------------------------
`chunked` | | Ignored | N/A _(Note that an unbounded query might return a large amount of data)_
`db` | Query string | Honored | Database name [mapped to a bucket](/influxdb/cloud-serverless/guides/api-compatibility/v1/#map-v1-databases-and-retention-policies-to-buckets)
`epoch` | Query string | Honored | [Timestamp precision](#timestamp-precision)
`pretty` | Query string | Ignored | N/A
`rp` | Query string | Honored | Retention policy [mapped to a bucket](/influxdb/cloud-serverless/guides/api-compatibility/v1/#map-v1-databases-and-retention-policies-to-buckets)
`q` | Query string | Honored | [InfluxQL](/influxdb/cloud-serverless/query-data/influxql/)
[`Authorization` header or `u` and `p`](#authorization) | | | [Token](#authorization)
{{% note %}}
When bringing v1 API workloads to {{% product-name %}}, you'll need to adjust request parameters in your client configuration or code.
{{% /note %}}
#### Timestamp precision
Use one of the following values for timestamp precision (`epoch`):
- `ns`: nanoseconds
- `us`: microseconds
- `ms`: milliseconds
- `s`: seconds
- `m`: minutes
- `h`: hours
### Authorization
To authorize a query request, include a [token](/influxdb/cloud-serverless/admin/tokens/) that has read permission for the bucket.
Use [`Token` authentication](/influxdb/cloud-serverless/guides/api-compatibility/v1/#authenticate-with-a-token-scheme) or v1-compatible [username and password authentication](/influxdb/cloud-serverless/guides/api-compatibility/v1/#authenticate-with-a-username-and-password-scheme) to include a token in the request.
### Return results as JSON or CSV
By default, the `/query` endpoint returns results in **JSON** format.
To return results in CSV format, include the `Accept` header
with the `application/csv` or `text/csv` MIME type--for example:
{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}}
```sh
curl --get https://{{< influxdb/host >}}/query \
--header "Authorization: Token DATABASE_TOKEN" \
--header "Accept: application/csv" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM home"
```
{{% /code-placeholders %}}
## Tools for querying the v1 API
### Interactive clients
To test InfluxDB v1 API queries interactively from the command line, use common HTTP clients such as cURL and Postman.
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[Token Auth](#)
[Basic Auth](#)
[Query String Auth](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
{{% code-placeholders "DATABASE_NAME|API_TOKEN" %}}
```sh
curl https://{{< influxdb/host >}}/query \
--header "Authorization: Token API_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM home"
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
the [database name mapped to the bucket](/influxdb/cloud-serverless/guides/api-compatibility/v1/#map-v1-databases-and-retention-policies-to-buckets)
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}:
an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the specified database.
{{% /code-tab-content %}}
{{% code-tab-content %}}
{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}}
```sh
curl --get https://{{< influxdb/host >}}/query \
-user "":"API_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM home"
```
{{% /code-placeholders %}}
{{% /code-tab-content %}}
{{% code-tab-content %}}
{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}}
```sh
curl --get https://{{< influxdb/host >}}/query \
--data-urlencode "u=ignored" \
--data-urlencode "p=DATABASE_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM home"
```
{{% /code-placeholders %}}
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
## Troubleshoot failures
Troubleshoot problems and errors encountered when using the HTTP API to query {{% product-name %}}.
### Database not found
If a DBRP doesn't exist for the `db=DATABASE_NAME` and `rp=RETENTION_POLICY_NAME` combination in the query request, the response body contains an error message, for example `"database not found:..."`.
### Quota and limit errors
HTTP API `/query` requests are subject to [usage quotas and limits](/influxdb/cloud-serverless/admin/billing/).

2
content/influxdb/cloud-serverless/query-data/influxql/_index.md
View File

@ -13,7 +13,7 @@ cascade:
- /influxdb/cloud-serverless/reference/influxql
---
Learn to use InfluxQL to query data stored in InfluxDB Cloud Serverless.
Learn to use InfluxQL to query data stored in {{% product-name %}}.
{{< children type="anchored-list" >}}

355
content/influxdb/cloud-serverless/query-data/influxql/dbrp.md
View File

@ -1,355 +0,0 @@
---
title: Map databases and retention policies to buckets
description: >
To query an an InfluxDB Cloud Serverless bucket with InfluxQL, first map each
database and retention policy (DBRP) combination to a bucket.
menu:
influxdb_cloud_serverless:
name: DBRP mappings
parent: Query with InfluxQL
weight: 101
---
InfluxQL requires a database and retention policy (DBRP) combination in order to query data.
In {{< product-name >}}, databases and retention policies are
combined and replaced by InfluxDB [buckets](/influxdb/cloud-serverless/reference/glossary/#bucket).
To query an {{< product-name >}} bucket with InfluxQL, first map each DBRP
combination to a bucket.
- [Automatic DBRP mapping](#automatic-dbrp-mapping)
- [Create DBRP mappings](#create-dbrp-mappings)
- [List DBRP mappings](#list-dbrp-mappings)
- [Update a DBRP mapping](#update-a-dbrp-mapping)
- [Delete a DBRP mapping](#delete-a-dbrp-mapping)
## Automatic DBRP mapping
{{< product-name >}} automatically creates DBRP mappings for you during the
following operations:
- Writing to the [`/write` v1 compatibility endpoint](/influxdb/cloud-serverless/guides/api-compatibility/v1/#write-data)
- [Upgrading from InfluxDB 1.x to InfluxDB Cloud](/influxdb/v2/upgrade/v1-to-cloud/)
For more information, see [Database and retention policy mapping](/influxdb/cloud-serverless/api/#tag/DBRPs).
## Create DBRP mappings
Use the [`influx` CLI](/influxdb/cloud-serverless/reference/cli/influx/) or the
[InfluxDB API](/influxdb/cloud-serverless/reference/api/) to create DBRP mappings.
{{% note %}}
#### A DBRP combination can only be mapped to a single bucket
Each unique DBRP combination can only be mapped to a single bucket.
If you map a DBRP combination that is already mapped to another bucket,
it will overwrite the existing DBRP mapping.
{{% /note %}}
{{< tabs-wrapper >}}
{{% tabs %}}
[influx CLI](#)
[InfluxDB API](#)
{{% /tabs %}}
{{% tab-content %}}
Use the [`influx v1 dbrp create` command](/influxdb/cloud-serverless/reference/cli/influx/v1/dbrp/create/)
to map a database and retention policy to a bucket.
Include the following:
{{< req type="key" >}}
- {{< req "\*" >}} **API token** to authenticate. We recommend setting your token to
your active InfluxDB connection configuration in the `influx` CLI, so you don't
have to add these parameters to each command.
To set up your active InfluxDB configuration, see
[`influx config set`](/influxdb/cloud-serverless/reference/cli/influx/config/set/).
- {{< req "\*" >}} **database name** to map
- {{< req "\*" >}} **retention policy** name to map
- {{< req "\*" >}} [Bucket ID](/influxdb/cloud-serverless/admin/buckets/view-buckets/#view-buckets-in-the-influxdb-ui) to map to
- **Default flag** to set the provided retention policy as the default retention policy for the database
{{% code-placeholders "(DATABASE|RETENTION_POLICY|BUCKET|API)_(NAME|TOKEN|ID)" %}}
```sh
influx v1 dbrp create \
--token API_TOKEN \
--db DATABASE_NAME \
--rp RETENTION_POLICY_NAME \
--bucket-id BUCKET_ID \
--default
```
{{% /code-placeholders %}}
{{% /tab-content %}}
{{% tab-content %}}
Use the [`/api/v2/dbrps` API endpoint](/influxdb/cloud-serverless/api/#operation/PostDBRP)
to create a new DBRP mapping.
{{< api-endpoint endpoint="https://{{< influxdb/host >}}/api/v2/dbrps" method="POST" api-ref="/influxdb/cloud-serverless/api/#operation/PostDBRP" >}}
Include the following:
- **Request method:** `POST`
- **Headers:**
- **Authorization:** `Token` schema with your InfluxDB [API token](/influxdb/cloud-serverless/admin/tokens/)
- **Content-type:** `application/json`
- **Request body:** JSON object with the following fields:
{{< req type="key" >}}
- {{< req "\*" >}} **bucketID:** [bucket ID](/influxdb/cloud-serverless/admin/buckets/view-buckets/)
- {{< req "\*" >}} **database:** database name
- **default:** set the provided retention policy as the default retention policy for the database
- {{< req "\*" >}} **org** or **orgID:** organization name or [organization ID](/influxdb/cloud-serverless/admin/organizations/view-orgs/#view-your-organization-id)
- {{< req "\*" >}} **retention_policy:** retention policy name
{{% code-placeholders "(DATABASE|RETENTION_POLICY|BUCKET|API|ORG)_(NAME|TOKEN|ID)" %}}
```sh
curl --request POST https://{{< influxdb/host >}}/api/v2/dbrps \
--header "Authorization: Token API_TOKEN" \
--header 'Content-type: application/json' \
--data '{
"bucketID": "BUCKET_ID",
"database": "DATABASE_NAME",
"default": true,
"orgID": "ORG_ID",
"retention_policy": "RETENTION_POLICY_NAME"
}'
```
{{% /code-placeholders %}}
{{% /tab-content %}}
{{< /tabs-wrapper >}}
## List DBRP mappings
Use the [`influx` CLI](/influxdb/cloud-serverless/reference/cli/influx/) or the
[InfluxDB HTTP API](/influxdb/cloud-serverless/reference/api/) to list all DBRP
mappings and verify the buckets you want to query are mapped to a database and
retention policy.
{{< tabs-wrapper >}}
{{% tabs %}}
[influx CLI](#)
[InfluxDB HTTP API](#)
{{% /tabs %}}
{{% tab-content %}}
Use the [`influx v1 dbrp list` command](/influxdb/cloud-serverless/reference/cli/influx/v1/dbrp/list/)
to list DBRP mappings.
##### View all DBRP mappings
{{% code-placeholders "(DATABASE|RETENTION_POLICY|BUCKET|API|ORG)_(NAME|TOKEN|ID)" %}}
```sh
influx v1 dbrp list --token API_TOKEN
```
##### Filter DBRP mappings by database
```sh
influx v1 dbrp list \
--token API_TOKEN \
--db DATABASE_NAME
```
##### Filter DBRP mappings by bucket ID
```sh
influx v1 dbrp list \
--token API_TOKEN \
--bucket-id BUCKET_ID
```
{{% /code-placeholders %}}
{{% /tab-content %}}
{{% tab-content %}}
Use the [`/api/v2/dbrps` API endpoint](/influxdb/cloud-serverless/api/#operation/GetDBRPs) to list DBRP mappings.
{{< api-endpoint endpoint="https://{{< influxdb/host >}}/api/v2/dbrps" method="GET" api-ref="/influxdb/cloud-serverless/api/#operation/GetDBRPs" >}}
Include the following:
- **Request method:** `GET`
- **Headers:**
- **Authorization:** `Token` schema with your InfluxDB [API token](/influxdb/cloud-serverless/admin/tokens/)
- **Query parameters:**
{{< req type="key" >}}
- {{< req "\*" >}} **orgID:** [organization ID](/influxdb/cloud-serverless/admin/organizations/view-orgs/#view-your-organization-id)
- **bucketID:** [bucket ID](/influxdb/cloud-serverless/admin/buckets/view-buckets/) _(to list DBRP mappings for a specific bucket)_
- **database:** database name _(to list DBRP mappings with a specific database name)_
- **rp:** retention policy name _(to list DBRP mappings with a specific retention policy name)_
- **id:** DBRP mapping ID _(to list a specific DBRP mapping)_
{{% code-placeholders "(DATABASE|RETENTION_POLICY|BUCKET|API|ORG)_(NAME|TOKEN|ID)" %}}
##### View all DBRP mappings
```sh
curl --request GET \
https://{{< influxdb/host >}}/api/v2/dbrps \
--header "Authorization: Token API_TOKEN" \
--data-urlencode "orgID=ORG_ID"
```
##### Filter DBRP mappings by database
```sh
curl --request GET \
https://{{< influxdb/host >}}/api/v2/dbrps \
--header "Authorization: Token API_TOKEN" \
--data-urlencode "orgID=ORG_ID" \
--data-urlencode "db=DATABASE_NAME"
```
##### Filter DBRP mappings by bucket ID
```sh
curl --request GET \
https://{{< influxdb/host >}}/api/v2/dbrps \
--header "Authorization: Token API_TOKEN" \
--data-urlencode "orgID=ORG_ID" \
--data-urlencode "bucketID=BUCKET_ID"
```
{{% /code-placeholders %}}
{{% /tab-content %}}
{{% /tabs-wrapper %}}
## Update a DBRP mapping
Use the [`influx` CLI](/influxdb/cloud-serverless/reference/cli/influx/) or the
[InfluxDB HTTP API](/influxdb/cloud-serverless/reference/api/) to update a DBRP mapping.
{{< tabs-wrapper >}}
{{% tabs %}}
[influx CLI](#)
[InfluxDB HTTP API](#)
{{% /tabs %}}
{{% tab-content %}}
Use the [`influx v1 dbrp update` command](/influxdb/cloud-serverless/reference/cli/influx/v1/dbrp/update/)
to update a DBRP mapping.
Include the following:
{{< req type="key" >}}
- {{< req "\*" >}} **API token** to authenticate. We recommend setting your token to
your active InfluxDB connection configuration in the influx CLI, so you don't
have to add these parameters to each command.
To set up your active InfluxDB configuration, see
[`influx config set`](/influxdb/cloud-serverless/reference/cli/influx/config/set/).
- {{< req "\*" >}} **DBRP mapping ID** to update
- **Retention policy** name to update to
- **Default flag** to set the retention policy as the default retention policy for the database
##### Update the default retention policy
{{% code-placeholders "(DBRP|RETENTION_POLICY|API)_(NAME|TOKEN|ID)" %}}
```sh
influx v1 dbrp update \
--token API_TOKEN \
--id DBRP_ID \
--rp RETENTION_POLICY_NAME \
--default
```
{{% /code-placeholders %}}
{{% /tab-content %}}
{{% tab-content %}}
Use the [`/api/v2/dbrps/{dbrpID}` API endpoint](/influxdb/cloud-serverless/api/#operation/GetDBRPs) to update DBRP mappings.
{{< api-endpoint endpoint="https://{{< influxdb/host >}}/api/v2/dbrps/{dbrpID}" method="PATCH" api-ref="/influxdb/cloud-serverless/api/#operation/PatchDBRPID" >}}
Include the following:
{{< req type="key" >}}
- **Request method:** `PATCH`
- **Headers:**
- {{< req "\*" >}} **Authorization:** `Token` schema with your InfluxDB [API token](/influxdb/cloud-serverless/admin/tokens/)
- **Path parameters:**
- {{< req "\*" >}} **id:** DBRP mapping ID to update
- **Query parameters:**
- {{< req "\*" >}} **orgID:** [organization ID](/influxdb/cloud-serverless/admin/organizations/view-orgs/#view-your-organization-id)
- **Request body (JSON):**
- **rp:** retention policy name to update to
- **default:** set the retention policy as the default retention policy for the database
##### Update the default retention policy
{{% code-placeholders "(DBRP|RETENTION_POLICY|API|ORG)_(NAME|TOKEN|ID)" %}}
```sh
curl --request PATCH \
https://{{< influxdb/host >}}/api/v2/dbrps/DBRP_ID \
--header "Authorization: Token API_TOKEN" \
--data-urlencode "orgID=ORG_ID" \
--data '{
"rp": "RETENTION_POLICY_NAME",
"default": true
}'
```
{{% /code-placeholders %}}
{{% /tab-content %}}
{{% /tabs-wrapper %}}
## Delete a DBRP mapping
Use the [`influx` CLI](/influxdb/cloud-serverless/reference/cli/influx/) or the
[InfluxDB API](/influxdb/cloud-serverless/reference/api/) to delete a DBRP mapping.
{{< tabs-wrapper >}}
{{% tabs %}}
[influx CLI](#)
[InfluxDB API](#)
{{% /tabs %}}
{{% tab-content %}}
Use the [`influx v1 dbrp delete` command](/influxdb/cloud-serverless/reference/cli/influx/v1/dbrp/delete/)
to delete a DBRP mapping.
Include the following:
{{< req type="key" >}}
- {{< req "\*" >}} **API token** to authenticate. We recommend setting your token to
your active InfluxDB connection configuration in the influx CLI, so you don't
have to add these parameters to each command.
To set up your active InfluxDB configuration, see
[`influx config set`](/influxdb/cloud-serverless/reference/cli/influx/config/set/).
- {{< req "\*" >}} **DBRP mapping ID** to delete
{{% code-placeholders "(DBRP|API)_(TOKEN|ID)" %}}
```sh
influx v1 dbrp delete \
--token API_TOKEN \
--id DBRP_ID
```
{{% /code-placeholders %}}
{{% /tab-content %}}
{{% tab-content %}}
Use the [`/api/v2/dbrps/{dbrpID}` API endpoint](/influxdb/cloud-serverless/api/#operation/DeleteDBRPID)
to delete a DBRP mapping.
{{< api-endpoint endpoint="https://{{< influxdb/host >}}/api/v2/dbrps/{dbrpID}" method="DELETE" api-ref="/influxdb/cloud-serverless/api/#operation/DeleteDBRPID" >}}
Include the following:
{{< req type="key" >}}
- **Request method:** `PATCH`
- **Headers:**
- {{< req "\*" >}} **Authorization:** `Token` schema with your InfluxDB
[API token](/influxdb/cloud-serverless/admin/tokens/)
- **Path parameters:**
- {{< req "\*" >}} **id:** DBRP mapping ID to update
- **Query parameters:**
- {{< req "\*" >}} **orgID:** [organization ID](/influxdb/cloud-serverless/admin/organizations/view-orgs/#view-your-organization-id)
{{% code-placeholders "(DBRP|API|ORG)_(TOKEN|ID)" %}}
```sh
curl --request DELETE \
https://{{< influxdb/host >}}/api/v2/dbrps/DBRP_ID \
--header "Authorization: Token API_TOKEN" \
--data-urlencode "orgID=ORG_ID"
```
{{% /code-placeholders %}}
{{% /tab-content %}}
{{% /tabs-wrapper %}}

9
content/influxdb/cloud-serverless/query-data/execute-queries/optimize-queries.md → content/influxdb/cloud-serverless/query-data/optimize-queries.md
View File

@ -6,27 +6,25 @@ weight: 401
menu:
influxdb_cloud_serverless:
name: Optimize queries
parent: Execute queries
parent: Query data
influxdb/cloud-serverless/tags: [query, sql, influxql]
related:
- /influxdb/cloud-serverless/query-data/sql/
- /influxdb/cloud-serverless/query-data/influxql/
- /influxdb/cloud-serverless/query-data/execute-queries/troubleshoot/
- /influxdb/cloud-serverless/reference/client-libraries/v3/
aliases:
- /influxdb/cloud-serverless/query-data/execute-queries/optimize-queries/
---
## Troubleshoot query performance
Use the following tools to help you identify performance bottlenecks and troubleshoot problems in queries:
<!-- TOC -->
- [Troubleshoot query performance](#troubleshoot-query-performance)
- [EXPLAIN and ANALYZE](#explain-and-analyze)
- [Enable trace logging](#enable-trace-logging)
<!-- /TOC -->
### EXPLAIN and ANALYZE
To view the query engine's execution plan and metrics for an SQL query, prepend [`EXPLAIN`](/influxdb/cloud-serverless/reference/sql/explain/) or [`EXPLAIN ANALYZE`](/influxdb/cloud-serverless/reference/sql/explain/#explain-analyze) to the query.
@ -40,6 +38,7 @@ import os
```
-->
<!--pytest-codeblocks:cont-->
{{% code-placeholders "BUCKET_NAME|API_TOKEN|APP_REQUEST_ID" %}}
```python
from influxdb_client_3 import InfluxDBClient3

9
content/influxdb/cloud-serverless/reference/glossary.md
View File

@ -238,9 +238,9 @@ For more information about different data types, see:
- [InfluxQL](/influxdb/v1/query_language/spec/#literals)
- [InfluxDB](/influxdb/v2/reference/syntax/line-protocol/#data-types-and-format)
#### database
### database
In InfluxDB Cloud Dedicated, a named location where time series data is stored.
In _InfluxDB Cloud Dedicated_, a named location where time series data is stored.
This is equivalent to a _bucket_ in _InfluxDB Cloud Serverless_.
In InfluxDB 1.x, a database represented a logical container for users, retention
@ -249,6 +249,7 @@ In InfluxDB 2.x, the equivalent of this concept is an InfluxDB [bucket](#bucket)
Related entries:
[bucket](#bucket),
[retention period](#retention-period),
[retention policy](#retention-policy-rp)
### date-time
@ -259,6 +260,10 @@ Specifying a timestamp is optional.
If a timestamp isn't specified for a data point, InfluxDB uses the server’s
local nanosecond timestamp in UTC.
### DBRP mapping
For {{% product-name %}} compatibility with InfluxDB v1 `/write` and `query` endpoints, maps an InfluxDB v1 database and retention policy combination to a bucket.
### downsample
Aggregating high resolution data into lower resolution data to preserve disk space.

294
content/influxdb/cloud-serverless/write-data/api/v1-http.md Normal file
View File

@ -0,0 +1,294 @@
---
title: Use the InfluxDB v1 HTTP write API
seotitle: Use the v1 write API
list_title: Use the v1 write API
description: >
Use the InfluxDB v1 HTTP write API to write data stored in InfluxDB Cloud Serverless.
weight: 301
menu:
influxdb_cloud_serverless:
parent: Write data
name: Use the v1 HTTP write API
influxdb/cloud-serverless/tags: [query, influxql, python]
metadata: [InfluxQL]
related:
- /influxdb/cloud-serverless/guides/api-compatibility/v1/
- /influxdb/cloud-serverless/reference/client-libraries/v1/
list_code_example: |
```sh
curl "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&rp=RETENTION_POLICY&precision=s" \
--header "Authorization: Token API_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--data-binary 'home,room=kitchen temp=72 1463683075'
```
---
Use the InfluxDB v1 HTTP API `/write` endpoint and InfluxQL to write data stored in {{< product-name >}}.
The `/write` endpoint provides compatibility for InfluxDB 1.x workloads that you bring to InfluxDB v3.
_The v1 write and query APIs require [mapping databases and retention policies to buckets](#map-databases-and-retention-policies-to-buckets)._
- [Map databases and retention policies to buckets](#map-databases-and-retention-policies-to-buckets)
- [Autogenerate a bucket and DBRP mapping](#autogenerate-a-bucket-and-dbrp-mapping)
- [Create a bucket and DBRP mapping](#create-a-bucket-and-dbrp-mapping)
- [Write to the v1 HTTP `/write` endpoint](#write-to-the-v1-http-write-endpoint)
- [Parameters](#parameters)
- [Data](#data)
- [Authorization](#authorization)
- [Tools for writing to the v1 API](#tools-for-writing-to-the-v1-api)
## Map databases and retention policies to buckets
The v1 write and query APIs require mapping databases and retention policies to buckets.
InfluxDB can [autogenerate a bucket and DBRP mapping](#autogenerate-a-bucket-and-dbrp-mapping) for a write request or you can [create a bucket and DBRP](#create-a-bucket-and-dbrp-mapping) before writing.
### Autogenerate a bucket and DBRP mapping
To let InfluxDB autogenerate a bucket and an associated DBRP mapping, pass the following parameters when writing data to the v1 `/write` endpoint:
- a [`db=DATABASE_NAME` parameter](#v1-api-write-parameters).
- Optional: an [`rp=RETENTION_POLICY_NAME`](#v1-api-write-parameters) parameter. Default retention policy name is `autogen`.
- a token (such as an [All-access token](/influxdb/cloud-serverless/admin/tokens/#all-access-api-token)) that has permission to write DBRPs and buckets.
If no bucket exists with the name `DATABASE_NAME/RETENTION_POLICY_NAME`, InfluxDB creates a bucket and a DBRP before writing the data to the bucket.
To learn more about DBRP mapping, see the [v1 API compatibility guide](/influxdb/cloud-serverless/guides/api-compatibility/v1/#map-v1-databases-and-retention-policies-to-buckets).
### Create a bucket and DBRP mapping
To create a DBRP for a bucket:
1. If it doesn't already exist, [create the bucket](/influxdb/cloud-serverless/admin/buckets/create-bucket/) that you want to write to.
2. [Find the bucket ID](/influxdb/cloud-serverless/admin/buckets/view-buckets/) for the bucket that you want to write to.
3. [Create a DBRP](/influxdb/cloud-serverless/guides/api-compatibility/v1/#create-dbrp-mappings), which maps a database name and retention policy name to the bucket ID from the preceding step.
If the `db=DATABASE_NAME` and `rp=RETENTION_POLICY` parameters in your `/write` request map to an existing DBRP, InfluxDB writes to the mapped bucket.
## Write to the v1 HTTP `/write` endpoint
{{% api-endpoint endpoint="https://{{< influxdb/host >}}/write" method="post" %}}
- [`/api/v2/write` parameters](#v1-api-write-parameters)
- [Tools for writing to the v1 API](#tools-for-writing-to-the-v1-api)
### Parameters
For {{% product-name %}} v1 API `/write` requests, set parameters as listed in the following table:
Parameter | Allowed in | Ignored | Value
-----------------------|--------------|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`consistency` | Query string | Ignored | N/A
`db` {{% req " \*" %}} | Query string | Honored | Database (see how to [map databases and retention policies to buckets](#map-databases-and-retention-policies-to-buckets))
`precision` | Query string | Honored | [Timestamp precision](#timestamp-precision)
`rp` | Query string | Honored | Retention policy (see how to [map databases and retention policies to buckets](#map-databases-and-retention-policies-to-buckets))
[`Authorization` header or `u` and `p`](#authorization) | | | [Token](#authorization)
{{% caption %}}{{% req " \*" %}} = {{% req "Required" %}}{{% /caption %}}
#### Timestamp precision
Use one of the following `precision` values in v1 API `/write` requests:
- `ns`: nanoseconds
- `us`: microseconds
- `ms`: milliseconds
- `s`: seconds
- `m`: minutes
- `h`: hours
### Data
In the request body, include the [line protocol](/influxdb/cloud-serverless/write-data/line-protocol/) data that you want to write to the bucket.
### Authorization
To authorize writes to an existing bucket, include a [token](/influxdb/cloud-serverless/admin/tokens/) that has write permission to the bucket.
Use [`Token` authentication](/influxdb/cloud-serverless/guides/api-compatibility/v1/#authenticate-with-a-token-scheme) or v1-compatible [username and password authentication](/influxdb/cloud-serverless/guides/api-compatibility/v1/#authenticate-with-a-username-and-password-scheme) to include a token in the request.
For InfluxDB to autogenerate the bucket and DBRP, you must use a [token](/influxdb/cloud-serverless/admin/tokens/), such as an **All-access token**, that has write permissions to buckets and DBRPs.
### Tools for writing to the v1 API
When using the v1 API and associated tooling, pass the DBRP mapping's database name and retention policy name in the request parameters.
The following tools work with the {{% product-name %}} `/write` endpoint:
- [Telegraf](#telegraf)
- [Interactive clients](#interactive-clients)
- [Client libraries](#client-libraries)
#### Telegraf
If you have existing v1 workloads that use Telegraf,
you can use the [InfluxDB v1.x `influxdb` Telegraf output plugin](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) to write data.
{{% note %}}
See how to [use Telegraf and the v2 API](/influxdb/cloud-serverless/write-data/use-telegraf/) for new workloads that don't already use the v1 API.
{{% /note %}}
The following table shows `outputs.influxdb` plugin parameters and values for writing to the {{% product-name %}} v1 API:
Parameter | Ignored | Value
-------------------------|--------------------------|---------------------------------------------------------------------------------------------------
`database` | Honored | Bucket name
`retention_policy` | Honored | [Duration](/influxdb/cloud-serverless/reference/glossary/#duration)
`username` | Ignored | String or empty
`password` | Honored | [API token](/influxdb/cloud-serverless/admin/tokens/) with permission to write to the bucket
`content_encoding` | Honored | `gzip` (compressed data) or `identity` (uncompressed)
`skip_database_creation` | Ignored | N/A (see how to [create a bucket](/influxdb/cloud-serverless/admin/buckets/create-bucket/))
To configure the v1.x output plugin for writing to {{% product-name %}}, add the following `outputs.influxdb` configuration in your `telegraf.conf` file:
{{% code-placeholders "API_TOKEN|RETENTION_POLICY" %}}
```toml
[[outputs.influxdb]]
urls = ["https://{{< influxdb/host >}}"]
database = "DATABASE_NAME"
skip_database_creation = true
retention_policy = "RETENTION_POLICY"
username = "ignored"
password = "API_TOKEN"
content_encoding = "gzip”
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the [database](#map-databases-and-retention-policies-to-buckets)
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: the [retention policy](#map-databases-and-retention-policies-to-buckets)
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the mapped bucket
##### Other Telegraf configuration options
`influx_uint_support`: supported in InfluxDB v3.
For more plugin options, see [`influxdb`](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) on GitHub.
#### Interactive clients
To test InfluxDB v1 API writes interactively from the command line, use common HTTP clients such as cURL and Postman.
{{% note %}}
For production use cases, use tools such as [client libraries](#client-libraries) that construct line protocol for you and provide batch writing options.
{{% /note %}}
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[Token Auth](#)
[Basic Auth](#)
[Query String Auth](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
{{% code-placeholders "DATABASE_NAME|API_TOKEN|RETENTION_POLICY" %}}
```sh
curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&rp=RETENTION_POLICY&precision=s" \
--header "Authorization: Token API_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--data-binary 'home,room=kitchen temp=72 1463683075'
```
{{% /code-placeholders %}}
{{% /code-tab-content %}}
{{% code-tab-content %}}
{{% code-placeholders "DATABASE_NAME|API_TOKEN|RETENTION_POLICY" %}}
```sh
curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&rp=RETENTION_POLICY&precision=s" \
-user "ignored":"API_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--data-binary 'home,room=kitchen temp=72 1463683075'
```
{{% /code-placeholders %}}
{{% /code-tab-content %}}
{{% code-tab-content %}}
{{% code-placeholders "DATABASE_NAME|API_TOKEN|RETENTION_POLICY" %}}
```sh
curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&rp=RETENTION_POLICY&precision=s" \
--header "Content-type: text/plain; charset=utf-8" \
--data-urlencode "u=ignored" \
--data-urlencode "p=DATABASE_TOKEN" \
--data-binary 'home,room=kitchen temp=72 1463683075'
```
{{% /code-placeholders %}}
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the [database](#map-databases-and-retention-policies-to-buckets)
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: the [retention policy](#map-databases-and-retention-policies-to-buckets)
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the mapped bucket
#### v1 influx CLI (not supported)
Don't use the v1 `influx` CLI with {{% product-name %}}.
While it may coincidentally work, it isn't officially supported.
#### Client libraries
Use language-specific [v1 client libraries](/influxdb/v1/tools/api_client_libraries/) and your custom code to write data to InfluxDB.
v1 client libraries send data in [line protocol](/influxdb/cloud-serverless/reference/syntax/line-protocol/) syntax to the v1 API `/write` endpoint.
The following samples show how to configure **v1** client libraries for writing to {{% product-name %}}:
{{< tabs-wrapper >}}
{{% tabs %}}
[Node.js](#nodejs)
[Python](#python)
{{% /tabs %}}
{{% tab-content %}}
<!-- Start NodeJS -->
Create a v1 API client using the [node-influx](/influxdb/v1/tools/api_client_libraries/#javascriptnodejs) JavaScript client library:
{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}}
```js
const Influx = require('influx')
// Instantiate a client for writing to {{% product-name %}} v1 API
const client = new Influx.InfluxDB({
host: '{{< influxdb/host >}}',
port: 443,
protocol: 'https'
database: 'BUCKET_NAME',
username: 'ignored',
password: 'API_TOKEN'
})
// When calling write or query functions, specify the retention policy name in options.
```
{{% /code-placeholders %}}
<!-- End NodeJS -->
{{% /tab-content %}}
{{% tab-content %}}
<!-- Start Python -->
Create a v1 API client using the [influxdb-python](/influxdb/v1/tools/api_client_libraries/#python) Python client library:
{{% code-placeholders "DATABASE_NAME|API_TOKEN|RETENTION_POLICY" %}}
```py
from influxdb import InfluxDBClient
# Instantiate a client for writing to {{% product-name %}} v1 API
client = InfluxDBClient(
host='{{< influxdb/host >}}',
ssl=True,
database='DATABASE_NAME',
username='',
password='API_TOKEN'
headers={'Content-Type': 'text/plain; charset=utf-8'}
)
# When calling write or query functions, specify the retention policy name in options.
```
{{% /code-placeholders %}}
<!-- End Python -->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the [database](#map-databases-and-retention-policies-to-buckets)
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: the [retention policy](#map-databases-and-retention-policies-to-buckets)
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the specified bucket

4
content/influxdb/cloud-serverless/write-data/line protocol/_index.md
View File

@ -124,7 +124,7 @@ After setting up InfluxDB and your project, you should have the following:
- Client libraries installed for writing data to InfluxDB.
The following example shows how to construct `Point` objects that follow the [example `home` schema](#example-home-schema), and then write the points as line protocol to an
InfluxDB Cloud Serverless bucket.
{{% product-name %}} bucket.
### Construct points and write line protocol
@ -329,7 +329,7 @@ The sample code does the following:
### Run the example
To run the sample and write the data to your InfluxDB Cloud Serverless bucket, enter the following command in your terminal:
To run the sample and write the data to your {{% product-name %}} bucket, enter the following command in your terminal:
{{< code-tabs-wrapper >}}
{{% code-tabs %}}

3
content/influxdb/v2/reference/cli/influx/v1/dbrp/create.md
View File

@ -41,6 +41,7 @@ influx v1 dbrp create [flags]
{{< cli/influx-creds-note >}}
##### Create a DBRP mapping
```sh
influx v1 dbrp create \
--bucket-id 12ab34cd56ef \
@ -48,3 +49,5 @@ influx v1 dbrp create \
--rp example-rp \
--default
```
If a DBRP mapping already exists for the database name, the `--default` flag sets the new mapping as the default.

6
layouts/partials/article/related.html
View File

@ -38,11 +38,11 @@
{{ $link := replaceRE `\,\s(.*)$` "" $relatedItem }}
{{ $title := $scratch.Get "title" }}
<!-- If an external link or API link -->
{{ if or (in $relatedItem "http") (in $relatedItem "/v2.0/api") (in $relatedItem ",")}}
{{ $isExternal := gt (len (findRE `^http` $relatedItem)) 0 }}
{{ if or ($isExternal) (in $relatedItem "/v2/api") (in $relatedItem ",")}}
{{ $link := replaceRE `\,\s(.*)$` "" $relatedItem }}
{{ $title := replaceRE `^(\S*\,\s)` "" $relatedItem }}
{{ $target := cond (in . "http") "_blank" "" }}
{{ $target := cond ($isExternal) "_blank" "" }}
<li><a href="{{ $link }}" target="{{ $target }}">{{ $title }}</a></li>
<!-- Automatically get page title and link from path -->

10
test/README.md
View File

@ -11,13 +11,15 @@ This project contains the following:
## Set configuration values
To set your InfluxDB credentials for testing, create the file `.env.influxdbv3` and add key=value properties for the following:
To set your InfluxDB credentials for testing, create a `.env.<product-name>` file and add key=value properties--for example, in `.env.serverless`
```text
INFLUX_HOST=https://us-east-1-1.aws.cloud2.influxdata.com
INFLUX_TOKEN=3S3SFrpFbnNR_pZ3Cr6LMN...==
INFLUX_ORG=28d1f2f.........
INFLUX_DATABASE=get-started
INFLUX_HOSTNAME=us-east-1-1.aws.cloud2.influxdata.com
INFLUX_TOKEN=5Vz...
INFLUX_ORG=28d...
INFLUX_DATABASE=jason-test-create-bucket
INFLUX_RETENTION_POLICY=test-autogen
```
Storing configuration properties in a `.env` (dotenv) file is generally preferable to using environment variables.

16
test/run-tests.sh
View File

@ -45,18 +45,24 @@ for file in `find . -type f` ; do
s/f"BUCKET_NAME"/os.getenv("INFLUX_DATABASE")/g;
s/f"DATABASE_NAME"/os.getenv("INFLUX_DATABASE")/g;
s|f"{{< influxdb/host >}}"|os.getenv("INFLUX_HOSTNAME")|g;
s|f"RETENTION_POLICY"|"autogen"|g;
s|f"RETENTION_POLICY_NAME\|RETENTION_POLICY"|"autogen"|g;
' $file
# Shell-specific replacements.
## In JSON Heredoc
sed -i 's|"orgID": "ORG_ID"|"orgID": "$INFLUX_ORG"|g;
s|"name": "BUCKET_NAME"|"name": "$INFLUX_DATABASE"|g;' \
$file
sed -i 's/API_TOKEN/$INFLUX_TOKEN/g;
s/ORG_ID/$INFLUX_ORG/g;
s/ORG/$INFLUX_ORG/g;
s/DATABASE_TOKEN/$INFLUX_TOKEN/g;
s/--bucket-id BUCKET_ID/--bucket-id $INFLUX_BUCKET_ID/g;
s/BUCKET_NAME/$INFLUX_DATABASE/g;
s/DATABASE_NAME/$INFLUX_DATABASE/g;
s/--id DBRP_ID/--id $INFLUX_DBRP_ID/g;
s/get-started/$INFLUX_DATABASE/g;
s/RETENTION_POLICY/autogen/g;
s/RETENTION_POLICY_NAME\|RETENTION_POLICY/$INFLUX_RETENTION_POLICY/g;
s/CONFIG_NAME/CONFIG_$(shuf -i 0-100 -n1)/g;' \
$file
@ -89,8 +95,12 @@ gpg -q --batch --yes --delete-key D8FF8E1F7DF8B07E > /dev/null 2>&1
# Run test commands with options provided in the CMD of the Dockerfile.
# pytest rootdir is the directory where pytest.ini is located (/test).
if [ -d ./content/influxdb/cloud-dedicated/ ]; then
echo "Running cloud-dedicated tests..."
pytest --codeblocks --envfile $BASE_DIR/.env.dedicated ./content/influxdb/cloud-dedicated/ $@
fi
if [ -d ./content/influxdb/cloud-serverless/ ]; then
echo "Running cloud-serverless tests..."
pytest --codeblocks --envfile $BASE_DIR/.env.serverless ./content/influxdb/cloud-serverless/ $@
fi