Documentation

Query data with InfluxQL

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

InfluxQL reference documentation

For complete InfluxQL reference documentation, see Influx Query Language in the latest InfluxDB 1.x documentation.

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

  1. Verify buckets have a mapping.
  2. Create DBRP mappings for unmapped buckets.
  3. Query a mapped bucket with InfluxQL.

Verify buckets have a mapping

Use the influx CLI or the InfluxDB API to verify the buckets you want to query are mapped to a database and retention policy. For examples, see List DBRP mappings.

If you do not find a DBRP mapping for a bucket, create a new DBRP mapping to map the unmapped bucket.

Create DBRP mappings for unmapped buckets

Use the influx CLI or the InfluxDB API to manually create DBRP mappings for unmapped buckets. For examples, see Create DBRP mappings.

Query a mapped bucket with InfluxQL

The influx CLI provides an InfluxQL shell where you can execute InfluxQL queries in an interactive Read-Eval-Print-Loop (REPL).

If you haven’t already, be sure to do the following:

Use the following command to start an InfluxQL shell:

influx v1 shell

Execute an InfluxQL query inside the InfluxQL shell.

> SELECT used_percent FROM example-db.example-rp.example-measurement WHERE host=host1

For more information about using the InfluxQL shell, see Use the InfluxQL shell.

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

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: URL-encoded InfluxQL query

URL-encode query parameters that may contain whitespace or other special characters.

curl --get http://localhost:8086/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 2.4 supports InfluxQL queries. See supported and unsupported queries below. To learn more about InfluxQL, see Influx Query Language (InfluxQL).

Supported InfluxQL queries
  • DELETE*
  • DROP MEASUREMENT*
  • EXPLAIN ANALYZE
  • 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

Was this page helpful?

Thank you for your feedback!


Set your InfluxDB URL

Upgrade to InfluxDB Cloud or InfluxDB 2.0!

InfluxDB Cloud and InfluxDB OSS 2.0 ready for production.