--- title: influxctl query description: The influxctl query command queries data from InfluxDB Cloud Dedicated using SQL or InfluxQL and prints results as a table or JSON. url: https://docs.influxdata.com/influxdb3/cloud-dedicated/reference/cli/influxctl/query/ estimated_tokens: 12099 product: InfluxDB Cloud Dedicated version: cloud-dedicated --- # influxctl query - influxctl 2.4.0+ 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 #### 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 Cloud Dedicated cluster host and port are configured in your `influxctl` [connection profile](/influxdb3/cloud-dedicated/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/cloud-dedicated/reference/glossary/#rfc3339nano-timestamp)–for example: `2024-01-01T00:00:00.000000000Z` - `unixnano`: [Unix nanosecond timestamp](/influxdb3/cloud-dedicated/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/cloud-dedicated/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'" ``` **file:** ```sh influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ /path/to/query.sql ``` **stdin:** ```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'" ``` **file:** ```sh influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ --language influxql \ /path/to/query.influxql ``` **stdin:** ```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" ``` **file:** ```sh influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ /path/to/query.sql ``` **stdin:** ```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" ``` **file:** ```sh influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ --format json \ /path/to/query.sql ``` **stdin:** ```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" ``` **file:** ```sh influxctl query \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ --time-format unixnano \ /path/to/query.sql ``` **stdin:** ```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/cloud-dedicated/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)" ``` **JSON format:** ```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 You must use **SQL** to query InfluxDB 3 system tables. Querying system tables can impact the overall performance of your InfluxDB Cloud Dedicated 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'" ``` **file:** ```sh influxctl query \ --enable-system-tables \ --token DATABASE_TOKEN \ --database DATABASE_NAME \ /path/to/query.sql ``` **stdin:** ```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/cloud-dedicated/reference/sql/) - [InfluxQL reference documentation](/influxdb3/cloud-dedicated/reference/influxql/) - [Query data in InfluxDB Cloud Dedicated](/influxdb3/cloud-dedicated/query-data/) - [Query system data](/influxdb3/cloud-dedicated/admin/query-system-data/)