477 lines
13 KiB
Markdown
477 lines
13 KiB
Markdown
---
|
|
title: influxctl query
|
|
description: >
|
|
The `influxctl query` command queries data from InfluxDB Clustered
|
|
using SQL and prints results as a table or JSON.
|
|
menu:
|
|
influxdb3_clustered:
|
|
parent: influxctl
|
|
weight: 201
|
|
metadata: [influxctl 2.4.0+]
|
|
related:
|
|
- /influxdb3/clustered/reference/sql/
|
|
- /influxdb3/clustered/query-data/
|
|
---
|
|
|
|
The `influxctl query` command queries data from {{< product-name >}} 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
|
|
|
|
{{% note %}}
|
|
#### 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.
|
|
{{% /note %}}
|
|
|
|
### InfluxDB connection configuration
|
|
|
|
Your {{< product-name omit=" Clustered" >}} 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] <QUERY>
|
|
```
|
|
|
|
## 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`) |
|
|
| | `--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 |
|
|
|
|
{{% caption %}}
|
|
_Also see [`influxctl` global flags](/influxdb3/clustered/reference/cli/influxctl/#global-flags)._
|
|
{{% /caption %}}
|
|
|
|
## Examples
|
|
|
|
- [Query InfluxDB v3 with SQL](#query-influxdb-v3-with-sql)
|
|
- [Query InfluxDB v3 with InfluxQL](#query-influxdb-v3-with-influxql)
|
|
- [Query InfluxDB v3 and return results in table format](#query-influxdb-v3-and-return-results-in-table-format)
|
|
- [Query InfluxDB v3 and return results in JSON format](#query-influxdb-v3-and-return-results-in-json-format)
|
|
- [Query InfluxDB v3 and return results with Unix nanosecond timestamps](#query-influxdb-v3-and-return-results-with-unix-nanosecond-timestamps)
|
|
- [Query InfluxDB v3 using credentials from the connection profile](#query-influxdb-v3-using-credentials-from-the-connection-profile)
|
|
- [Query data from InfluxDB v3 system tables](#query-data-from-influxdb-v3-system-tables)
|
|
|
|
In the examples below, replace the following:
|
|
|
|
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}:
|
|
Database token with read access to the queried database
|
|
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
|
|
Name of the database to query
|
|
|
|
### Query InfluxDB v3 with SQL
|
|
|
|
{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}}
|
|
|
|
{{< code-tabs-wrapper >}}
|
|
{{% code-tabs %}}
|
|
[string](#)
|
|
[file](#)
|
|
[stdin](#)
|
|
{{% /code-tabs %}}
|
|
{{% code-tab-content %}}
|
|
{{% influxdb/custom-timestamps %}}
|
|
```sh
|
|
influxctl query \
|
|
--token DATABASE_TOKEN \
|
|
--database DATABASE_NAME \
|
|
"SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z'"
|
|
```
|
|
{{% /influxdb/custom-timestamps %}}
|
|
{{% /code-tab-content %}}
|
|
{{% code-tab-content %}}
|
|
```sh
|
|
influxctl query \
|
|
--token DATABASE_TOKEN \
|
|
--database DATABASE_NAME \
|
|
/path/to/query.sql
|
|
```
|
|
{{% /code-tab-content %}}
|
|
{{% code-tab-content %}}
|
|
```sh
|
|
cat ./query.sql | influxctl query \
|
|
--token DATABASE_TOKEN \
|
|
--database DATABASE_NAME \
|
|
-
|
|
```
|
|
{{% /code-tab-content %}}
|
|
{{< /code-tabs-wrapper >}}
|
|
|
|
{{% /code-placeholders %}}
|
|
|
|
### Query InfluxDB v3 with InfluxQL
|
|
|
|
{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}}
|
|
|
|
{{< code-tabs-wrapper >}}
|
|
{{% code-tabs %}}
|
|
[string](#)
|
|
[file](#)
|
|
[stdin](#)
|
|
{{% /code-tabs %}}
|
|
{{% code-tab-content %}}
|
|
{{% influxdb/custom-timestamps %}}
|
|
```sh
|
|
influxctl query \
|
|
--token DATABASE_TOKEN \
|
|
--database DATABASE_NAME \
|
|
--language influxql \
|
|
"SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z'"
|
|
```
|
|
{{% /influxdb/custom-timestamps %}}
|
|
{{% /code-tab-content %}}
|
|
{{% code-tab-content %}}
|
|
```sh
|
|
influxctl query \
|
|
--token DATABASE_TOKEN \
|
|
--database DATABASE_NAME \
|
|
--language influxql \
|
|
/path/to/query.influxql
|
|
```
|
|
{{% /code-tab-content %}}
|
|
{{% code-tab-content %}}
|
|
```sh
|
|
cat ./query.influxql | influxctl query \
|
|
--token DATABASE_TOKEN \
|
|
--database DATABASE_NAME \
|
|
--language influxql \
|
|
-
|
|
```
|
|
{{% /code-tab-content %}}
|
|
{{< /code-tabs-wrapper >}}
|
|
|
|
{{% /code-placeholders %}}
|
|
|
|
### Query InfluxDB v3 and return results in table format
|
|
|
|
{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}}
|
|
|
|
{{< code-tabs-wrapper >}}
|
|
{{% code-tabs %}}
|
|
[string](#)
|
|
[file](#)
|
|
[stdin](#)
|
|
{{% /code-tabs %}}
|
|
{{% code-tab-content %}}
|
|
{{% influxdb/custom-timestamps %}}
|
|
```sh
|
|
influxctl query \
|
|
--token DATABASE_TOKEN \
|
|
--database DATABASE_NAME \
|
|
"SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' LIMIT 5"
|
|
```
|
|
{{% /influxdb/custom-timestamps %}}
|
|
{{% /code-tab-content %}}
|
|
{{% code-tab-content %}}
|
|
```sh
|
|
influxctl query \
|
|
--token DATABASE_TOKEN \
|
|
--database DATABASE_NAME \
|
|
/path/to/query.sql
|
|
```
|
|
{{% /code-tab-content %}}
|
|
{{% code-tab-content %}}
|
|
```sh
|
|
cat ./query.sql | influxctl query \
|
|
--token DATABASE_TOKEN \
|
|
--database DATABASE_NAME \
|
|
-
|
|
```
|
|
{{% /code-tab-content %}}
|
|
{{< /code-tabs-wrapper >}}
|
|
|
|
{{% /code-placeholders %}}
|
|
|
|
{{< expand-wrapper >}}
|
|
{{% expand "View example table-formatted results" %}}
|
|
{{% influxdb/custom-timestamps %}}
|
|
```
|
|
+-------+--------+---------+------+----------------------+
|
|
| 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 | | | |
|
|
+-------+--------+---------+------+----------------------+
|
|
```
|
|
{{% /influxdb/custom-timestamps %}}
|
|
{{% /expand %}}
|
|
{{< /expand-wrapper >}}
|
|
|
|
### Query InfluxDB v3 and return results in JSON format
|
|
|
|
{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}}
|
|
|
|
{{< code-tabs-wrapper >}}
|
|
{{% code-tabs %}}
|
|
[string](#)
|
|
[file](#)
|
|
[stdin](#)
|
|
{{% /code-tabs %}}
|
|
{{% code-tab-content %}}
|
|
{{% influxdb/custom-timestamps %}}
|
|
```sh
|
|
influxctl query \
|
|
--token DATABASE_TOKEN \
|
|
--database DATABASE_NAME \
|
|
--format json \
|
|
"SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' LIMIT 5"
|
|
```
|
|
{{% /influxdb/custom-timestamps %}}
|
|
{{% /code-tab-content %}}
|
|
{{% code-tab-content %}}
|
|
```sh
|
|
influxctl query \
|
|
--token DATABASE_TOKEN \
|
|
--database DATABASE_NAME \
|
|
--format json \
|
|
/path/to/query.sql
|
|
```
|
|
{{% /code-tab-content %}}
|
|
{{% code-tab-content %}}
|
|
```sh
|
|
cat ./query.sql | influxctl query \
|
|
--token DATABASE_TOKEN \
|
|
--database DATABASE_NAME \
|
|
--format json \
|
|
-
|
|
```
|
|
{{% /code-tab-content %}}
|
|
{{< /code-tabs-wrapper >}}
|
|
|
|
{{% /code-placeholders %}}
|
|
|
|
{{< expand-wrapper >}}
|
|
{{% expand "View example JSON-formatted results" %}}
|
|
{{% influxdb/custom-timestamps %}}
|
|
```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
|
|
}
|
|
]
|
|
```
|
|
{{% /influxdb/custom-timestamps %}}
|
|
{{% /expand %}}
|
|
{{< /expand-wrapper >}}
|
|
|
|
### Query InfluxDB v3 and return results with Unix nanosecond timestamps
|
|
|
|
{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}}
|
|
|
|
{{< code-tabs-wrapper >}}
|
|
{{% code-tabs %}}
|
|
[string](#)
|
|
[file](#)
|
|
[stdin](#)
|
|
{{% /code-tabs %}}
|
|
{{% code-tab-content %}}
|
|
{{% influxdb/custom-timestamps %}}
|
|
```sh
|
|
influxctl query \
|
|
--token DATABASE_TOKEN \
|
|
--database DATABASE_NAME \
|
|
--time-format unixnano \
|
|
"SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' LIMIT 5"
|
|
```
|
|
{{% /influxdb/custom-timestamps %}}
|
|
{{% /code-tab-content %}}
|
|
{{% code-tab-content %}}
|
|
```sh
|
|
influxctl query \
|
|
--token DATABASE_TOKEN \
|
|
--database DATABASE_NAME \
|
|
--time-format unixnano \
|
|
/path/to/query.sql
|
|
```
|
|
{{% /code-tab-content %}}
|
|
{{% code-tab-content %}}
|
|
```sh
|
|
cat ./query.sql | influxctl query \
|
|
--token DATABASE_TOKEN \
|
|
--database DATABASE_NAME \
|
|
--time-format unixnano \
|
|
-
|
|
```
|
|
{{% /code-tab-content %}}
|
|
{{< /code-tabs-wrapper >}}
|
|
|
|
{{% /code-placeholders %}}
|
|
|
|
{{< expand-wrapper >}}
|
|
{{% expand "View example table-formatted results" %}}
|
|
{{% influxdb/custom-timestamps %}}
|
|
```
|
|
+-------+--------+---------+------+---------------------+
|
|
| 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 | | | |
|
|
+-------+--------+---------+------+---------------------+
|
|
```
|
|
{{% /influxdb/custom-timestamps %}}
|
|
{{% /expand %}}
|
|
{{< /expand-wrapper >}}
|
|
|
|
### Query InfluxDB v3 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).
|
|
|
|
{{% influxdb/custom-timestamps %}}
|
|
```sh
|
|
influxctl query "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z'"
|
|
```
|
|
{{% /influxdb/custom-timestamps %}}
|
|
|
|
### Query data from InfluxDB v3 system tables
|
|
|
|
{{% note %}}
|
|
You must use **SQL** to query InfluxDB v3 system tables.
|
|
{{% /note %}}
|
|
|
|
{{% warn %}}
|
|
Querying system tables can impact the overall performance of your
|
|
{{< product-name omit=" Clustered" >}} cluster. System tables are not part of
|
|
InfluxDB's stable API and are subject to change.
|
|
{{% /warn %}}
|
|
|
|
{{% code-placeholders "DATABASE_(TOKEN|NAME)|TABLE_NAME" %}}
|
|
|
|
{{< code-tabs-wrapper >}}
|
|
{{% code-tabs %}}
|
|
[string](#)
|
|
[file](#)
|
|
[stdin](#)
|
|
{{% /code-tabs %}}
|
|
{{% code-tab-content %}}
|
|
{{% influxdb/custom-timestamps %}}
|
|
```sh
|
|
influxctl query \
|
|
--enable-system-tables \
|
|
--token DATABASE_TOKEN \
|
|
--database DATABASE_NAME \
|
|
"SELECT * FROM system.tables WHERE table_name = 'TABLE_NAME'"
|
|
```
|
|
{{% /influxdb/custom-timestamps %}}
|
|
{{% /code-tab-content %}}
|
|
{{% code-tab-content %}}
|
|
```sh
|
|
influxctl query \
|
|
--enable-system-tables \
|
|
--token DATABASE_TOKEN \
|
|
--database DATABASE_NAME \
|
|
/path/to/query.sql
|
|
```
|
|
{{% /code-tab-content %}}
|
|
{{% code-tab-content %}}
|
|
```sh
|
|
cat ./query.sql | influxctl query \
|
|
--enable-system-tables \
|
|
--token DATABASE_TOKEN \
|
|
--database DATABASE_NAME \
|
|
-
|
|
```
|
|
{{% /code-tab-content %}}
|
|
{{< /code-tabs-wrapper >}}
|
|
|
|
{{% /code-placeholders %}}
|
|
|
|
{{% expand "View command updates" %}}
|
|
|
|
#### v2.9.0 {date="2024-05-06"}
|
|
|
|
- Add `--time-format` flag to specify which timestamp format to use in the
|
|
`table` output format.
|
|
|
|
#### v2.8.0 {date="2024-04-11"}
|
|
|
|
- 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 v3
|
|
system tables.
|
|
|
|
{{% /expand %}}
|