Documentation

influxctl query

Limited availability

InfluxDB Clustered is currently only available to a limited group of InfluxData customers. If interested in being part of the limited access group, please contact the InfluxData Sales team.

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:

Usage

influxctl query [flags] <QUERY>

Arguments

ArgumentDescription
QUERYQuery to execute (command line string, path to file, or - to read from stdin)

Flags

FlagDescription
--databaseDatabase to query
--enable-system-tablesEnable ability to query system tables
--formatOutput format (table (default) or json)
--languageQuery language (sql (default) or influxql)
--time-formatTime format for table output (rfc3339nano (default) or unixnano)
--tokenDatabase token with read permissions on the queried database
-h--helpOutput command help

Examples

In the examples below, replace the following:

  • DATABASE_TOKEN: Database token with read access to the queried database
  • DATABASE_NAME: Name of the database to query

Query InfluxDB v3 with SQL

influxctl query \
  --token 
DATABASE_TOKEN
\
--database
DATABASE_NAME
\
"SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z'"
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 \ "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z'"
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
\
"SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' LIMIT 5"
influxctl query \
  --token 
DATABASE_TOKEN
\
--database
DATABASE_NAME
\
/path/to/query.sql
cat ./query.sql | influxctl query \
  --token 
DATABASE_TOKEN
\
--database
DATABASE_NAME
\
-

View example table-formatted results

Query InfluxDB v3 and return results in JSON format

influxctl query \
  --token 
DATABASE_TOKEN
\
--database
DATABASE_NAME
\
--format json \ "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' LIMIT 5"
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 \ -

View example JSON-formatted results

Query InfluxDB v3 and return results with Unix nanosecond timestamps

influxctl query \
  --token 
DATABASE_TOKEN
\
--database
DATABASE_NAME
\
--time-format unixnano \ "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' LIMIT 5"
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 \ -

View example table-formatted results

Query InfluxDB v3 using credentials from the connection profile

The following example uses the database and token defined in the default connection profile.

influxctl query "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z'"

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
\
"SELECT * FROM system.tables"
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
\
-

View command updates


Was this page helpful?

Thank you for your feedback!


The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Read more