Query data with InfluxQL

In InfluxDB 1.x, data is stored in databases and retention policies. In InfluxDB Cloud, data is stored in buckets. Because InfluxQL uses the 1.x data model, a bucket must be mapped to a database and retention policy (DBRP) before it can be queried using InfluxQL.

To use InfluxQL to query bucket data, complete the following steps:

1. Verify buckets have a mapping.
2. Map unmapped buckets.
3. Query a mapped bucket with InfluxQL.

Verify buckets have a mapping

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

• Request method: GET
• Headers:
  • Authorization: Token schema with your InfluxDB API token
• Query parameters:
  * Required
  • * organization_id: organization ID
  • bucket_id: bucket ID (to list DBRP mappings for a specific bucket)
  • database: database name (to list DBRP mappings with a specific database name)
  • retention_policy: 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?organization_id=00oxo0oXx000x0Xo \
  --header "Authorization: Token YourAuthToken"

Filter DBRP mappings by database

curl --request GET \
  https://cloud2.influxdata.com/api/v2/dbrps?organization_id=00oxo0oXx000x0Xo&database=example-db \
  --header "Authorization: Token YourAuthToken"

Filter DBRP mappings by bucket ID

curl --request GET \
  https://cloud2.influxdata.com/api/v2/dbrps?organization_id=00oxo0oXx000x0Xo&bucket_id=00oxo0oXx000x0Xo \
  --header "Authorization: Token YourAuthToken"

If you do not find a DBRP mapping for a bucket, complete the next procedure to map the unmapped bucket. For more information on the DBRP mapping API, see the /api/v2/dbrps endpoint documentation.

Map unmapped buckets

Use the /api/v2/dbrps API endpoint to create a new DBRP mapping for a bucket. 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
  • * bucket_id: bucket ID
  • * database: database name
  • default: set the provided retention policy as the default retention policy for the database
  • * organization or organization_id: organization name or organization ID
  • * retention_policy: retention policy name

curl --request POST https://cloud2.influxdata.com/api/v2/dbrps \
  --header "Authorization: Token YourAuthToken" \
  --header 'Content-type: application/json' \
  --data '{
        "bucket_id": "00oxo0oXx000x0Xo",
        "database": "example-db",
        "default": true,
        "organization_id": "00oxo0oXx000x0Xo",
        "retention_policy": "example-rp"
      }'

After you’ve verified the bucket is mapped, query the bucket using the query 1.x compatibility endpoint.

Query a mapped bucket with InfluxQL

The InfluxDB 1.x compatibility API supports all InfluxDB 1.x client libraries and integrations in InfluxDB Cloud.

To query a mapped bucket with InfluxQL, use the /query 1.x compatibility endpoint. Include the following in your request:

• Request method: GET
• Headers:
  • Authorization: See compatibility API authentication
• Query parameters:
  • db: 1.x database to query
  • rp: 1.x retention policy to query (if no retention policy is specified, InfluxDB uses the default retention policy for the specified database)
  • q: URL-encoded InfluxQL query

curl --get https://cloud2.influxdata.com/query?db=example-db \
  --header "Authorization: Token YourAuthToken" \
  --data-urlencode "q=SELECT used_percent FROM example-db.example-rp.example-measurement WHERE host=host1"

By default, the /query compatibility endpoint returns results in JSON. To return results as CSV, include the Accept: application/csv header.

InfluxQL support

InfluxDB Cloud supports InfluxQL read-only queries. See supported and unsupported queries below. To learn more about InfluxQL, see Influx Query Language (InfluxQL).