diff --git a/content/influxdb/cloud-dedicated/get-started/_index.md b/content/influxdb/cloud-dedicated/get-started/_index.md index a3ef7eef7..85bdb8a57 100644 --- a/content/influxdb/cloud-dedicated/get-started/_index.md +++ b/content/influxdb/cloud-dedicated/get-started/_index.md @@ -92,33 +92,37 @@ The following table compares tools that you can use to interact with {{% product This tutorial covers many of the recommended tools. | Tool | Administration | Write | Query | -|:----------------------------------------------------------------------------------------------------|:------------------------:|:------------------------:|:------------------------:| +| :-------------------------------------------------------------------------------------------------- | :----------------------: | :----------------------: | :----------------------: | | [Chronograf](/chronograf/v1/) | - | - | **{{< icon "check" >}}** | -| `influx` CLI | - | - | - | +| `influx` CLI | - | - | - | +| [`influxctl` CLI](#influxctl-cli){{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | | [`influx3` data CLI](#influx3-data-cli){{< req text="\* " color="magenta" >}} | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | -| [`influxctl` admin CLI](#influxctl-admin-cli) | **{{< icon "check" >}}** | - | - | -| [InfluxDB HTTP API](#influxdb-http-api) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | -| InfluxDB user interface | - | - | - | +| [InfluxDB HTTP API](#influxdb-http-api){{< req text="\* " color="magenta" >}} | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | +| InfluxDB user interface | - | - | - | | [InfluxDB v3 client libraries](#influxdb-v3-client-libraries){{< req text="\* " color="magenta" >}} | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | -| [InfluxDB v1 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v1/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | | [InfluxDB v2 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v2/) | - | **{{< icon "check" >}}** | - | -| Telegraf | - | **{{< icon "check" >}}** | - | -| **Third-party tools** | -| Flight SQL clients | - | - | **{{< icon "check" >}}** | -| [Grafana](/influxdb/cloud-dedicated/query-data/sql/execute-queries/grafana/) | - | - | **{{< icon "check" >}}** | -| [Superset](/influxdb/cloud-dedicated/query-data/sql/execute-queries/superset/) | - | - | **{{< icon "check" >}}** | -| [Tableau](/influxdb/cloud-dedicated/process-data/visualize/tableau/) | - | - | **{{< icon "check" >}}** | +| [InfluxDB v1 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v1/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | +| [Telegraf](/telegraf/v1/){{< req text="\* " color="magenta" >}} | - | **{{< icon "check" >}}** | - | +| **Third-party tools** | | | | +| Flight SQL clients | - | - | **{{< icon "check" >}}** | +| [Grafana](/influxdb/cloud-dedicated/query-data/sql/execute-queries/grafana/) | - | - | **{{< icon "check" >}}** | +| [Superset](/influxdb/cloud-dedicated/query-data/sql/execute-queries/superset/) | - | - | **{{< icon "check" >}}** | +| [Tableau](/influxdb/cloud-dedicated/process-data/visualize/tableau/) | - | - | **{{< icon "check" >}}** | +{{< caption >}} {{< req type="key" text="Covered in this tutorial" color="magenta" >}} +{{< /caption >}} {{% warn %}} Avoid using the `influx` CLI with {{% product-name %}}. While it may coincidentally work, it isn't supported. {{% /warn %}} -### `influxctl` admin CLI +### `influxctl` CLI -The [`influxctl` command line interface (CLI)](/influxdb/cloud-dedicated/reference/cli/influxctl/) performs administrative tasks, such as managing databases and authorization tokens in a cluster. +The [`influxctl` command line interface (CLI)](/influxdb/cloud-dedicated/reference/cli/influxctl/) +writes, queries, and performs administrative tasks, such as managing databases +and authorization tokens in a cluster. ### `influx3` data CLI diff --git a/content/influxdb/cloud-dedicated/get-started/query.md b/content/influxdb/cloud-dedicated/get-started/query.md index a72ec1406..ddc0a56d0 100644 --- a/content/influxdb/cloud-dedicated/get-started/query.md +++ b/content/influxdb/cloud-dedicated/get-started/query.md @@ -44,8 +44,9 @@ The examples in this section of the tutorial query the {{% product-name %}} supports many different tools for querying data, including: {{< req type="key" text="Covered in this tutorial" color="magenta" >}} -- [`influx3` data CLI](?t=influx3+CLI#execute-an-sql-query){{< req "\* " >}} -- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/){{< req "\* " >}} +- [`influxctl` CLI](#execute-an-sql-query){{< req text="\* " color="magenta" >}} +- [`influx3` data CLI](?t=influx3+CLI#execute-an-sql-query){{< req text="\* " color="magenta" >}} +- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/){{< req text="\* " color="magenta" >}} - [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight/) - [Superset](/influxdb/cloud-dedicated/query-data/sql/execute-queries/superset/) - [Grafana](/influxdb/cloud-dedicated/query-data/sql/execute-queries/grafana/) @@ -176,8 +177,11 @@ ORDER BY room, _time Get started with one of the following tools for querying data stored in an {{% product-name %}} database: +- **`influxctl` CLI**: Query data from your command-line using the + [`influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/). +- **`influx3` CLI**: Query data from your terminal command-line using the + Python-based [`influx3` CLI](https://github.com/InfluxCommunity/influxdb3-python). - **InfluxDB v3 client libraries**: Use language-specific (Python, Go, etc.) clients to execute queries in your terminal or custom code. -- **influx3 CLI**: Send queries from your terminal command-line. - **Grafana**: Use the [FlightSQL Data Source plugin](https://grafana.com/grafana/plugins/influxdata-flightsql-datasource/), to query, connect, and visualize data. For this example, use the following query to select all the data written to the @@ -200,13 +204,14 @@ WHERE {{% note %}} Some examples in this getting started tutorial assume your InfluxDB -credentials (**URL**, **organization**, and **token**) are provided by +credentials (**URL**, and **token**) are provided by [environment variables](/influxdb/cloud-dedicated/get-started/setup/?t=InfluxDB+API#configure-authentication-credentials). {{% /note %}} {{< tabs-wrapper >}} {{% tabs %}} -[influx3 CLI](#influx3-cli) +[influxctl CLI](#) +[influx3 CLI](#) [Python](#) [Go](#) [Node.js](#) @@ -214,6 +219,38 @@ credentials (**URL**, **organization**, and **token**) are provided by [Java](#) {{% /tabs %}} {{% tab-content %}} + + +Use the [`influxctl query` command](/influxdb/cloud-dedicated/reference/cli/influxctl/query/) +to query the [home sensor sample data](#home-sensor-data-line-protocol) in your +{{< product-name omit=" Clustered" >}} cluster. +Provide the following: + +- Database name to query using the `--database` flag +- Database token using the `--token` flag (use the `INFLUX_TOKEN` environment variable created in + [Get started--Set up {{< product-name >}}](/influxdb/cloud-dedicated/get-started/setup/#configure-authentication-credentials)) +- SQL query + +{{% influxdb/custom-timestamps %}} +{{% code-placeholders "get-started" %}} +```sh +influxctl query \ + --database get-started \ + --token $INFLUX_TOKEN \ + "SELECT + * +FROM + home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z'" +``` +{{% /code-placeholders %}} +{{% /influxdb/custom-timestamps %}} + + +{{% /tab-content %}} +{{% tab-content %}} {{% influxdb/custom-timestamps %}} diff --git a/content/influxdb/cloud-dedicated/get-started/setup.md b/content/influxdb/cloud-dedicated/get-started/setup.md index 472fbb61a..b456aa553 100644 --- a/content/influxdb/cloud-dedicated/get-started/setup.md +++ b/content/influxdb/cloud-dedicated/get-started/setup.md @@ -68,11 +68,7 @@ If stored at a non-default location, include the `--config` flag with each `influxctl` command and provide the path to your profile configuration file. {{% /note %}} - **Copy and paste the sample configuration profile code** into your `config.toml` - and replace the following with your {{< product-name >}} credentials: - - - `ACCOUNT_ID`: Your account ID - - `CLUSTER_ID`: Your cluster ID + **Copy and paste the sample configuration profile code** into your `config.toml`: {{% code-placeholders "ACCOUNT_ID|CLUSTER_ID" %}} ```toml @@ -81,9 +77,15 @@ If stored at a non-default location, include the `--config` flag with each product = "dedicated" account_id = "ACCOUNT_ID" cluster_id = "CLUSTER_ID" + host = "{{< influxdb/host >}}" ``` {{% /code-placeholders %}} +Replace the following with your {{< product-name >}} credentials: + +- {{% code-placeholder-key %}}`ACCOUNT_ID`{{% /code-placeholder-key %}}: Your account ID +- {{% code-placeholder-key %}}`CLUSTER_ID`{{% /code-placeholder-key %}}: Your cluster ID + _For detailed information about `influxctl` profiles, see [Configure connection profiles](/influxdb/cloud-dedicated/reference/cli/influxctl/#configure-connection-profiles)_. @@ -198,6 +200,7 @@ set INFLUX_TOKEN=DATABASE_TOKEN {{% /tab-content %}} {{< /tabs-wrapper >}} -Replace `DATABASE_TOKEN` with your [database token](#create-a-database-token) string. +Replace {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}} +with your [database token](#create-a-database-token) string. {{< page-nav prev="/influxdb/cloud-dedicated/get-started/" next="/influxdb/cloud-dedicated/get-started/write/" keepTab=true >}} diff --git a/content/influxdb/cloud-dedicated/get-started/write.md b/content/influxdb/cloud-dedicated/get-started/write.md index 35e3a28c5..14c862ed0 100644 --- a/content/influxdb/cloud-dedicated/get-started/write.md +++ b/content/influxdb/cloud-dedicated/get-started/write.md @@ -27,6 +27,7 @@ InfluxDB provides many different options for ingesting or writing data, includin - InfluxDB HTTP API (v1 and v2) - Telegraf +- `influxctl` CLI - `influx3` data CLI - InfluxDB client libraries @@ -46,7 +47,8 @@ Each line of line protocol contains the following elements: {{< req type="key" >}} -- {{< req "\*" >}} **measurement**: String that identifies the [measurement](/influxdb/cloud-dedicated/reference/glossary/#measurement) to store the data in. +- {{< req "\*" >}} **measurement**: String that identifies the + [measurement](/influxdb/cloud-dedicated/reference/glossary/#measurement) to store the data in. - **tag set**: Comma-delimited list of key value pairs, each representing a tag. Tag keys and values are unquoted strings. _Spaces, commas, and equal characters must be escaped._ - {{< req "\*" >}} **field set**: Comma-delimited list of key value pairs, each representing a field. @@ -150,6 +152,7 @@ credentials (**URL**, **organization**, and **token**) are provided by {{< tabs-wrapper >}} {{% tabs %}} +[influxctl CLI](#) [Telegraf](#) [v1 API](#) [v2 API](#) @@ -160,6 +163,59 @@ credentials (**URL**, **organization**, and **token**) are provided by [Java](#) {{% /tabs %}} {{% tab-content %}} + + +Use the [`influxctl write` command](/influxdb/cloud-dedicated/reference/cli/influxctl/write/) +to write the [home sensor sample data](#home-sensor-data-line-protocol) to your +{{< product-name omit=" Clustered" >}} cluster. +Provide the following: + +- Database name using the `--database` flag +- Database token using the `--token` flag (use the `INFLUX_TOKEN` environment variable created in + [Get started--Set up {{< product-name >}}](/influxdb/cloud-dedicated/get-started/setup/#configure-authentication-credentials)) +- Timestamp precision as seconds (`s`) using the `--precision` flag +- [Home sensor data line protocol](#home-sensor-data-line-protocol) + +{{% influxdb/custom-timestamps %}} +{{% code-placeholders "get-started" %}} +```sh +influxctl write \ + --database get-started \ + --token $INFLUX_TOKEN \ + --precision s \ + 'home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 +home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 +home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 +home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 +home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 +home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 +home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 +home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 +home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 +home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 +home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 +home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000 +home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600 +home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600 +home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200 +home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200 +home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800 +home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800 +home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400 +home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400 +home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000 +home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000 +home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600 +home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600 +home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200 +home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200' +``` + +{{% /code-placeholders %}} +{{% /influxdb/custom-timestamps %}} + +{{% /tab-content %}} +{{% tab-content %}} {{% influxdb/custom-timestamps %}} diff --git a/content/influxdb/cloud-dedicated/query-data/execute-queries/influxctl-cli.md b/content/influxdb/cloud-dedicated/query-data/execute-queries/influxctl-cli.md new file mode 100644 index 000000000..9200af133 --- /dev/null +++ b/content/influxdb/cloud-dedicated/query-data/execute-queries/influxctl-cli.md @@ -0,0 +1,173 @@ +--- +title: Use the influxctl CLI to query data +list_title: Use the influxctl CLI +description: > + Use the `influxctl query` command to query data in InfluxDB Cloud Dedicated + with SQL. +weight: 301 +menu: + influxdb_cloud_dedicated: + parent: Execute queries + name: Use the influxctl CLI +influxdb/cloud-dedicated/tags: [query, sql, influxctl, CLI] +metadata: [SQL] +related: + - /influxdb/cloud-dedicated/reference/cli/influxctl/query/ + - /influxdb/cloud-dedicated/get-started/query/#execute-an-sql-query, Get started querying data + - /influxdb/cloud-dedicated/reference/sql/ +list_code_example: | + ```sh + influxctl query \ + --token DATABASE_TOKEN \ + --database DATABASE_NAME \ + "q=SELECT * FROM home" + ``` +--- + +Use the [`influxctl query` command](/influxdb/cloud-dedicated/reference/cli/influxctl/query/) +to query data in {{< product-name >}} with SQL. + +{{% note %}} +The `influxctl query` command only supports SQL queries; not InfluxQL. +{{% /note %}} + +Provide the following with your command: + +- **Database token**: [Database token](/influxdb/cloud-dedicated/admin/tokens/) + with read permissions on the queried database. Uses the `token` setting from + the [`influxctl` connection profile](/influxdb/cloud-dedicated/reference/cli/influxctl/#configure-connection-profiles) + or the `--token` command flag. +- **Database name**: Name of the database to query. Uses the `database` setting + from the [`influxctl` connection profile](/influxdb/cloud-dedicated/reference/cli/influxctl/#configure-connection-profiles) + or the `--database` command flag. +- **SQL query**: SQL query to execute. + Pass the query in one of the following ways: + + - a string on the command line + - a path to a file that contains the query + - a single dash (`-`) to read the query from stdin + +{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[string](#) +[file](#) +[stdin](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +influxctl query \ + --token DATABASE_TOKEN \ + --database DATABASE_NAME \ + "SELECT * FROM home" +``` +{{% /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 %}} + +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 + + +## Output format + +The `influxctl query` command supports the following output formats: + +- `table` _(default)_ +- `json` + +Use the `--format` flag to specify the output format: + +{{% influxdb/custom-timestamps %}} +```sh +influxctl query \ + --format json \ + "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' LIMIT 5" +``` +{{% /influxdb/custom-timestamps %}} + +{{< 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 "View example JSON-formatted results" %}} +{{% influxdb/custom-timestamps %}} +```json +[ + { + "co": 0, + "hum": 35.9, + "room": "Kitchen", + "temp": 21, + "time": "2022-01-01T08:00:00Z" + }, + { + "co": 0, + "hum": 36.2, + "room": "Kitchen", + "temp": 23, + "time": "2022-01-01T09:00:00Z" + }, + { + "co": 0, + "hum": 36.1, + "room": "Kitchen", + "temp": 22.7, + "time": "2022-01-01T10:00:00Z" + }, + { + "co": 0, + "hum": 36, + "room": "Kitchen", + "temp": 22.4, + "time": "2022-01-01T11:00:00Z" + }, + { + "co": 0, + "hum": 36, + "room": "Kitchen", + "temp": 22.5, + "time": "2022-01-01T12:00:00Z" + } +] +``` +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{< /expand-wrapper >}} + diff --git a/content/influxdb/clustered/get-started/_index.md b/content/influxdb/clustered/get-started/_index.md index 9ed4fd49a..9bec42bf3 100644 --- a/content/influxdb/clustered/get-started/_index.md +++ b/content/influxdb/clustered/get-started/_index.md @@ -93,24 +93,26 @@ The following table compares tools that you can use to interact with {{% product This tutorial covers many of the recommended tools. | Tool | Administration | Write | Query | -|:----------------------------------------------------------------------------------------------------|:------------------------:|:------------------------:|:------------------------:| +| :-------------------------------------------------------------------------------------------------- | :----------------------: | :----------------------: | :----------------------: | | [Chronograf](/chronograf/v1/) | - | - | **{{< icon "check" >}}** | -| `influx` CLI | - | - | - | +| `influx` CLI | - | - | - | +| [`influxctl` CLI](#influxctl-cli){{< req text="\* " color="magenta" >}} | **{{< icon "check" >}}** | **{{< icon "check" >}}** | **{{< icon "check" >}}** | | [`influx3` data CLI](#influx3-data-cli){{< req text="\* " color="magenta" >}} | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | -| [`influxctl` admin CLI](#influxctl-admin-cli) | **{{< icon "check" >}}** | - | - | -| [InfluxDB HTTP API](#influxdb-http-api) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | -| InfluxDB user interface | - | - | - | +| [InfluxDB HTTP API](#influxdb-http-api){{< req text="\* " color="magenta" >}} | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | +| InfluxDB user interface | - | - | - | | [InfluxDB v3 client libraries](#influxdb-v3-client-libraries){{< req text="\* " color="magenta" >}} | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | -| [InfluxDB v1 client libraries](/influxdb/clustered/reference/client-libraries/v1/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | | [InfluxDB v2 client libraries](/influxdb/clustered/reference/client-libraries/v2/) | - | **{{< icon "check" >}}** | - | -| Telegraf | - | **{{< icon "check" >}}** | - | -| **Third-party tools** | -| Flight SQL clients | - | - | **{{< icon "check" >}}** | -| [Grafana](/influxdb/clustered/query-data/sql/execute-queries/grafana/) | - | - | **{{< icon "check" >}}** | -| [Superset](/influxdb/clustered/query-data/sql/execute-queries/superset/) | - | - | **{{< icon "check" >}}** | -| [Tableau](/influxdb/clustered/process-data/visualize/tableau/) | - | - | **{{< icon "check" >}}** | +| [InfluxDB v1 client libraries](/influxdb/clustered/reference/client-libraries/v1/) | - | **{{< icon "check" >}}** | **{{< icon "check" >}}** | +| [Telegraf](/telegraf/v1/){{< req text="\* " color="magenta" >}} | - | **{{< icon "check" >}}** | - | +| **Third-party tools** | | | | +| Flight SQL clients | - | - | **{{< icon "check" >}}** | +| [Grafana](/influxdb/clustered/query-data/sql/execute-queries/grafana/) | - | - | **{{< icon "check" >}}** | +| [Superset](/influxdb/clustered/query-data/sql/execute-queries/superset/) | - | - | **{{< icon "check" >}}** | +| [Tableau](/influxdb/clustered/process-data/visualize/tableau/) | - | - | **{{< icon "check" >}}** | +{{< caption >}} {{< req type="key" text="Covered in this tutorial" color="magenta" >}} +{{< /caption >}} {{% warn %}} Avoid using the `influx` CLI with {{% product-name %}}. @@ -119,7 +121,9 @@ While it may coincidentally work, it isn't supported. ### `influxctl` admin CLI -The [`influxctl` command line interface (CLI)](/influxdb/cloud-dedicated/reference/cli/influxctl/) performs administrative tasks, such as managing databases and authorization tokens in a cluster. +The [`influxctl` command line interface (CLI)](/influxdb/cloud-dedicated/reference/cli/influxctl/) +writes, queries, and performs administrative tasks, such as managing databases +and authorization tokens in a cluster. ### `influx3` data CLI diff --git a/content/influxdb/clustered/get-started/query.md b/content/influxdb/clustered/get-started/query.md index 9fe8c9e47..c39f55845 100644 --- a/content/influxdb/clustered/get-started/query.md +++ b/content/influxdb/clustered/get-started/query.md @@ -44,9 +44,10 @@ The examples in this section of the tutorial query the {{% product-name %}} supports many different tools for querying data, including: {{< req type="key" text="Covered in this tutorial" color="magenta" >}} -- [`influx3` data CLI](?t=influx3+CLI#execute-an-sql-query){{< req "\* " >}} -- [InfluxDB v3 client libraries](/influxdb/clustered/reference/client-libraries/v3/) -- [Flight clients](/influxdb/clustered/reference/client-libraries/flight/){{< req "\* " >}} +- [`influxctl` CLI](#execute-an-sql-query){{< req text="\* " color="magenta" >}} +- [`influx3` data CLI](?t=influx3+CLI#execute-an-sql-query){{< req text="\* " color="magenta" >}} +- [InfluxDB v3 client libraries](/influxdb/clustered/reference/client-libraries/v3/){{< req text="\* " color="magenta" >}} +- [Flight clients](/influxdb/clustered/reference/client-libraries/flight/) - [Superset](/influxdb/clustered/query-data/sql/execute-queries/superset/) - [Grafana](/influxdb/clustered/query-data/sql/execute-queries/grafana/) - [InfluxQL with InfluxDB v1 HTTP API](/influxdb/clustered/query-data/execute-queries/influxdb-v1-api/) @@ -176,8 +177,11 @@ ORDER BY room, _time Get started with one of the following tools for querying data stored in an {{% product-name %}} database: +- **`influxctl` CLI**: Query data from your command-line using the + [`influxctl` CLI](/influxdb/clustered/reference/cli/influxctl/). +- **`influx3` CLI**: Query data from your terminal command-line using the + Python-based [`influx3` CLI](https://github.com/InfluxCommunity/influxdb3-python). - **InfluxDB v3 client libraries**: Use language-specific (Python, Go, etc.) clients to execute queries in your terminal or custom code. -- **influx3 CLI**: Send queries from your terminal command-line. - **Grafana**: Use the [FlightSQL Data Source plugin](https://grafana.com/grafana/plugins/influxdata-flightsql-datasource/), to query, connect, and visualize data. For this example, use the following query to select all the data written to the @@ -200,13 +204,14 @@ WHERE {{% note %}} Some examples in this getting started tutorial assume your InfluxDB -credentials (**URL**, **organization**, and **token**) are provided by +credentials (**URL** and **token**) are provided by [environment variables](/influxdb/clustered/get-started/setup/?t=InfluxDB+API#configure-authentication-credentials). {{% /note %}} {{< tabs-wrapper >}} {{% tabs %}} -[influx3 CLI](#influx3-cli) +[influxctl CLI](#) +[influx3 CLI](#) [Python](#) [Go](#) [Node.js](#) @@ -214,6 +219,38 @@ credentials (**URL**, **organization**, and **token**) are provided by [Java](#) {{% /tabs %}} {{% tab-content %}} + + +Use the [`influxctl query` command](/influxdb/clustered/reference/cli/influxctl/query/) +to query the [home sensor sample data](#home-sensor-data-line-protocol) in your +{{< product-name omit=" Clustered" >}} cluster. +Provide the following: + +- Database name to query using the `--database` flag +- Database token using the `--token` flag (use the `INFLUX_TOKEN` environment variable created in + [Get started--Set up {{< product-name >}}](/influxdb/clustered/get-started/setup/#configure-authentication-credentials)) +- SQL query + +{{% influxdb/custom-timestamps %}} +{{% code-placeholders "get-started" %}} +```sh +influxctl query \ + --database get-started \ + --token $INFLUX_TOKEN \ + "SELECT + * +FROM + home +WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z'" +``` +{{% /code-placeholders %}} +{{% /influxdb/custom-timestamps %}} + + +{{% /tab-content %}} +{{% tab-content %}} {{% influxdb/custom-timestamps %}} diff --git a/content/influxdb/clustered/get-started/setup.md b/content/influxdb/clustered/get-started/setup.md index 20f37ab27..9197b6d0d 100644 --- a/content/influxdb/clustered/get-started/setup.md +++ b/content/influxdb/clustered/get-started/setup.md @@ -61,14 +61,7 @@ If stored at a non-default location, include the `--config` flag with each `influxctl` command and provide the path to your profile configuration file. {{% /note %}} - **Copy and paste the sample configuration profile code** into your `config.toml` - and replace the following with your {{< product-name >}} credentials: - - - {{% code-placeholder-key %}}`PORT`{{% /code-placeholder-key %}}: the port to use to access your InfluxDB cluster - - {{% code-placeholder-key %}}`OAUTH_CLIENT_ID`{{% /code-placeholder-key %}}: the client URL of your OAuth2 provider - (for example: `https://indentityprovider/oauth2/v2/token`) - - {{% code-placeholder-key %}}`OAUTH_DEVICE_ID`{{% /code-placeholder-key %}}: the device URL of your OAuth2 provider - (for example: `https://indentityprovider/oauth2/v2/auth/device`) + **Copy and paste the sample configuration profile code** into your `config.toml`: {{% code-placeholders "PORT|OAUTH_TOKEN_URL|OAUTH_DEVICE_URL" %}} ```toml @@ -86,6 +79,14 @@ If stored at a non-default location, include the `--config` flag with each ``` {{% /code-placeholders %}} +Replace the following with your {{< product-name >}} credentials: + + - {{% code-placeholder-key %}}`PORT`{{% /code-placeholder-key %}}: the port to use to access your InfluxDB cluster + - {{% code-placeholder-key %}}`OAUTH_CLIENT_ID`{{% /code-placeholder-key %}}: the client URL of your OAuth2 provider + (for example: `https://indentityprovider/oauth2/v2/token`) + - {{% code-placeholder-key %}}`OAUTH_DEVICE_ID`{{% /code-placeholder-key %}}: the device URL of your OAuth2 provider + (for example: `https://indentityprovider/oauth2/v2/auth/device`) + _For detailed information about `influxctl` profiles, see [Configure connection profiles](/influxdb/clustered/reference/cli/influxctl/#configure-connection-profiles)_. @@ -200,6 +201,7 @@ set INFLUX_TOKEN=DATABASE_TOKEN {{% /tab-content %}} {{< /tabs-wrapper >}} -Replace `DATABASE_TOKEN` with your [database token](#create-a-database-token) string. +Replace {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}} +with your [database token](#create-a-database-token) string. {{< page-nav prev="/influxdb/clustered/get-started/" next="/influxdb/clustered/get-started/write/" keepTab=true >}} diff --git a/content/influxdb/clustered/get-started/write.md b/content/influxdb/clustered/get-started/write.md index 7ba1699a3..8e5e98296 100644 --- a/content/influxdb/clustered/get-started/write.md +++ b/content/influxdb/clustered/get-started/write.md @@ -27,6 +27,7 @@ InfluxDB provides many different options for ingesting or writing data, includin - InfluxDB HTTP API (v1 and v2) - Telegraf +- `influxctl` CLI - `influx3` data CLI - InfluxDB client libraries @@ -46,7 +47,8 @@ Each line of line protocol contains the following elements: {{< req type="key" >}} -- {{< req "\*" >}} **measurement**: String that identifies the [measurement](/influxdb/clustered/reference/glossary/#measurement) to store the data in. +- {{< req "\*" >}} **measurement**: String that identifies the + [measurement](/influxdb/clustered/reference/glossary/#measurement) to store the data in. - **tag set**: Comma-delimited list of key value pairs, each representing a tag. Tag keys and values are unquoted strings. _Spaces, commas, and equal characters must be escaped._ - {{< req "\*" >}} **field set**: Comma-delimited list of key value pairs, each representing a field. @@ -150,6 +152,7 @@ credentials (**URL**, **organization**, and **token**) are provided by {{< tabs-wrapper >}} {{% tabs %}} +[influxctl CLI](#) [Telegraf](#) [v1 API](#) [v2 API](#) @@ -160,6 +163,59 @@ credentials (**URL**, **organization**, and **token**) are provided by [Java](#) {{% /tabs %}} {{% tab-content %}} + + +Use the [`influxctl write` command](/influxdb/clustered/reference/cli/influxctl/write/) +to write the [home sensor sample data](#home-sensor-data-line-protocol) to your +{{< product-name omit=" Clustered" >}} cluster. +Provide the following: + +- Database name using the `--database` flag +- Database token using the `--token` flag (use the `INFLUX_TOKEN` environment variable created in + [Get started--Set up {{< product-name >}}](/influxdb/clustered/get-started/setup/#configure-authentication-credentials)) +- Timestamp precision as seconds (`s`) using the `--precision` flag +- [Home sensor data line protocol](#home-sensor-data-line-protocol) + +{{% influxdb/custom-timestamps %}} +{{% code-placeholders "get-started" %}} +```sh +influxctl write \ + --database get-started \ + --token $INFLUX_TOKEN \ + --precision s \ + 'home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 +home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 +home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 +home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 +home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 +home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 +home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 +home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 +home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 +home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 +home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 +home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000 +home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600 +home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600 +home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200 +home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200 +home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800 +home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800 +home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400 +home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400 +home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000 +home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000 +home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600 +home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600 +home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200 +home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200' +``` + +{{% /code-placeholders %}} +{{% /influxdb/custom-timestamps %}} + +{{% /tab-content %}} +{{% tab-content %}} {{% influxdb/custom-timestamps %}} diff --git a/content/influxdb/clustered/query-data/execute-queries/influxctl-cli.md b/content/influxdb/clustered/query-data/execute-queries/influxctl-cli.md new file mode 100644 index 000000000..dcf43d8f9 --- /dev/null +++ b/content/influxdb/clustered/query-data/execute-queries/influxctl-cli.md @@ -0,0 +1,172 @@ +--- +title: Use the influxctl CLI to query data +list_title: Use the influxctl CLI +description: > + Use the `influxctl query` command to query data in InfluxDB Clustered with SQL. +weight: 301 +menu: + influxdb_clustered: + parent: Execute queries + name: Use the influxctl CLI +influxdb/clustered/tags: [query, sql, influxctl, CLI] +metadata: [SQL] +related: + - /influxdb/clustered/reference/cli/influxctl/query/ + - /influxdb/clustered/get-started/query/#execute-an-sql-query, Get started querying data + - /influxdb/clustered/reference/sql/ +list_code_example: | + ```sh + influxctl query \ + --token DATABASE_TOKEN \ + --database DATABASE_NAME \ + "q=SELECT * FROM home" + ``` +--- + +Use the [`influxctl query` command](/influxdb/clustered/reference/cli/influxctl/query/) +to query data in {{< product-name >}} with SQL. + +{{% note %}} +The `influxctl query` command only supports SQL queries; not InfluxQL. +{{% /note %}} + +Provide the following with your command: + +- **Database token**: [Database token](/influxdb/clustered/admin/tokens/) + with read permissions on the queried database. Uses the `token` setting from + the [`influxctl` connection profile](/influxdb/clustered/reference/cli/influxctl/#configure-connection-profiles) + or the `--token` command flag. +- **Database name**: Name of the database to query. Uses the `database` setting + from the [`influxctl` connection profile](/influxdb/clustered/reference/cli/influxctl/#configure-connection-profiles) + or the `--database` command flag. +- **SQL query**: SQL query to execute. + Pass the query in one of the following ways: + + - a string on the command line + - a path to a file that contains the query + - a single dash (`-`) to read the query from stdin + +{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[string](#) +[file](#) +[stdin](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +influxctl query \ + --token DATABASE_TOKEN \ + --database DATABASE_NAME \ + "SELECT * FROM home" +``` +{{% /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 %}} + +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 + + +## Output format + +The `influxctl query` command supports the following output formats: + +- `table` _(default)_ +- `json` + +Use the `--format` flag to specify the output format: + +{{% influxdb/custom-timestamps %}} +```sh +influxctl query \ + --format json \ + "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z' LIMIT 5" +``` +{{% /influxdb/custom-timestamps %}} + +{{< 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 "View example JSON-formatted results" %}} +{{% influxdb/custom-timestamps %}} +```json +[ + { + "co": 0, + "hum": 35.9, + "room": "Kitchen", + "temp": 21, + "time": "2022-01-01T08:00:00Z" + }, + { + "co": 0, + "hum": 36.2, + "room": "Kitchen", + "temp": 23, + "time": "2022-01-01T09:00:00Z" + }, + { + "co": 0, + "hum": 36.1, + "room": "Kitchen", + "temp": 22.7, + "time": "2022-01-01T10:00:00Z" + }, + { + "co": 0, + "hum": 36, + "room": "Kitchen", + "temp": 22.4, + "time": "2022-01-01T11:00:00Z" + }, + { + "co": 0, + "hum": 36, + "room": "Kitchen", + "temp": 22.5, + "time": "2022-01-01T12:00:00Z" + } +] +``` +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{< /expand-wrapper >}} +