influxctl query
The influxctl query command queries data from InfluxDB Clustered using SQL
or InfluxQL and prints results as a table or JSON.
Provide the query in one of the following ways:
- a string on the command line
- a path to a file that contains the query
- as a single dash (
-) to read the query from stdin
Important to note
- This command supports only one query per execution.
- This command is not meant to be a full, feature-rich query tool. It’s meant for debug, triage, and basic data exploration.
InfluxDB connection configuration
Your InfluxDB cluster host and port are
configured in your influxctl
connection profile.
Default uses TLS and port 443.
You can set a default database and token to use for the query and write
commands in your connection profile or pass them with the
command using the --database and --token flags.
Command line flags override settings in the connection profile.
Output format
The --format flag lets you print the output in other formats.
The json format is available for programmatic parsing by other tooling.
Default: table.
When using the table format, by default, timestamps are formatted as RFC3339
timestamps. Use the --time-format flag to specify one of the available time formats:
rfc3339nano: (Default) RFC3339Nano-formatted timestamp–for example:2024-01-01T00:00:00.000000000Zunixnano: Unix nanosecond timestamp
Usage
influxctl query [flags] <QUERY>
Arguments
| Argument | Description |
|---|---|
| QUERY | Query to execute (command line string, path to file, or - to read from stdin) |
Flags
| Flag | Description | |
|---|---|---|
--database | Database to query | |
--enable-system-tables | Enable ability to query system tables | |
--format | Output format (table (default) or json) | |
--language | Query language (sql (default) or influxql) | |
--time-format | Time format for table output (rfc3339nano (default) or unixnano) | |
--token | Database token with read permissions on the queried database | |
-h | --help | Output command help |
Also see influxctl global flags.
Examples
- Query InfluxDB v3 with SQL
- Query InfluxDB v3 with InfluxQL
- Query InfluxDB v3 and return results in table format
- Query InfluxDB v3 and return results in JSON format
- Query InfluxDB v3 and return results with Unix nanosecond timestamps
- Query InfluxDB v3 using credentials from the connection profile
- Query data from InfluxDB v3 system tables
In the examples below, replace the following:
DATABASE_TOKEN: Database token with read access to the queried databaseDATABASE_NAME: Name of the database to query
Query InfluxDB v3 with SQL
influxctl query \
--token DATABASE_TOKEN \
--database DATABASE_NAME \
/path/to/query.sql
cat ./query.sql | influxctl query \
--token DATABASE_TOKEN \
--database DATABASE_NAME \
-
Query InfluxDB v3 with InfluxQL
influxctl query \
--token DATABASE_TOKEN \
--database DATABASE_NAME \
--language influxql \
/path/to/query.influxql
cat ./query.influxql | influxctl query \
--token DATABASE_TOKEN \
--database DATABASE_NAME \
--language influxql \
-
Query InfluxDB v3 and return results in table format
influxctl query \
--token DATABASE_TOKEN \
--database DATABASE_NAME \
/path/to/query.sql
cat ./query.sql | influxctl query \
--token DATABASE_TOKEN \
--database DATABASE_NAME \
-
Query InfluxDB v3 and return results in JSON format
influxctl query \
--token DATABASE_TOKEN \
--database DATABASE_NAME \
--format json \
/path/to/query.sql
cat ./query.sql | influxctl query \
--token DATABASE_TOKEN \
--database DATABASE_NAME \
--format json \
-
Query InfluxDB v3 and return results with Unix nanosecond timestamps
influxctl query \
--token DATABASE_TOKEN \
--database DATABASE_NAME \
--time-format unixnano \
/path/to/query.sql
cat ./query.sql | influxctl query \
--token DATABASE_TOKEN \
--database DATABASE_NAME \
--time-format unixnano \
-
Query InfluxDB v3 using credentials from the connection profile
The following example uses the database and token defined in the default
connection profile.
Query data from InfluxDB v3 system tables
You must use SQL to query InfluxDB v3 system tables.
Querying system tables can impact the overall performance of your InfluxDB cluster. System tables are not part of InfluxDB’s stable API and are subject to change.
influxctl query \
--enable-system-tables \
--token DATABASE_TOKEN \
--database DATABASE_NAME \
/path/to/query.sql
cat ./query.sql | influxctl query \
--enable-system-tables \
--token DATABASE_TOKEN \
--database DATABASE_NAME \
-
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.