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.7, 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:
- Verify buckets have a mapping.
- Create DBRP mappings for unmapped buckets.
- 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
To verify the buckets you want to query are mapped to a database and retention policy, use the
influxCLI or the InfluxDB API. 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
influxCLI 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, do the following:
Use the following command to start an InfluxQL shell:
influx v1 shellExecute an InfluxQL query inside the InfluxQL shell.
SELECT used_percent FROM "example-db"."example-rp"."example-measurement" WHERE host=host1For 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.7.
To query a mapped bucket with InfluxQL, use the
/query1.x compatibility endpoint, and 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
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
/querycompatibility endpoint returns results in JSON.- Request method:
(Optional) To return results as CSV, include the
Accept: application/csvheader.
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 ANALYZESELECT(read-only)SHOW DATABASESSHOW SERIESSHOW MEASUREMENTSSHOW TAG KEYSSHOW FIELD KEYSSHOW SERIES EXACT CARDINALITYSHOW TAG KEY CARDINALITYSHOW FIELD KEY CARDINALITY
* These commands delete data.
Unsupported InfluxQL queries
SELECT INTOALTERCREATEDROP(limited support)GRANTKILLREVOKESHOW SERIES CARDINALITY
Was this page helpful?
Thank you for your feedback!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support.