Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
docs-v2/content/influxdb3/cloud-dedicated/reference/cli/influxctl/query.md

16 KiB
Raw Permalink Blame History

title description menu weight metadata related
influxctl query The `influxctl query` command queries data from InfluxDB Cloud Dedicated using SQL or InfluxQL and prints results as a table or JSON.
influxdb3_cloud_dedicated
parent
influxctl
201
influxctl 2.4.0+
/influxdb3/cloud-dedicated/reference/sql/
/influxdb3/cloud-dedicated/reference/influxql/
/influxdb3/cloud-dedicated/query-data/
/influxdb3/cloud-dedicated/admin/query-system-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.

InfluxDB connection configuration

Your {{< product-name omit=" Clustered" >}} 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:

Usage

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

{{% caption %}} Also see influxctl global flags. {{% /caption %}}

Examples

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 3 with SQL

{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}}

{{< code-tabs-wrapper >}} {{% code-tabs %}} string file stdin {{% /code-tabs %}} {{% code-tab-content %}} {{% influxdb/custom-timestamps %}}

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 %}}

influxctl query \
  --token DATABASE_TOKEN \
  --database DATABASE_NAME \
  /path/to/query.sql

{{% /code-tab-content %}} {{% code-tab-content %}}

cat ./query.sql | influxctl query \
  --token DATABASE_TOKEN \
  --database DATABASE_NAME \
  -

{{% /code-tab-content %}} {{< /code-tabs-wrapper >}}

{{% /code-placeholders %}}

Query InfluxDB 3 with InfluxQL

{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}}

{{< code-tabs-wrapper >}} {{% code-tabs %}} string file stdin {{% /code-tabs %}} {{% code-tab-content %}} {{% influxdb/custom-timestamps %}}

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 %}}

influxctl query \
  --token DATABASE_TOKEN \
  --database DATABASE_NAME \
  --language influxql \
  /path/to/query.influxql

{{% /code-tab-content %}} {{% code-tab-content %}}

cat ./query.influxql | influxctl query \
  --token DATABASE_TOKEN \
  --database DATABASE_NAME \
  --language influxql \
  -

{{% /code-tab-content %}} {{< /code-tabs-wrapper >}}

{{% /code-placeholders %}}

Query InfluxDB 3 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 %}}

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 %}}

influxctl query \
  --token DATABASE_TOKEN \
  --database DATABASE_NAME \
  /path/to/query.sql

{{% /code-tab-content %}} {{% code-tab-content %}}

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 3 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 %}}

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 %}}

influxctl query \
  --token DATABASE_TOKEN \
  --database DATABASE_NAME \
  --format json \
  /path/to/query.sql

{{% /code-tab-content %}} {{% code-tab-content %}}

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 %}}

[
  {
    "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 3 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 %}}

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 %}}

influxctl query \
  --token DATABASE_TOKEN \
  --database DATABASE_NAME \
  --time-format unixnano \
  /path/to/query.sql

{{% /code-tab-content %}} {{% code-tab-content %}}

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 3 using credentials from the connection profile

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

{{% influxdb/custom-timestamps %}}

influxctl query "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z'"

{{% /influxdb/custom-timestamps %}}

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.

{{< code-tabs-wrapper >}} {{% code-tabs %}} Table format JSON format {{% /code-tabs %}} {{% code-tab-content %}}

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)"

{{% /code-tab-content %}} {{% code-tab-content %}}

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)"

{{% /code-tab-content %}} {{< /code-tabs-wrapper >}}

The output is similar to the following:

{{< expand-wrapper >}} {{% expand "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 |
+--------------------------+----------+

{{% /expand %}} {{% expand "View example JSON-formatted performance statistics" %}}

{
  "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
}

{{% /expand %}} {{< /expand-wrapper >}}

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 {{< product-name omit=" Clustered" >}} cluster. System tables are not part of InfluxDB's stable API and are subject to change.

{{% code-placeholders "DATABASE_(TOKEN|NAME)|TABLE_NAME" %}}

{{< code-tabs-wrapper >}} {{% code-tabs %}} string file stdin {{% /code-tabs %}} {{% code-tab-content %}} {{% influxdb/custom-timestamps %}}

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 %}}

influxctl query \
  --enable-system-tables \
  --token DATABASE_TOKEN \
  --database DATABASE_NAME \
  /path/to/query.sql

{{% /code-tab-content %}} {{% code-tab-content %}}

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

{{% /expand %}}