Documentation

InfluxDB Cloud Serverless

Map databases and retention policies to buckets

InfluxQL requires a database and retention policy (DBRP) combination in order to query data. In InfluxDB Cloud Serverless, databases and retention policies are combined and replaced by InfluxDB buckets. To query an InfluxDB Cloud Serverless bucket with InfluxQL, first map each DBRP combination to a bucket.

Automatic DBRP mapping

InfluxDB Cloud Serverless automatically creates DBRP mappings for you during the following operations:

For more information, see Database and retention policy mapping.

Create DBRP mappings

Use the influx CLI or the InfluxDB API to create DBRP mappings.

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.

influx CLI InfluxDB API

Use the influx v1 dbrp create command to map a database and retention policy to a bucket. Include the following:

* Required

  • * 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.
  • * database name to map
  • * retention policy name to map
  • * Bucket ID to map to
  • Default flag to set the provided retention policy as the default retention policy for the database
influx v1 dbrp create \
  --token 
API_TOKEN
 \
  --db 
DATABASE_NAME
 \
  --rp 
RETENTION_POLICY_NAME
 \
  --bucket-id 
BUCKET_ID
 \
  --default

Use the /api/v2/dbrps API endpoint to create a new DBRP mapping.

POST https://cloud2.influxdata.com/api/v2/dbrps

Include the following:

  • Request method: POST
  • Headers:
    • Authorization: Token schema with your InfluxDB API token
    • Content-type: application/json
  • Request body: JSON object with the following fields:
    * Required
    • * bucketID: bucket ID
    • * database: database name
    • default: set the provided retention policy as the default retention policy for the database
    • * org or orgID: organization name or organization ID
    • * retention_policy: retention policy name
curl --request POST https://cloud2.influxdata.com/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
"
      }'

List DBRP mappings

Use the influx CLI or the InfluxDB HTTP API to list all DBRP mappings and verify the buckets you want to query are mapped to a database and retention policy.

influx CLI InfluxDB HTTP API

Use the influx v1 dbrp list command to list DBRP mappings.

View all DBRP mappings
influx v1 dbrp list --token 
API_TOKEN
Filter DBRP mappings by database
influx v1 dbrp list \
  --token 
API_TOKEN
 \
  --db 
DATABASE_NAME
Filter DBRP mappings by bucket ID
influx v1 dbrp list \
  --token 
API_TOKEN
 \
  --bucket-id 
BUCKET_ID

Use the /api/v2/dbrps API endpoint to list DBRP mappings.

GET https://cloud2.influxdata.com/api/v2/dbrps

Include the following:

  • Request method: GET
  • Headers:
    • Authorization: Token schema with your InfluxDB API token
  • Query parameters:
    * Required
    • * orgID: organization ID
    • bucketID: bucket ID (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)
View all DBRP mappings
curl --request GET \
  https://cloud2.influxdata.com/api/v2/dbrps \
  --header "Authorization: Token 
API_TOKEN
" \
  --data-urlencode "orgID=
ORG_ID
"
Filter DBRP mappings by database
curl --request GET \
  https://cloud2.influxdata.com/api/v2/dbrps \
  --header "Authorization: Token 
API_TOKEN
" \
  --data-urlencode "orgID=
ORG_ID
" \
  --data-urlencode  "db=
DATABASE_NAME
"
Filter DBRP mappings by bucket ID
curl --request GET \
  https://cloud2.influxdata.com/api/v2/dbrps \
  --header "Authorization: Token 
API_TOKEN
" \
  --data-urlencode "orgID=
ORG_ID
" \
  --data-urlencode  "bucketID=
BUCKET_ID
"

Update a DBRP mapping

Use the influx CLI or the InfluxDB HTTP API to update a DBRP mapping.

influx CLI InfluxDB HTTP API

Use the influx v1 dbrp update command to update a DBRP mapping. Include the following:

* Required

  • * 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.
  • * 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
influx v1 dbrp update \
  --token 
API_TOKEN
 \
  --id 
DBRP_ID
 \
  --rp 
RETENTION_POLICY_NAME
 \
  --default

Use the /api/v2/dbrps/{dbrpID} API endpoint to update DBRP mappings.

PATCH https://cloud2.influxdata.com/api/v2/dbrps/{dbrpID}

Include the following:

* Required

  • Request method: PATCH
  • Headers:
    • * Authorization: Token schema with your InfluxDB API token
  • Path parameters:
    • * id: DBRP mapping ID to update
  • Query parameters:
  • 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
curl --request PATCH \
  https://cloud2.influxdata.com/api/v2/dbrps/
DBRP_ID
 \
  --header "Authorization: Token 
API_TOKEN
" \
  --data-urlencode "orgID=
ORG_ID
" \
  --data '{
      "rp": "
RETENTION_POLICY_NAME
",
      "default": true
    }'

Delete a DBRP mapping

Use the influx CLI or the InfluxDB API to delete a DBRP mapping.

influx CLI InfluxDB API

Use the influx v1 dbrp delete command to delete a DBRP mapping. Include the following:

* Required

  • * 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.
  • * DBRP mapping ID to delete
influx v1 dbrp delete \
  --token 
API_TOKEN
 \
  --id 
DBRP_ID

Use the /api/v2/dbrps/{dbrpID} API endpoint to delete a DBRP mapping.

DELETE https://cloud2.influxdata.com/api/v2/dbrps/{dbrpID}

Include the following:

* Required

  • Request method: PATCH
  • Headers:
    • * Authorization: Token schema with your InfluxDB API token
  • Path parameters:
    • * id: DBRP mapping ID to update
  • Query parameters:
curl --request DELETE \
  https://cloud2.influxdata.com/api/v2/dbrps/
DBRP_ID
 \
  --header "Authorization: Token 
API_TOKEN
" \
  --data-urlencode "orgID=
ORG_ID
"

Was this page helpful?

Thank you for your feedback!

© 2023 InfluxData, Inc.

Select your InfluxDB Cloud region

Select your InfluxDB Cloud region and cluster and we’ll customize code examples for you. Identify your InfluxDB Cloud cluster.

AWS

For more information, see InfluxDB Cloud Serverless regions.

Thank you for your feedback!

Let us know what we can do better:

Thank you!

No thanks

Introducing InfluxDB Clustered

A highly available InfluxDB 3.0 cluster on your own infrastructure.

InfluxDB Clustered is a highly available InfluxDB 3.0 cluster built for high write and query workloads on your own infrastructure.

InfluxDB Clustered is currently in limited availability and is only available to a limited group of InfluxData customers. If interested in being part of the limited access group, please contact the InfluxData Sales team.

Learn more
Contact InfluxData Sales

The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Flux is going into maintenance mode and will not be supported in InfluxDB 3.0. This was a decision based on the broad demand for SQL and the continued growth and adoption of InfluxQL. We are continuing to support Flux for users in 1.x and 2.x so you can continue using it with no changes to your code. If you are interested in transitioning to InfluxDB 3.0 and want to future-proof your code, we suggest using InfluxQL.

For information about the future of Flux, see the following:

State of the InfluxDB Cloud Serverless documentation

InfluxDB Cloud Serverless documentation is a work in progress.

The new documentation for InfluxDB Cloud Serverless is a work in progress. We are adding new information and content almost daily. Thank you for your patience!

If there is specific information you’re looking for, please submit a documentation issue.

InfluxDB Cloud Serverless

You are currently viewing documentation specific to InfluxDB Cloud Serverless powered by the IOx storage engine, which offers different functionality than InfluxDB Cloud powered by the TSM storage engine.

Are you using InfluxDB Cloud Serverless? How to find out?

Visit your organization's homepage and look for:

InfluxDB Cloud Serverless
Yes – I'm using InfluxDB Cloud Serverless No – I'm using InfluxDB Cloud (TSM)