Use the influxctl CLI to query data

Use the influxctl query command to query data in InfluxDB Cloud Dedicated with SQL or InfluxQL.

Provide the following with your command:

  • Database token: A database token with read permissions on the queried database. By default, this uses the database setting from the influxctl connection profile or the --token command flag.

  • Database name: The name of the database to query. By default, this uses the database setting from the influxctl connection profile or the --database command flag.

  • Query language (Optional): The query language of the query. Use the --language flag to specify one of the following query languages:

    • sql (default)
    • influxql

  • Query: SQL or InfluxQL query to execute. Pass the query in one of the following ways:

    • a string on the command line
    • a path to a file that contains the query
    • a single dash (-) to read the query from stdin

SQL InfluxQL

string file stdin

influxctl query \
  --token 
DATABASE_TOKEN
 \
  --database 
DATABASE_NAME
 \
  "SELECT * FROM home"
influxctl query \
  --token 
DATABASE_TOKEN
 \
  --database 
DATABASE_NAME
 \
  /path/to/query.sql
cat ./query.sql | influxctl query \
  --token 
DATABASE_TOKEN
 \
  --database 
DATABASE_NAME
 \
  -

string file stdin

influxctl query \
  --token 
DATABASE_TOKEN
 \
  --database 
DATABASE_NAME
 \
  --language influxql \
  "SELECT * FROM home"
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 \
  -

Replace the following:

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

Query timeouts

The influxctl --timeout global flag sets the maximum duration for API calls, including query requests. If a query takes longer than the specified timeout, the operation will be canceled.

Timeout examples

Use different timeout values based on your query type:

# Shorter timeout for testing dashboard queries (10 seconds)
influxctl query \
  --timeout 10s \
  --token 
DATABASE_TOKEN
 \
  --database 
DATABASE_NAME
 \
  "SELECT AVG(temperature) FROM sensors WHERE time >= now() - INTERVAL '1 day'"

# Longer timeout for analytical queries (5 minutes)
influxctl query \
  --timeout 5m \
  --token 
DATABASE_TOKEN
 \
  --database 
DATABASE_NAME
 \
  "SELECT room, AVG(temperature) FROM sensors WHERE time >= now() - INTERVAL '30 days' GROUP BY room"

For guidance on selecting appropriate timeout values, see Query timeout best practices.

Output format

The influxctl query command supports the following output formats:

  • table (default)
  • json

Use the --format flag to specify the output format:

```sh influxctl query \ --format json \ "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' LIMIT 5" ```

View example table-formatted results

View example JSON-formatted results

Timestamp format

When using the table output format, you can specify which of the following timestamp formats to use to display timestamp values in the query results:

```sh influxctl query \ --time-format unixnano \ "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' LIMIT 5" ```

View example results with Unix nanosecond timestamps

Was this page helpful?

Thank you for your feedback!