--- title: influxctl query description: The influxctl query command queries data from InfluxDB Clustered using SQL and prints results as a table or JSON. url: https://docs.influxdata.com/influxdb3/clustered/reference/cli/influxctl/query/ estimated_tokens: 3358 publisher: InfluxData canonical: https://docs.influxdata.com/influxdb3/clustered/reference/cli/influxctl/query/ date: '2026-05-15T15:46:14-06:00' lastmod: '2026-05-15T15:46:14-06:00' --- * influxctl 2.4.0+ 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](/influxdb3/clustered/reference/cli/influxctl/#configure-connection-profiles). 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](/influxdb3/clustered/reference/glossary/#rfc3339nano-timestamp)–for example:`2024-01-01T00:00:00.000000000Z` * `unixnano`: [Unix nanosecond timestamp](/influxdb3/clustered/reference/glossary/#unix-timestamp) ## Usage ```sh influxctl query [flags] ``` ## 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`) | | | `--perf-debug` |Output performance statistics and gRPC response trailers instead of query results| | | `--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](/influxdb3/clustered/reference/cli/influxctl/#global-flags).* ## Examples * [Query InfluxDB 3 with SQL](#query-influxdb-3-with-sql) * [Query InfluxDB 3 with InfluxQL](#query-influxdb-3-with-influxql) * [Query InfluxDB 3 and return results in table format](#query-influxdb-3-and-return-results-in-table-format) * [Query InfluxDB 3 and return results in JSON format](#query-influxdb-3-and-return-results-in-json-format) * [Query InfluxDB 3 and return results with Unix nanosecond timestamps](#query-influxdb-3-and-return-results-with-unix-nanosecond-timestamps) * [Query InfluxDB 3 using credentials from the connection profile](#query-influxdb-3-using-credentials-from-the-connection-profile) * [Output query performance statistics](#output-query-performance-statistics) * [Query data from InfluxDB 3 system tables](#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 #### string #### ```sh influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z'" ``` ```sh influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ /path/to/query.sql ``` ```sh cat ./query.sql | influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ - ``` ### Query InfluxDB 3 with InfluxQL #### string #### ```sh influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ --language influxql \ "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z'" ``` ```sh influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ --language influxql \ /path/to/query.influxql ``` ```sh cat ./query.influxql | influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ --language influxql \ - ``` ### Query InfluxDB 3 and return results in table format #### string #### ```sh influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' LIMIT 5" ``` ```sh influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ /path/to/query.sql ``` ```sh cat ./query.sql | influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ - ``` [](#view-example-table-formatted-results) View example table-formatted results ``` +-------+--------+---------+------+----------------------+ | 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 #### string #### ```sh influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ --format json \ "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' LIMIT 5" ``` ```sh influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ --format json \ /path/to/query.sql ``` ```sh cat ./query.sql | influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ --format json \ - ``` [](#view-example-json-formatted-results) View example JSON-formatted results ```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 #### string #### ```sh influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ --time-format unixnano \ "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' LIMIT 5" ``` ```sh influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ --time-format unixnano \ /path/to/query.sql ``` ```sh cat ./query.sql | influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ --time-format unixnano \ - ``` [](#view-example-table-formatted-results) View example table-formatted results ``` +-------+--------+---------+------+---------------------+ | 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](/influxdb3/clustered/reference/cli/influxctl/#configure-connection-profiles). ```sh influxctl query "SELECT \* FROM home WHERE time \>= '2022-01-01T08:00:00Z'" ``` ### 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. #### Table format #### ```sh 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)" ``` ```sh 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: [](#view-example-table-formatted-performance-statistics) View example table-formatted performance statistics ``` +--------------------------+----------+ | 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 | +--------------------------+----------+ ``` [](#view-example-json-formatted-performance-statistics) View example JSON-formatted performance statistics ```json { "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 > [!Note] > You must use **SQL** to query InfluxDB 3 system tables. > [!Warning] > 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. #### string #### ```sh influxctl query \ --enable-system-tables \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ "SELECT * FROM system.tables WHERE table_name = 'TABLE_NAME'" ``` ```sh influxctl query \ --enable-system-tables \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ /path/to/query.sql ``` ```sh cat ./query.sql | influxctl query \ --enable-system-tables \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ - ``` [](#view-command-updates) View command updates #### v2.12.0 * Add `--perf-debug` flag to output performance statistics and gRPC response trailers instead of query results. #### v2.9.0 * Add `--time-format` flag to specify which timestamp format to use in the`table` output format. #### v2.8.0 * Add InfluxQL support and introduce the `--language` flag to specify the query language. * Add `--enable-system-tables` flag to enable the ability to query InfluxDB 3 system tables. #### Related * [SQL reference documentation](/influxdb3/clustered/reference/sql/) * [Query data in InfluxDB Clustered](/influxdb3/clustered/query-data/) | Argument | Description | | --- | --- | | Argument | Description | | QUERY | Query to execute (command line string, path to file, or - to read from stdin) | | Flag | | Description | | --- | --- | --- | | 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 ) | | | --perf-debug | Output performance statistics and gRPC response trailers instead of query results | | | --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 |