influxctl query

The influxctl query command queries data from InfluxDB Cloud Dedicated 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

InfluxDB connection configuration

Your InfluxDB Cloud Dedicated 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.000000000Z
• unixnano: Unix nanosecond timestamp

Usage

influxctl query [flags] <QUERY>

Arguments

Flags

Examples

• Query InfluxDB 3 with SQL
• Query InfluxDB 3 with InfluxQL
• Query InfluxDB 3 and return results in table format
• Query InfluxDB 3 and return results in JSON format
• Query InfluxDB 3 and return results with Unix nanosecond timestamps
• Query InfluxDB 3 using credentials from the connection profile
• Output query performance statistics
• Query data from InfluxDB 3 system tables

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 3 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 3 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 3 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
 \
  - 

+-------+--------+---------+------+----------------------+
|    co |    hum | room    | temp | time                 |
+-------+--------+---------+------+----------------------+
|     0 |   35.9 | Kitchen |   21 | 2022-01-01T08:00:00Z |
|     0 |   36.2 | Kitchen |   23 | 2022-01-01T09:00:00Z |
|     0 |   36.1 | Kitchen | 22.7 | 2022-01-01T10:00:00Z |
|     0 |     36 | Kitchen | 22.4 | 2022-01-01T11:00:00Z |
|     0 |     36 | Kitchen | 22.5 | 2022-01-01T12:00:00Z |
+-------+--------+---------+------+----------------------+
| TOTAL | 5 ROWS |         |      |                      |
+-------+--------+---------+------+----------------------+

Query InfluxDB 3 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 \
  - 

[
  {
    "co": 0,
    "hum": 35.9,
    "room": "Kitchen",
    "temp": 21,
    "time": 1641024000000000000
  },
  {
    "co": 0,
    "hum": 36.2,
    "room": "Kitchen",
    "temp": 23,
    "time": 1641027600000000000
  },
  {
    "co": 0,
    "hum": 36.1,
    "room": "Kitchen",
    "temp": 22.7,
    "time": 1641031200000000000
  },
  {
    "co": 0,
    "hum": 36,
    "room": "Kitchen",
    "temp": 22.4,
    "time": 1641034800000000000
  },
  {
    "co": 0,
    "hum": 36,
    "room": "Kitchen",
    "temp": 22.5,
    "time": 1641038400000000000
  }
]

Query InfluxDB 3 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 \
  - 

+-------+--------+---------+------+---------------------+
|    co |    hum | room    | temp |                time |
+-------+--------+---------+------+---------------------+
|     0 |   35.9 | Kitchen |   21 | 1641024000000000000 |
|     0 |   36.2 | Kitchen |   23 | 1641027600000000000 |
|     0 |   36.1 | Kitchen | 22.7 | 1641031200000000000 |
|     0 |     36 | Kitchen | 22.4 | 1641034800000000000 |
|     0 |     36 | Kitchen | 22.5 | 1641038400000000000 |
+-------+--------+---------+------+---------------------+
| TOTAL | 5 ROWS |         |      |                     |
+-------+--------+---------+------+---------------------+

Query InfluxDB 3 using credentials from the connection profile

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

Output query performance statistics

Use the --perf-debug flag to output performance statistics and gRPC response trailers instead of query results. This is useful for debugging query performance and understanding query execution.

influxctl query \
  --perf-debug \
  --format table \
  --token 
DATABASE_TOKEN
 \
  --database 
DATABASE_NAME
 \
  --language influxql \
  "SELECT SUM(temp) FROM home WHERE time > now() - 1h GROUP BY time(5m)"

influxctl query \
  --perf-debug \
  --format json \
  --token 
DATABASE_TOKEN
 \
  --database 
DATABASE_NAME
 \
  --language influxql \
  "SELECT SUM(temp) FROM home WHERE time > now() - 1h GROUP BY time(5m)"

The output is similar to the following:

+--------------------------+----------+
| Metric                   | Value    |
+--------------------------+----------+
| Client Duration          | 1.619 s  |
| Output Rows              | 0        |
| Output Size              | 0 B      |
+--------------------------+----------+
| Compute Duration         | 42.0 µs  |
| Execution Duration       | 181.0 µs |
| Ingester Latency Data    | 0        |
| Ingester Latency Plan    | 0        |
| Ingester Partition Count | 0        |
| Ingester Response        | 0 B      |
| Ingester Response Rows   | 0        |
| Max Memory               | 64 B     |
| Parquet Files            | 0        |
| Partitions               | 0        |
| Planning Duration        | 7.0 ms   |
| Queue Duration           | 378.0 µs |
+--------------------------+----------+

{
  "client_duration_secs": 1.748,
  "compute_duration_secs": 0,
  "execution_duration_secs": 0,
  "ingester_latency_data": 0,
  "ingester_latency_plan": 0,
  "ingester_partition_count": 0,
  "ingester_response_bytes": 0,
  "ingester_response_rows": 0,
  "max_memory_bytes": 64,
  "output_bytes": 0,
  "output_rows": 0,
  "parquet_files": 0,
  "partitions": 0,
  "planning_duration_secs": 0.006,
  "queue_duration_secs": 0
}

Query data from InfluxDB 3 system tables

influxctl query \
  --enable-system-tables \
  --token 
DATABASE_TOKEN
 \
  --database 
DATABASE_NAME
 \
  "SELECT * FROM system.tables WHERE table_name = '
TABLE_NAME
'"

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
 \
  -