Query data with InfluxQL

In InfluxDB 1.x, data is stored in databases and retention policies. In InfluxDB Cloud and InfluxDB OSS 2.0, 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.

Complete the following steps:

  1. Verify buckets have a mapping.

    If data is written into a bucket using the /write 1.x compatibility API, the bucket automatically has a mapping. For more information, see Database and retention policy mapping. If you’re not sure how data was written into a bucket, we recommend verifying the bucket has a mapping.

  2. Map unmapped buckets.

  3. Query a mapped bucket with InfluxQL.

Verify buckets have a mapping

Verify the buckets that you want to query are mapped to a database and retention policy using the GET /dbrps API request (see CURL example below). Include the following in your request:

  • orgID(required). If this is the only parameter included in the request, a list of all database retention policy mappings for the specified organization is returned.
  • To find a specific bucket (bucketID), database (database), retention policy (rp), or mapping ID (id), include the query parameter in your request.
View all DBRP mappings
  1. curl --request GET \
  2.   http://localhost:8086/api/v2/dbrps?orgID=example-org-id \
  3.   --header "Authorization: Token YourAuthToken" \
  4.   --header "Content-type: application/json"
Filter DBRP mappings by database
  1. curl --request GET \
  2.   http://localhost:8086/api/v2/dbrps?orgID=example-org-id&db=example-db \
  3.   --header "Authorization: Token YourAuthToken" \
  4.   --header "Content-type: application/json"

If you do not find a mapping ID (id) 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

To map an unmapped bucket to a database and retention policy, use the POST /dbrps API request (see CURL example below).

You must include an authorization token with basic or token authentication in your request header and the following required parameters in your request body:

  • organization (organization or organization_id)
  • target bucket (bucket_id)

  • database and retention policy to map to bucket (database and retention_policy)

    1. curl --request POST http://localhost:8086/api/v2/dbrps \
    2. --header "Authorization: Token YourAuthToken" \
    3. --header 'Content-type: application/json' \
    4. --data '{
    5.    "bucketID": "12ab34cd56ef",
    6.    "database": "example-db",
    7.    "default": true,
    8.    "org": "example-org",
    9.    "orgID": "example-org-id",
    10.    "retention_policy": "example-rp",
    11.   }'

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 and InfluxDB OSS 2.0.

To query a mapped bucket with InfluxQL, use the /query 1.x compatibility endpoint (see CURL example below), and include the following in your request:

  • InfluxDB authentication token (See compatibility API authentication)
  • db query parameter: 1.x database to query
  • rp query parameter: 1.x retention policy to query; if no retention policy is specified, InfluxDB uses the default retention policy for the specified database.
  • q query parameter: InfluxQL query

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

  1. curl --request GET http://localhost:8086/query?db=example-db \
  2.   --header "Authorization: Token YourAuthToken" \
  3.   --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 and InfluxDB OSS 2.0 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 (see above)
  • GRANT
  • KILL
  • REVOKE

Related articles

influxql query