Documentation

Query data with InfluxQL

Use InfluxQL (an SQL-like query language) to interact with InfluxDB, and query and analyze your times series data.

In InfluxDB 1.x, data is stored in databases and retention policies. In InfluxDB OSS 2.6, 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 query data with InfluxQL, complete the following steps:

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

InfluxQL reference documentation

For complete InfluxQL reference documentation, see the InfluxQL specification for InfluxDB 2.x.

Verify buckets have a mapping

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

  2. 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

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).

  1. If you haven’t already, do the following:

  2. Use the following command to start an InfluxQL shell:

    influx v1 shell
    
  3. Execute an InfluxQL query inside the InfluxQL shell.

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

    For more information, see how to use the InfluxQL shell. For more information about DBRP mappings, see Manage DBRP mappings.

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

  1. To query a mapped bucket with InfluxQL, use the /query 1.x compatibility endpoint, and 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.

  2. (Optional) To return results as CSV, include the Accept: application/csv header.

For more information about DBRP mappings, see Manage DBRP mappings.

InfluxQL support

InfluxDB OSS 2.x supports the following InfluxQL statements and clauses. See supported and unsupported queries below.

Supported InfluxQL queries
  • DELETE*
  • DROP MEASUREMENT*
  • EXPLAIN ANALYZE
  • SELECT (read-only)
  • SHOW DATABASES
  • SHOW SERIES
  • SHOW MEASUREMENTS
  • SHOW TAG KEYS
  • SHOW FIELD KEYS
  • SHOW SERIES EXACT CARDINALITY
  • SHOW TAG KEY CARDINALITY
  • SHOW FIELD KEY CARDINALITY

* These commands delete data.

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

Was this page helpful?

Thank you for your feedback!


Set your InfluxDB URL

Linux Package Signing Key Rotation

All signed InfluxData Linux packages have been resigned with an updated key. If using Linux, you may need to update your package configuration to continue to download and verify InfluxData software packages.

For more information, see the Linux Package Signing Key Rotation blog post.

InfluxDB Cloud backed by InfluxDB IOx

All InfluxDB Cloud organizations created on or after January 31, 2023 are backed by the new InfluxDB IOx storage engine. Check the right column of your InfluxDB Cloud organization homepage to see which InfluxDB storage engine you’re using.

If powered by IOx, this is the correct documentation.

If powered by TSM, see the TSM-based InfluxDB Cloud documentation.

InfluxDB Cloud backed by InfluxDB TSM

All InfluxDB Cloud organizations created on or after January 31, 2023 are backed by the new InfluxDB IOx storage engine which enables nearly unlimited series cardinality and SQL query support. Check the right column of your InfluxDB Cloud organization homepage to see which InfluxDB storage engine you’re using.

If powered by TSM, this is the correct documentation.

If powered by IOx, see the IOx-based InfluxDB Cloud documentation.

State of the InfluxDB Cloud (IOx) documentation

The new documentation for InfluxDB Cloud backed by InfluxDB IOx 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.