Documentation

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, before querying in InfluxQL, a bucket must be mapped to a database and retention policy (DBRP).

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

When writing to an InfluxDB Cloud bucket using the /write 1.x compatibility API, InfluxDB Cloud automatically creates a DBRP mapping for the bucket that matches the db/rp naming convention. For more information, see Database and retention policy mapping. If you’re not sure how data was written into a bucket, verify the bucket has a mapping.

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

  • Request method: GET
  • Headers:
  • 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:
  • Request body: JSON object with the following fields:
    • (Required) bucket_id: bucket ID
    • (Required) database: database name
    • default: set the provided retention policy as the default retention policy for the database
    • (Required) organization or organization_id: organization name or organization ID
    • (Required) 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:
  • 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: InfluxQL query

URL-encode the InfluxQL query to ensure it’s formatted correctly when submitted to InfluxDB.

curl --request 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 support InfluxQL read-only queries. See supported and unsupported queries below. To learn more about InfluxQL, see Influx Query Language (InfluxQL).

Supported InfluxQL queries
  • DELETE*
  • DROP MEASUREMENT*
  • SELECT (read-only)
  • SHOW DATABASES
  • SHOW MEASUREMENTS
  • SHOW TAG KEYS
  • SHOW TAG VALUES
  • SHOW FIELD KEYS

* These commands delete data.

Unsupported InfluxQL queries
  • SELECT INTO
  • ALTER
  • CREATE
  • DROP (limited support)
  • GRANT
  • KILL
  • REVOKE

New! Cloud or OSS?

InfluxDB OSS 2.0 now generally available!

InfluxDB OSS 2.0 is now generally available and ready for production use. See the InfluxDB OSS 2.0 release notes.

For information about upgrading to InfluxDB OSS 2.0, see: