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/clustered/reference/cli/influxctl/query.md

13 KiB
Raw Permalink Blame History

title description menu weight metadata related
influxctl query The `influxctl query` command queries data from InfluxDB Clustered using SQL and prints results as a table or JSON.
influxdb3_clustered
parent
influxctl
201
influxctl 2.4.0+
/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. 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)
--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 v3 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 v3 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 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 %}}

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

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

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

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

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.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 v3 system tables.

{{% /expand %}}