diff --git a/.ci/v1-shared-drift-manifest.json b/.ci/v1-shared-drift-manifest.json index 544b2b13b8..24ae6f438a 100644 --- a/.ci/v1-shared-drift-manifest.json +++ b/.ci/v1-shared-drift-manifest.json @@ -27,7 +27,6 @@ "supported_protocols/prometheus.md", "tools/api_client_libraries.md", "tools/grafana.md", - "tools/influx-cli/use-influx-cli.md", "tools/influx_inspect.md", "troubleshooting/errors.md", "troubleshooting/frequently-asked-questions.md", diff --git a/content/enterprise_influxdb/v1/about-the-project/release-notes.md b/content/enterprise_influxdb/v1/about-the-project/release-notes.md index 04f493f250..c2ff3b41b4 100644 --- a/content/enterprise_influxdb/v1/about-the-project/release-notes.md +++ b/content/enterprise_influxdb/v1/about-the-project/release-notes.md @@ -42,10 +42,13 @@ alt_links: [Enable mTLS](/enterprise_influxdb/v1/administration/configure/security/enable_tls/). - Add an `influx-meta cleanup-shards` command that removes shards with no owners and shard groups with no shards from a live cluster. -- Add a `-timeout ` flag to `influxd-ctl` that applies to any - command that uses the control client, including `add-data`. +- Add a + [`-timeout `](/enterprise_influxdb/v1/tools/influxd-ctl/#override-the-default-timeout) + flag to `influxd-ctl` that applies to any command that uses the control + client, including `add-data`. - `influxd-ctl backup` now avoids data nodes with no shard data and prefers - the most recently written shard copy when selecting a source. + the most recently written shard copy when + [selecting a source](/enterprise_influxdb/v1/tools/influxd-ctl/backup/#node-selection). ### Bug Fixes diff --git a/content/enterprise_influxdb/v1/administration/configure/config-data-nodes.md b/content/enterprise_influxdb/v1/administration/configure/config-data-nodes.md index f3cd006a16..c070909769 100644 --- a/content/enterprise_influxdb/v1/administration/configure/config-data-nodes.md +++ b/content/enterprise_influxdb/v1/administration/configure/config-data-nodes.md @@ -586,7 +586,7 @@ increase in cache size may lead to an increase in heap usage. Environment variable: `INFLUXDB_DATA_SERIES_ID_SET_CACHE_SIZE` -#### series-id-set-cache-max-size +#### series-id-set-cache-max-size {metadata="v1.13.0+"} Default is `0`. @@ -600,11 +600,13 @@ adaptive sizing. both be set to enable adaptive sizing, or both left at `0` to disable it. Setting only one prevents InfluxDB from starting. When adaptive sizing is enabled, `series-id-set-cache-max-size` must be greater than -`series-id-set-cache-size`. +`series-id-set-cache-size`, and `series-id-set-cache-size` must be greater +than `0`. A `series-id-set-cache-size` of `0` disables the cache entirely, +which takes precedence over adaptive sizing. Environment variable: `INFLUXDB_DATA_SERIES_ID_SET_CACHE_MAX_SIZE` -#### series-id-set-cache-target-hit-rate +#### series-id-set-cache-target-hit-rate {metadata="v1.13.0+"} Default is `0.0`. @@ -617,7 +619,7 @@ evicting entries, InfluxDB grows the cache capacity, up to Environment variable: `INFLUXDB_DATA_SERIES_ID_SET_CACHE_TARGET_HIT_RATE` -#### series-id-set-cache-shrink-conservatism +#### series-id-set-cache-shrink-conservatism {metadata="v1.13.0+"} Default is `2.5`. diff --git a/content/enterprise_influxdb/v1/tools/influx-cli/use-influx-cli.md b/content/enterprise_influxdb/v1/tools/influx-cli/use-influx-cli.md index 287a213971..c1b4230feb 100644 --- a/content/enterprise_influxdb/v1/tools/influx-cli/use-influx-cli.md +++ b/content/enterprise_influxdb/v1/tools/influx-cli/use-influx-cli.md @@ -12,434 +12,8 @@ aliases: - /enterprise_influxdb/v1/tools/use-influx/ related: - /enterprise_influxdb/v1/administration/backup-and-restore/ +source: /shared/influxdb-v1/tools/influx-cli/use-influx-cli.md --- -The `influx` command line interface (CLI) provides an interactive shell for the HTTP API associated with `influxd`. -Use `influx` to write data (manually or from a file), query data interactively, view query output in different formats, and manage resources in InfluxDB. - -* [Launch `influx`](#launch-influx) -* [`influx` Arguments](#influx-arguments) -* [`influx` Commands](#influx-commands) - -## Launch `influx` - -The `influx` CLI is included when you [install InfluxDB Enterprise](/enterprise_influxdb/v1/introduction/installation/). - -If you [install](https://influxdata.com/downloads/) InfluxDB via a package manager, the CLI is installed at `/usr/bin/influx` ( on macOS). - -To access the CLI, first launch the `influxd` database process and then launch `influx` in your terminal. - -```bash -influx -``` - -If successfully connected to an InfluxDB node, the output is the following: - -```bash -Connected to http://localhost:8086 version {{< latest-patch >}} -InfluxDB shell version: {{< latest-patch >}} -> -``` - -_The versions of InfluxDB and the CLI should be identical. If not, parsing issues can occur with queries._ - -In the prompt, you can enter InfluxQL queries as well as CLI-specific commands. -Enter `help` to get a list of available commands. -Use `Ctrl+C` to cancel if you want to cancel a long-running InfluxQL query. - -## Environment Variables - -The following environment variables can be used to configure settings used by the `influx` client. They can be specified in lower or upper case, however the upper case version takes precedence. - -#### `HTTP_PROXY` -Defines the proxy server to use for HTTP. - -**Value format:**`[protocol://][:port]` - -``` -HTTP_PROXY=http://localhost:1234 -``` - -#### `HTTPS_PROXY` -Defines the proxy server to use for HTTPS. Takes precedence over HTTP_PROXY for HTTPS. - -**Value format:**`[protocol://][:port]` - -``` -HTTPS_PROXY=https://localhost:1443 -``` - -#### `NO_PROXY` -List of host names that should **not** go through any proxy. If set to an asterisk '\*' only, it matches all hosts. - -**Value format:** comma-separated list of hosts - -``` -NO_PROXY=123.45.67.89,123.45.67.90 -``` - -## `influx` arguments - -Arguments specify connection, write, import, and output options for the CLI session. - -`influx` provides the following arguments: - -`-h`, `-help` -List `influx` arguments - -`-cert 'path'` _(v1.13.0+)_ -Path to the client certificate file (PEM) presented for mutual TLS (mTLS). -Alternatively, set the certificate with the `INFLUX_CERT` environment variable. - -`-compressed` -Set to true if the import file is compressed. -Use with `-import`. - -`-consistency 'any|one|quorum|all'` -Set the write consistency level. - -`-database 'database name'` -The database to which `influx` connects. - -`-execute 'command'` -Execute an [InfluxQL](/enterprise_influxdb/v1/query_language/explore-data/) command and quit. -See [-execute](#execute-an-influxql-command-and-quit-with--execute). - -`-format 'json|csv|column'` -Specifies the format of the server responses. -See [-format](#specify-the-format-of-the-server-responses-with--format). - -`-host 'host name'` -The host to which `influx` connects. -By default, InfluxDB runs on localhost. - -`-ignore-cert-sanity-checks` _(v1.13.0+)_ -Load the client certificate even if it fails client-authentication sanity checks. -Alternatively, set this with the `INFLUX_IGNORE_CERT_SANITY_CHECKS` environment variable. - -`-import` -Import new data or [exported data](/enterprise_influxdb/v1/administration/backup-and-restore/#exporting-data) from a file. -See [-import](#import-data-from-a-file). - -`-insecure-certificate` _(v1.13.0+)_ -Ignore file permission checks when loading the client certificate and key. -Alternatively, set this with the `INFLUX_INSECURE_CERTIFICATE` environment variable. - -`-key 'path'` _(v1.13.0+)_ -Path to the client private key file (PEM) for mutual TLS (mTLS). -Alternatively, set the key with the `INFLUX_KEY` environment variable. - -`-password 'password'` -The password `influx` uses to connect to the server. -`influx` will prompt for a password if you leave it blank (`-password ''`). -Alternatively, set the password for the CLI with the `INFLUX_PASSWORD` environment -variable. - -`-path` -The path to the file to import. -Use with [-import](#import-data-from-a-file). - -`-port 'port #'` -The port to which `influx` connects. -By default, InfluxDB runs on port `8086`. - -`-pps` -How many points per second the import will allow. -By default, pps is zero and influx will not throttle importing. -Use with `-import`. - -`-precision 'rfc3339|h|m|s|ms|u|ns'` -Specifies the format/precision of the timestamp: `rfc3339` (`YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ`), `h` (hours), `m` (minutes), `s` (seconds), `ms` (milliseconds), `u` (microseconds), `ns` (nanoseconds). -Precision defaults to nanoseconds. - -> **Note:** Setting the precision to `rfc3339` (`-precision rfc3339`) works with the `-execute` option, but it does not work with the `-import option`. All other precision formats (e.g., `h`,`m`,`s`,`ms`,`u`, and `ns`) work with the `-execute` and `-import` options. - -`-pretty` -Turns on pretty print for the `json` format. - -`-root-ca 'path'` _(v1.13.0+)_ -Path to the CA bundle (PEM) used to verify the server certificate. -Alternatively, set the CA bundle with the `INFLUX_ROOT_CA` environment variable. - -`-ssl` -Use HTTPS for requests. - -`-unsafeSsl` -Disables SSL certificate verification. -Use when connecting over HTTPS with a self-signed certificate. - -`-username 'username'` -The username that `influx` uses to connect to the server. -Alternatively, set the username for the CLI with the `INFLUX_USERNAME` environment variable. - -`-version` -Display the InfluxDB version and exit. - -The following sections provide detailed examples for some arguments, including `-execute`, `-format`, and `-import`. - -- [Execute an InfluxQL command and quit with `-execute`](#execute-an-influxql-command-and-quit-with--execute) -- [Specify the format of the server responses with `-format`](#specify-the-format-of-the-server-responses-with--format) -- [Import data from a file](#import-data-from-a-file) - -### Execute an InfluxQL command and quit with `-execute` - -Execute queries that don't require a database specification: - -```bash -$ influx -execute 'SHOW DATABASES' -name: databases ---------------- -name -NOAA_water_database -_internal -telegraf -pirates -``` - -Execute queries that do require a database specification, and change the timestamp precision: - -```bash -$ influx -execute 'SELECT * FROM "h2o_feet" LIMIT 3' -database="NOAA_water_database" -precision=rfc3339 -name: h2o_feet --------------- -time level description location water_level -2015-08-18T00:00:00Z below 3 feet santa_monica 2.064 -2015-08-18T00:00:00Z between 6 and 9 feet coyote_creek 8.12 -2015-08-18T00:06:00Z between 6 and 9 feet coyote_creek 8.005 -``` - -### Specify the format of the server responses with `-format` - -The default format is `column`: - -```bash -$ influx -format=column -[...] -> SHOW DATABASES -name: databases ---------------- -name -NOAA_water_database -_internal -telegraf -pirates -``` - -Change the format to `csv`: - -```bash -$ influx -format=csv -[...] -> SHOW DATABASES -name,name -databases,NOAA_water_database -databases,_internal -databases,telegraf -databases,pirates -``` - -Change the format to `json`: - -```bash -$ influx -format=json -[...] -> SHOW DATABASES -{"results":[{"series":[{"name":"databases","columns":["name"],"values":[["NOAA_water_database"],["_internal"],["telegraf"],["pirates"]]}]}]} -``` - -Change the format to `json` and turn on pretty print: - -```bash -$ influx -format=json -pretty -[...] -> SHOW DATABASES -{ - "results": [ - { - "series": [ - { - "name": "databases", - "columns": [ - "name" - ], - "values": [ - [ - "NOAA_water_database" - ], - [ - "_internal" - ], - [ - "telegraf" - ], - [ - "pirates" - ] - ] - } - ] - } - ] -} -``` - -### Import data from a file - -An import file has two sections: - -- _Optional_: **DDL (Data Definition Language)**: Contains the [InfluxQL commands](/enterprise_influxdb/v1/query_language/manage-database/) for creating the relevant [database](/enterprise_influxdb/v1/concepts/glossary/) and managing the [retention policy](/enterprise_influxdb/v1/concepts/glossary/#retention-policy-rp). -If your database and retention policy already exist, your file can skip this section. -- **DML (Data Manipulation Language)**: Context metadata that specifies the database and (if desired) retention policy for the import and contains the data in [line protocol](/enterprise_influxdb/v1/concepts/glossary/#influxdb-line-protocol). - -#### Example: import data from a file - -The following `datarrr.txt` file is output using the [`influx_inspect export` command](/enterprise_influxdb/v1/tools/influx_inspect#export): - -```text -# DDL -CREATE DATABASE pirates -CREATE RETENTION POLICY oneday ON pirates DURATION 1d REPLICATION 1 - -# DML -# CONTEXT-DATABASE: pirates -# CONTEXT-RETENTION-POLICY: oneday - -treasures,captain_id=dread_pirate_roberts value=801 1439856000 -treasures,captain_id=flint value=29 1439856000 -treasures,captain_id=sparrow value=38 1439856000 -treasures,captain_id=tetra value=47 1439856000 -treasures,captain_id=crunch value=109 1439858880 -``` - -To import the file, enter the following command in your terminal: - -```bash -influx -import -path=datarrr.txt -precision=s -``` - -The data is imported into the database and retention policy specified in the `# DML` -context metadata. -The output is the following: - -```text -2015/12/22 12:25:06 Processed 2 commands -2015/12/22 12:25:06 Processed 5 inserts -2015/12/22 12:25:06 Failed 0 inserts -``` - -> **Note:** For large datasets, `influx` writes out a status message every 100,000 points. -> For example: -> -> 2015/08/21 14:48:01 Processed 3100000 lines. -> Time elapsed: 56.740578415s. -> Points per second (PPS): 54634 - -Keep the following in mind when using `-import`: - -- To throttle the import, use `-pps` to set the number of points per second to ingest. By default, pps is zero and `influx` does not throttle importing. -- To import a file compressed with `gzip` (GNU zip), include the -compressed flag. -- Include timestamps in the data file. - If points don’t include a timestamp, InfluxDB assigns the same timestamp to those points, which can result in unintended [duplicate points or overwrites](/enterprise_influxdb/v1/troubleshooting/frequently-asked-questions/#how-does-influxdb-handle-duplicate-points). -- If your data file contains more than 5,000 points, consider splitting it into smaller files to write data to InfluxDB in batches. - We recommend writing points in batches of 5,000 to 10,000 for optimal performance. - Writing smaller batches increases the number of HTTP requests, which can negatively impact performance. - By default, the HTTP request times out after five seconds. Although InfluxDB continues attempting to write the points after a timeout, you won’t receive confirmation of a successful write. - -> **Note:** To export data from InfluxDB version 0.8.9, see [Exporting from 0.8.9](https://github.com/influxdb/influxdb/blob/1.8/importer/README.md). - -For more information, see [exporting and importing data](/enterprise_influxdb/v1/administration/backup-and-restore/#exporting-and-importing-data). - -## `influx` commands - -Enter `help` in the CLI for a partial list of the available commands. - -### Commands - -The list below offers a brief discussion of each command. -We provide detailed information on `insert` at the end of this section. - -`auth` -Prompts you for your username and password. -`influx` uses those credentials when querying a database. -Alternatively, set the username and password for the CLI with the -`INFLUX_USERNAME` and `INFLUX_PASSWORD` environment variables. - -`chunked` -Turns on chunked responses from the server when issuing queries. -This setting is enabled by default. - -`chunk size ` -Sets the size of the chunked responses. -The default size is `10,000`. -Setting it to `0` resets `chunk size` to its default value. - -`clear [ database | db | retention policy | rp ]` -Clears the current context for the [database](/enterprise_influxdb/v1/concepts/glossary/#database) or [retention policy](/enterprise_influxdb/v1/concepts/glossary/#retention-policy-rp). - -`connect ` -Connect to a different server without exiting the shell. -By default, `influx` connects to `localhost:8086`. -If you do not specify either the host or the port, `influx` assumes the default setting for the missing attribute. - -`consistency ` -Sets the write consistency level: `any`, `one`, `quorum`, or `all`. - -`Ctrl+C` -Terminates the currently running query. Useful when an interactive query is taking too long to respond -because it is trying to return too much data. - -`exit` `quit` `Ctrl+D` -Quits the `influx` shell. - -`format ` -Specifies the format of the server responses: `json`, `csv`, or `column`. -See the description of [-format](#specify-the-format-of-the-server-responses-with--format) for examples of each format. - -`history` -Displays your command history. -To use the history while in the shell, simply use the "up" arrow. -`influx` stores your last 1,000 commands in your home directory in `.influx_history`. - -`insert` -Write data using line protocol. -See [insert](#write-data-to-influxdb-with-insert). - -`precision ` -Specifies the format/precision of the timestamp: `rfc3339` (`YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ`), `h` (hours), `m` (minutes), `s` (seconds), `ms` (milliseconds), `u` (microseconds), `ns` (nanoseconds). -Precision defaults to nanoseconds. - -`pretty` -Turns on pretty print for the `json` format. - -`settings` -Outputs the current settings for the shell including the `Host`, `Username`, `Database`, `Retention Policy`, `Pretty` status, `Chunked` status, `Chunk Size`, `Format`, and `Write Consistency`. - -`use [ "" | ""."" ]` -Sets the current [database](/enterprise_influxdb/v1/concepts/glossary/#database) and/or [retention policy](/enterprise_influxdb/v1/concepts/glossary/#retention-policy-rp). -Once `influx` sets the current database and/or retention policy, there is no need to specify that database and/or retention policy in queries. -If you do not specify the retention policy, `influx` automatically queries the `use`d database's `DEFAULT` retention policy. - -#### Write data to InfluxDB with `insert` - -Enter `insert` followed by the data in [line protocol](/enterprise_influxdb/v1/concepts/glossary/#influxdb-line-protocol) to write data to InfluxDB. -Use `insert into ` to write data to a specific [retention policy](/enterprise_influxdb/v1/concepts/glossary/#retention-policy-rp). - -Write data to a single field in the measurement `treasures` with the tag `captain_id = pirate_king`. -`influx` automatically writes the point to the database's `DEFAULT` retention policy. -``` -INSERT treasures,captain_id=pirate_king value=2 - -``` - -Write the same point to the already-existing retention policy `oneday`: -``` -> INSERT INTO oneday treasures,captain_id=pirate_king value=2 -Using retention policy oneday -> -``` - -### Queries - -Execute all InfluxQL queries in `influx`. - -See [Data exploration](/enterprise_influxdb/v1/query_language/explore-data/), [Schema exploration](/enterprise_influxdb/v1/query_language/explore-schema/), [Database management](/enterprise_influxdb/v1/query_language/manage-database/), [Authentication and authorization](/enterprise_influxdb/v1/administration/authentication_and_authorization/) for InfluxQL documentation. + diff --git a/content/influxdb/v1/about_the_project/release-notes.md b/content/influxdb/v1/about_the_project/release-notes.md index 52f2407dd6..f0a14cd1e8 100644 --- a/content/influxdb/v1/about_the_project/release-notes.md +++ b/content/influxdb/v1/about_the_project/release-notes.md @@ -46,8 +46,9 @@ alt_links: now accept a wider range of human-readable input formats, while remaining compatible with all previously accepted values. ([#27376](https://github.com/influxdata/influxdb/pull/27376)) -- **`SHOW MEASUREMENTS`**: Support partial results when some shards are - unavailable. ([#27443](https://github.com/influxdata/influxdb/pull/27443)) +- **[`SHOW MEASUREMENTS`](/influxdb/v1/query_language/explore-schema/#show-measurements)**: + Support partial results when some shards are unavailable. + ([#27443](https://github.com/influxdata/influxdb/pull/27443)) - **Operational visibility**: Failed and slow queries, per-user query and [write byte statistics](/influxdb/v1/administration/config/#user-write-bytes-enabled) (opt-in), the remote host and user in query logs, compaction planning diff --git a/content/influxdb/v1/administration/config.md b/content/influxdb/v1/administration/config.md index 36bf3826f2..785c238744 100644 --- a/content/influxdb/v1/administration/config.md +++ b/content/influxdb/v1/administration/config.md @@ -534,7 +534,7 @@ An increase in cache size may lead to an increase in heap usage. **Default**: `100` **Environment variable**: `INFLUXDB_DATA_SERIES_ID_SET_CACHE_SIZE` -#### series-id-set-cache-max-size +#### series-id-set-cache-max-size {metadata="v1.13.0+"} The upper bound, in number of entries, for adaptive growth of the [`series-id-set-cache-size`](#series-id-set-cache-size) cache. Set this together @@ -547,12 +547,14 @@ disables adaptive sizing. > both be set to enable adaptive sizing, or both left at `0` to disable it. > Setting only one prevents InfluxDB from starting. When adaptive sizing is > enabled, `series-id-set-cache-max-size` must be greater than -> `series-id-set-cache-size`. +> `series-id-set-cache-size`, and `series-id-set-cache-size` must be greater +> than `0`. A `series-id-set-cache-size` of `0` disables the cache entirely, +> which takes precedence over adaptive sizing. **Default**: `0` **Environment variable**: `INFLUXDB_DATA_SERIES_ID_SET_CACHE_MAX_SIZE` -#### series-id-set-cache-target-hit-rate +#### series-id-set-cache-target-hit-rate {metadata="v1.13.0+"} The cache hit rate, as a fraction between `0.0` and `1.0` (exclusive), that adaptive sizing tries to reach for the @@ -565,7 +567,7 @@ that hit rate can never be reached. **Default**: `0.0` **Environment variable**: `INFLUXDB_DATA_SERIES_ID_SET_CACHE_TARGET_HIT_RATE` -#### series-id-set-cache-shrink-conservatism +#### series-id-set-cache-shrink-conservatism {metadata="v1.13.0+"} How reluctant the adaptive shrink policy is to release memory from the [`series-id-set-cache-size`](#series-id-set-cache-size) cache, expressed in diff --git a/content/influxdb/v1/tools/influx-cli/use-influx-cli.md b/content/influxdb/v1/tools/influx-cli/use-influx-cli.md index 71167330d0..9ba014fbae 100644 --- a/content/influxdb/v1/tools/influx-cli/use-influx-cli.md +++ b/content/influxdb/v1/tools/influx-cli/use-influx-cli.md @@ -10,436 +10,8 @@ aliases: - /influxdb/v1/tools/shell/ related: - /influxdb/v1/administration/backup_and_restore/ +source: /shared/influxdb-v1/tools/influx-cli/use-influx-cli.md --- -The `influx` command line interface (CLI) provides an interactive shell for the HTTP API associated with `influxd`. -Use `influx` to write data (manually or from a file), query data interactively, view query output in different formats, and manage resources in InfluxDB. - -* [Launch `influx`](#launch-influx) -* [`influx` Arguments](#influx-arguments) -* [`influx` Commands](#influx-commands) - -## Launch `influx` - -The `influx` CLI is included when you [install InfluxDB OSS {{< current-version >}}](/influxdb/v1/introduction/install/). - -The `influx` CLI is installed at the following path, depending on your -system and package manager: - -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[Linux](#linux) -[macOS](#macos) -[Homebrew](#homebrew) -{{% /code-tabs %}} -{{% code-tab-content %}} -```bash -/usr/bin/influx -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```bash -/usr/local/bin/influx -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} -```bash -/opt/homebrew/opt/influxdb@1/bin/influx -``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -To access the CLI, first launch the `influxd` database process and then launch `influx` in your terminal. - -```bash -influx -``` - -If successfully connected to an InfluxDB node, the output is the following: - -```bash -Connected to http://localhost:8086 version {{< latest-patch >}} -InfluxDB shell version: {{< latest-patch >}} -> -``` - -_The versions of InfluxDB and the CLI should be identical. If not, parsing issues can occur with queries._ - -In the prompt, you can enter InfluxQL queries as well as CLI-specific commands. -Enter `help` to get a list of available commands. -Use `Ctrl+C` to cancel if you want to cancel a long-running InfluxQL query. - -## Environment Variables - -The following environment variables can be used to configure settings used by the `influx` client. They can be specified in lower or upper case, however the upper case version takes precedence. - -#### `HTTP_PROXY` -Defines the proxy server to use for HTTP. - -**Value format:**`[protocol://][:port]` - -``` -HTTP_PROXY=http://localhost:1234 -``` - -#### `HTTPS_PROXY` -Defines the proxy server to use for HTTPS. Takes precedence over HTTP_PROXY for HTTPS. - -**Value format:**`[protocol://][:port]` - -``` -HTTPS_PROXY=https://localhost:1443 -``` - -#### `NO_PROXY` -List of host names that should **not** go through any proxy. If set to an asterisk '\*' only, it matches all hosts. - -**Value format:** comma-separated list of hosts - -``` -NO_PROXY=123.45.67.89,123.45.67.90 -``` - -## `influx` Arguments - -Arguments specify connection, write, import, and output options for the CLI session. - -`influx` provides the following arguments: - -`-h`, `-help` -List `influx` arguments - -`-compressed` -Set to true if the import file is compressed. -Use with `-import`. - -`-consistency 'any|one|quorum|all'` -Set the write consistency level. - -`-database 'database name'` -The database to which `influx` connects. - -`-execute 'command'` -Execute an [InfluxQL](/influxdb/v1/query_language/explore-data/) command and quit. -See [-execute](/influxdb/v1/tools/shell/#execute-an-influxql-command-and-quit-with-execute). - -`-format 'json|csv|column'` -Specifies the format of the server responses. -See [-format](/influxdb/v1/tools/shell/#specify-the-format-of-the-server-responses-with-format). - -`-host 'host name'` -The host to which `influx` connects. -By default, InfluxDB runs on localhost. - -`-import` -Import new data or [exported data](/enterprise_influxdb/v1/administration/backup-and-restore/#exporting-data) from a file. -See [-import](#import-data-from-a-file). - -`-password 'password'` -The password `influx` uses to connect to the server. -`influx` will prompt for a password if you leave it blank (`-password ''`). -Alternatively, set the password for the CLI with the `INFLUX_PASSWORD` environment -variable. - -`-path` -The path to the file to import. -Use with[-import](#import-data-from-a-file). - -`-port 'port #'` -The port to which `influx` connects. -By default, InfluxDB runs on port `8086`. - -`-pps` -How many points per second the import will allow. -By default, pps is zero and influx will not throttle importing. -Use with `-import`. - -`-precision 'rfc3339|h|m|s|ms|u|ns'` -Specifies the format/precision of the timestamp: `rfc3339` (`YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ`), `h` (hours), `m` (minutes), `s` (seconds), `ms` (milliseconds), `u` (microseconds), `ns` (nanoseconds). -Precision defaults to nanoseconds. - -> **Note:** Setting the precision to `rfc3339` (`-precision rfc3339`) works with the `-execute` option, but it does not work with the `-import option`. All other precision formats (e.g., `h`,`m`,`s`,`ms`,`u`, and `ns`) work with the `-execute` and `-import` options. - -`-pretty` -Turns on pretty print for the `json` format. - -`-ssl` -Use HTTPS for requests. - -`-unsafeSsl` -Disables SSL certificate verification. -Use when connecting over HTTPS with a self-signed certificate. - -`-username 'username'` -The username that `influx` uses to connect to the server. -Alternatively, set the username for the CLI with the `INFLUX_USERNAME` environment variable. - -`-version` -Display the InfluxDB version and exit. - -The following sections provide detailed examples for some arguments, including `-execute`, `-format`, and `-import`. - -- [Execute an InfluxQL command and quit with `-execute`](#execute-an-influxql-command-and-quit-with--execute) -- [Specify the format of the server responses with `-format`](#specify-the-format-of-the-server-responses-with--format) -- [Import data from a file](#import-data-from-a-file) - -### Execute an InfluxQL command and quit with `-execute` - -Execute queries that don't require a database specification: - -```bash -$ influx -execute 'SHOW DATABASES' -name: databases ---------------- -name -NOAA_water_database -_internal -telegraf -pirates -``` - -Execute queries that do require a database specification, and change the timestamp precision: - -```bash -$ influx -execute 'SELECT * FROM "h2o_feet" LIMIT 3' -database="NOAA_water_database" -precision=rfc3339 -name: h2o_feet --------------- -time level description location water_level -2015-08-18T00:00:00Z below 3 feet santa_monica 2.064 -2015-08-18T00:00:00Z between 6 and 9 feet coyote_creek 8.12 -2015-08-18T00:06:00Z between 6 and 9 feet coyote_creek 8.005 -``` - -### Specify the format of the server responses with `-format` - -The default format is `column`: - -```bash -$ influx -format=column -[...] -> SHOW DATABASES -name: databases ---------------- -name -NOAA_water_database -_internal -telegraf -pirates -``` - -Change the format to `csv`: - -```bash -$ influx -format=csv -[...] -> SHOW DATABASES -name,name -databases,NOAA_water_database -databases,_internal -databases,telegraf -databases,pirates -``` - -Change the format to `json`: - -```bash -$ influx -format=json -[...] -> SHOW DATABASES -{"results":[{"series":[{"name":"databases","columns":["name"],"values":[["NOAA_water_database"],["_internal"],["telegraf"],["pirates"]]}]}]} -``` - -Change the format to `json` and turn on pretty print: - -```bash -$ influx -format=json -pretty -[...] -> SHOW DATABASES -{ - "results": [ - { - "series": [ - { - "name": "databases", - "columns": [ - "name" - ], - "values": [ - [ - "NOAA_water_database" - ], - [ - "_internal" - ], - [ - "telegraf" - ], - [ - "pirates" - ] - ] - } - ] - } - ] -} -``` - -### Import data from a file - -An import file has two sections: - -- _Optional_: **DDL (Data Definition Language)**: Contains the [InfluxQL commands](/influxdb/v1/query_language/manage-database/) for creating the relevant [database](/influxdb/v1/concepts/glossary/) and managing the [retention policy](/influxdb/v1/concepts/glossary/#retention-policy-rp). -If your database and retention policy already exist, your file can skip this section. -- **DML (Data Manipulation Language)**: Context metadata that specifies the database and (if desired) retention policy for the import and contains the data in [line protocol](/influxdb/v1/concepts/glossary/#influxdb-line-protocol). - -Example: - -File (`datarrr.txt`): -``` -# DDL -CREATE DATABASE pirates -CREATE RETENTION POLICY oneday ON pirates DURATION 1d REPLICATION 1 - -# DML -# CONTEXT-DATABASE: pirates -# CONTEXT-RETENTION-POLICY: oneday - -treasures,captain_id=dread_pirate_roberts value=801 1439856000 -treasures,captain_id=flint value=29 1439856000 -treasures,captain_id=sparrow value=38 1439856000 -treasures,captain_id=tetra value=47 1439856000 -treasures,captain_id=crunch value=109 1439858880 -``` - -Command: -``` -$influx -import -path=datarrr.txt -precision=s -``` - -Results: -``` -2015/12/22 12:25:06 Processed 2 commands -2015/12/22 12:25:06 Processed 5 inserts -2015/12/22 12:25:06 Failed 0 inserts -``` -> [!Note] -> For large datasets, `influx` writes out a status message every 100,000 points. -> -> For example: -> -> ```sh -> 2015/08/21 14:48:01 Processed 3100000 lines. -> Time elapsed: 56.740578415s. -> Points per second (PPS): 54634 -> ``` - -Things to note about `-import`: - -- To throttle the import, use `-pps` to set the number of points per second to ingest. By default, pps is zero and `influx` does not throttle importing. -- To import a file compressed with `gzip` (GNU zip), include the -compressed flag. -- Include timestamps in the data file. - If points don’t include a timestamp, InfluxDB assigns the same timestamp to those points, which can result in unintended [duplicate points or overwrites](/influxdb/v1/troubleshooting/frequently-asked-questions/#how-does-influxdb-handle-duplicate-points). -- If your data file contains more than 5,000 points, consider splitting it into smaller files to write data to InfluxDB in batches. - We recommend writing points in batches of 5,000 to 10,000 for optimal performance. - Writing smaller batches increases the number of HTTP requests, which can negatively impact performance. - By default, the HTTP request times out after five seconds. Although InfluxDB continues attempting to write the points after a timeout, you won’t receive confirmation of a successful write. - -> **Note:** To export data from InfluxDB version 0.8.9, see [Exporting from 0.8.9](https://github.com/influxdb/influxdb/blob/1.8/importer/README.md). - -For more information, see [exporting and importing data](/influxdb/v1/administration/backup_and_restore/#exporting-and-importing-data). - -## `influx` commands - -Enter `help` in the CLI for a partial list of the available commands. - -### Commands - -The list below offers a brief discussion of each command. -We provide detailed information on `insert` at the end of this section. - -`auth` -Prompts you for your username and password. -`influx` uses those credentials when querying a database. -Alternatively, set the username and password for the CLI with the -`INFLUX_USERNAME` and `INFLUX_PASSWORD` environment variables. - -`chunked` -Turns on chunked responses from the server when issuing queries. -This setting is enabled by default. - -`chunk size ` -Sets the size of the chunked responses. -The default size is `10,000`. -Setting it to `0` resets `chunk size` to its default value. - -`clear [ database | db | retention policy | rp ]` -Clears the current context for the [database](/influxdb/v1/concepts/glossary/#database) or [retention policy](/influxdb/v1/concepts/glossary/#retention-policy-rp). - -`connect ` -Connect to a different server without exiting the shell. -By default, `influx` connects to `localhost:8086`. -If you do not specify either the host or the port, `influx` assumes the default setting for the missing attribute. - -`consistency ` -Sets the write consistency level: `any`, `one`, `quorum`, or `all`. - -`Ctrl+C` -Terminates the currently running query. Useful when an interactive query is taking too long to respond -because it is trying to return too much data. - -`exit` `quit` `Ctrl+D` -Quits the `influx` shell. - -`format ` -Specifies the format of the server responses: `json`, `csv`, or `column`. -See the description of [-format](/influxdb/v1/tools/shell/#specify-the-format-of-the-server-responses-with-format) for examples of each format. - -`history` -Displays your command history. -To use the history while in the shell, simply use the "up" arrow. -`influx` stores your last 1,000 commands in your home directory in `.influx_history`. - -`insert` -Write data using line protocol. -See [insert](/influxdb/v1/tools/shell/#write-data-to-influxdb-with-insert). - -`precision ` -Specifies the format/precision of the timestamp: `rfc3339` (`YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ`), `h` (hours), `m` (minutes), `s` (seconds), `ms` (milliseconds), `u` (microseconds), `ns` (nanoseconds). -Precision defaults to nanoseconds. - -`pretty` -Turns on pretty print for the `json` format. - -`settings` -Outputs the current settings for the shell including the `Host`, `Username`, `Database`, `Retention Policy`, `Pretty` status, `Chunked` status, `Chunk Size`, `Format`, and `Write Consistency`. - -`use [ "" | ""."" ]` -Sets the current [database](/influxdb/v1/concepts/glossary/#database) and/or [retention policy](/influxdb/v1/concepts/glossary/#retention-policy-rp). -Once `influx` sets the current database and/or retention policy, there is no need to specify that database and/or retention policy in queries. -If you do not specify the retention policy, `influx` automatically queries the `use`d database's `DEFAULT` retention policy. - -#### Write data to InfluxDB with `insert` - -Enter `insert` followed by the data in [line protocol](/influxdb/v1/concepts/glossary/#influxdb-line-protocol) to write data to InfluxDB. -Use `insert into ` to write data to a specific [retention policy](/influxdb/v1/concepts/glossary/#retention-policy-rp). - -Write data to a single field in the measurement `treasures` with the tag `captain_id = pirate_king`. -`influx` automatically writes the point to the database's `DEFAULT` retention policy. -``` -INSERT treasures,captain_id=pirate_king value=2 - -``` - -Write the same point to the already-existing retention policy `oneday`: -``` -> INSERT INTO oneday treasures,captain_id=pirate_king value=2 -Using retention policy oneday -> -``` - -### Queries - -Execute all InfluxQL queries in `influx`. - -See [Data exploration](/influxdb/v1/query_language/explore-data/), [Schema exploration](/influxdb/v1/query_language/explore-schema/), [Database management](/influxdb/v1/query_language/manage-database/), [Authentication and authorization](/influxdb/v1/administration/authentication_and_authorization/) for InfluxQL documentation. + diff --git a/content/shared/influxdb-v1/tools/influx-cli/use-influx-cli.md b/content/shared/influxdb-v1/tools/influx-cli/use-influx-cli.md new file mode 100644 index 0000000000..478ef6576b --- /dev/null +++ b/content/shared/influxdb-v1/tools/influx-cli/use-influx-cli.md @@ -0,0 +1,484 @@ +The `influx` command line interface (CLI) provides an interactive shell for the HTTP API associated with `influxd`. +Use `influx` to write data (manually or from a file), query data interactively, view query output in different formats, and manage resources in InfluxDB. + +* [Launch `influx`](#launch-influx) +* [`influx` arguments](#influx-arguments) +* [`influx` commands](#influx-commands) + +## Launch `influx` + +{{% show-in "influxdb/v1" %}} +The `influx` CLI is included when you [install InfluxDB OSS {{< current-version >}}](/product/version/introduction/install/). + +The `influx` CLI is installed at the following path, depending on your +system and package manager: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Linux](#linux) +[macOS](#macos) +[Homebrew](#homebrew) +{{% /code-tabs %}} +{{% code-tab-content %}} +```bash +/usr/bin/influx +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```bash +/usr/local/bin/influx +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```bash +/opt/homebrew/opt/influxdb@1/bin/influx +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} +{{% /show-in %}} +{{% show-in "enterprise_influxdb/v1" %}} +The `influx` CLI is included when you [install InfluxDB Enterprise](/product/version/introduction/installation/). + +If you [install](https://influxdata.com/downloads/) InfluxDB via a package manager, the CLI is installed at `/usr/bin/influx` (on macOS). +{{% /show-in %}} + +To access the CLI, first launch the `influxd` database process and then launch `influx` in your terminal. + +```bash +influx +``` + +If successfully connected to an InfluxDB node, the output is the following: + +```bash +Connected to http://localhost:8086 version {{< latest-patch >}} +InfluxDB shell version: {{< latest-patch >}} +> +``` + +_The versions of InfluxDB and the CLI should be identical. If not, parsing issues can occur with queries._ + +In the prompt, you can enter InfluxQL queries as well as CLI-specific commands. +Enter `help` to get a list of available commands. +Use `Ctrl+C` to cancel if you want to cancel a long-running InfluxQL query. + +## Environment variables + +The following environment variables can be used to configure settings used by the `influx` client. They can be specified in lower or upper case, however the upper case version takes precedence. + +#### `HTTP_PROXY` +Defines the proxy server to use for HTTP. + +**Value format:**`[protocol://][:port]` + +``` +HTTP_PROXY=http://localhost:1234 +``` + +#### `HTTPS_PROXY` +Defines the proxy server to use for HTTPS. Takes precedence over HTTP_PROXY for HTTPS. + +**Value format:**`[protocol://][:port]` + +``` +HTTPS_PROXY=https://localhost:1443 +``` + +#### `NO_PROXY` +List of host names that should **not** go through any proxy. If set to an asterisk '\*' only, it matches all hosts. + +**Value format:** comma-separated list of hosts + +``` +NO_PROXY=123.45.67.89,123.45.67.90 +``` + +## `influx` arguments + +Arguments specify connection, write, import, and output options for the CLI session. + +`influx` provides the following arguments: + +`-h`, `-help` +List `influx` arguments + +{{% show-in "enterprise_influxdb/v1" %}} +`-cert 'path'` _(v1.13.0+)_ +Path to the client certificate file (PEM) presented for mutual TLS (mTLS). +Alternatively, set the certificate with the `INFLUX_CERT` environment variable. +{{% /show-in %}} + +`-compressed` +Set to true if the import file is compressed. +Use with `-import`. + +`-consistency 'any|one|quorum|all'` +Set the write consistency level. + +`-database 'database name'` +The database to which `influx` connects. + +`-execute 'command'` +Execute an [InfluxQL](/product/version/query_language/explore-data/) command and quit. +See [-execute](#execute-an-influxql-command-and-quit-with--execute). + +`-format 'json|csv|column'` +Specifies the format of the server responses. +See [-format](#specify-the-format-of-the-server-responses-with--format). + +`-host 'host name'` +The host to which `influx` connects. +By default, InfluxDB runs on localhost. + +{{% show-in "enterprise_influxdb/v1" %}} +`-ignore-cert-sanity-checks` _(v1.13.0+)_ +Load the client certificate even if it fails client-authentication sanity checks. +Alternatively, set this with the `INFLUX_IGNORE_CERT_SANITY_CHECKS` environment variable. +{{% /show-in %}} + +`-import` +{{% show-in "influxdb/v1" %}} +Import new data or [exported data](/product/version/administration/backup_and_restore/#exporting-data) from a file. +{{% /show-in %}} +{{% show-in "enterprise_influxdb/v1" %}} +Import new data or [exported data](/product/version/administration/backup-and-restore/#exporting-data) from a file. +{{% /show-in %}} +See [-import](#import-data-from-a-file). + +{{% show-in "enterprise_influxdb/v1" %}} +`-insecure-certificate` _(v1.13.0+)_ +Ignore file permission checks when loading the client certificate and key. +Alternatively, set this with the `INFLUX_INSECURE_CERTIFICATE` environment variable. + +`-key 'path'` _(v1.13.0+)_ +Path to the client private key file (PEM) for mutual TLS (mTLS). +Alternatively, set the key with the `INFLUX_KEY` environment variable. +{{% /show-in %}} + +`-password 'password'` +The password `influx` uses to connect to the server. +`influx` will prompt for a password if you leave it blank (`-password ''`). +Alternatively, set the password for the CLI with the `INFLUX_PASSWORD` environment +variable. + +`-path` +The path to the file to import. +Use with [-import](#import-data-from-a-file). + +`-port 'port #'` +The port to which `influx` connects. +By default, InfluxDB runs on port `8086`. + +`-pps` +How many points per second the import will allow. +By default, pps is zero and influx will not throttle importing. +Use with `-import`. + +`-precision 'rfc3339|h|m|s|ms|u|ns'` +Specifies the format/precision of the timestamp: `rfc3339` (`YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ`), `h` (hours), `m` (minutes), `s` (seconds), `ms` (milliseconds), `u` (microseconds), `ns` (nanoseconds). +Precision defaults to nanoseconds. + +> [!Note] +> Setting the precision to `rfc3339` (`-precision rfc3339`) works with the `-execute` option, but it does not work with the `-import option`. All other precision formats (e.g., `h`,`m`,`s`,`ms`,`u`, and `ns`) work with the `-execute` and `-import` options. + +`-pretty` +Turns on pretty print for the `json` format. + +{{% show-in "enterprise_influxdb/v1" %}} +`-root-ca 'path'` _(v1.13.0+)_ +Path to the CA bundle (PEM) used to verify the server certificate. +Alternatively, set the CA bundle with the `INFLUX_ROOT_CA` environment variable. +{{% /show-in %}} + +`-ssl` +Use HTTPS for requests. + +`-unsafeSsl` +Disables SSL certificate verification. +Use when connecting over HTTPS with a self-signed certificate. + +`-username 'username'` +The username that `influx` uses to connect to the server. +Alternatively, set the username for the CLI with the `INFLUX_USERNAME` environment variable. + +`-version` +Display the InfluxDB version and exit. + +The following sections provide detailed examples for some arguments, including `-execute`, `-format`, and `-import`. + +- [Execute an InfluxQL command and quit with `-execute`](#execute-an-influxql-command-and-quit-with--execute) +- [Specify the format of the server responses with `-format`](#specify-the-format-of-the-server-responses-with--format) +- [Import data from a file](#import-data-from-a-file) + +### Execute an InfluxQL command and quit with `-execute` + +Execute queries that don't require a database specification: + +```bash +$ influx -execute 'SHOW DATABASES' +name: databases +--------------- +name +NOAA_water_database +_internal +telegraf +pirates +``` + +Execute queries that do require a database specification, and change the timestamp precision: + +```bash +$ influx -execute 'SELECT * FROM "h2o_feet" LIMIT 3' -database="NOAA_water_database" -precision=rfc3339 +name: h2o_feet +-------------- +time level description location water_level +2015-08-18T00:00:00Z below 3 feet santa_monica 2.064 +2015-08-18T00:00:00Z between 6 and 9 feet coyote_creek 8.12 +2015-08-18T00:06:00Z between 6 and 9 feet coyote_creek 8.005 +``` + +### Specify the format of the server responses with `-format` + +The default format is `column`: + +```bash +$ influx -format=column +[...] +> SHOW DATABASES +name: databases +--------------- +name +NOAA_water_database +_internal +telegraf +pirates +``` + +Change the format to `csv`: + +```bash +$ influx -format=csv +[...] +> SHOW DATABASES +name,name +databases,NOAA_water_database +databases,_internal +databases,telegraf +databases,pirates +``` + +Change the format to `json`: + +```bash +$ influx -format=json +[...] +> SHOW DATABASES +{"results":[{"series":[{"name":"databases","columns":["name"],"values":[["NOAA_water_database"],["_internal"],["telegraf"],["pirates"]]}]}]} +``` + +Change the format to `json` and turn on pretty print: + +```bash +$ influx -format=json -pretty +[...] +> SHOW DATABASES +{ + "results": [ + { + "series": [ + { + "name": "databases", + "columns": [ + "name" + ], + "values": [ + [ + "NOAA_water_database" + ], + [ + "_internal" + ], + [ + "telegraf" + ], + [ + "pirates" + ] + ] + } + ] + } + ] +} +``` + +### Import data from a file + +An import file has two sections: + +- _Optional_: **DDL (Data Definition Language)**: Contains the [InfluxQL commands](/product/version/query_language/manage-database/) for creating the relevant [database](/product/version/concepts/glossary/) and managing the [retention policy](/product/version/concepts/glossary/#retention-policy-rp). +If your database and retention policy already exist, your file can skip this section. +- **DML (Data Manipulation Language)**: Context metadata that specifies the database and (if desired) retention policy for the import and contains the data in [line protocol](/product/version/concepts/glossary/#influxdb-line-protocol). + +#### Example: import data from a file + +The following `datarrr.txt` file is output using the [`influx_inspect export` command](/product/version/tools/influx_inspect/#export): + +```text +# DDL +CREATE DATABASE pirates +CREATE RETENTION POLICY oneday ON pirates DURATION 1d REPLICATION 1 + +# DML +# CONTEXT-DATABASE: pirates +# CONTEXT-RETENTION-POLICY: oneday + +treasures,captain_id=dread_pirate_roberts value=801 1439856000 +treasures,captain_id=flint value=29 1439856000 +treasures,captain_id=sparrow value=38 1439856000 +treasures,captain_id=tetra value=47 1439856000 +treasures,captain_id=crunch value=109 1439858880 +``` + +To import the file, enter the following command in your terminal: + +```bash +influx -import -path=datarrr.txt -precision=s +``` + +The data is imported into the database and retention policy specified in the `# DML` +context metadata. +The output is the following: + +```text +2015/12/22 12:25:06 Processed 2 commands +2015/12/22 12:25:06 Processed 5 inserts +2015/12/22 12:25:06 Failed 0 inserts +``` + +> [!Note] +> For large datasets, `influx` writes out a status message every 100,000 points. +> +> For example: +> +> ```sh +> 2015/08/21 14:48:01 Processed 3100000 lines. +> Time elapsed: 56.740578415s. +> Points per second (PPS): 54634 +> ``` + +Keep the following in mind when using `-import`: + +- To throttle the import, use `-pps` to set the number of points per second to ingest. By default, pps is zero and `influx` does not throttle importing. +- To import a file compressed with `gzip` (GNU zip), include the -compressed flag. +- Include timestamps in the data file. + If points don’t include a timestamp, InfluxDB assigns the same timestamp to those points, which can result in unintended [duplicate points or overwrites](/product/version/troubleshooting/frequently-asked-questions/#how-does-influxdb-handle-duplicate-points). +- If your data file contains more than 5,000 points, consider splitting it into smaller files to write data to InfluxDB in batches. + We recommend writing points in batches of 5,000 to 10,000 for optimal performance. + Writing smaller batches increases the number of HTTP requests, which can negatively impact performance. + By default, the HTTP request times out after five seconds. Although InfluxDB continues attempting to write the points after a timeout, you won’t receive confirmation of a successful write. + +> [!Note] +> To export data from InfluxDB version 0.8.9, see [Exporting from 0.8.9](https://github.com/influxdb/influxdb/blob/1.8/importer/README.md). + +{{% show-in "influxdb/v1" %}} +For more information, see [exporting and importing data](/product/version/administration/backup_and_restore/#exporting-and-importing-data). +{{% /show-in %}} +{{% show-in "enterprise_influxdb/v1" %}} +For more information, see [exporting and importing data](/product/version/administration/backup-and-restore/#exporting-and-importing-data). +{{% /show-in %}} + +## `influx` commands + +Enter `help` in the CLI for a partial list of the available commands. + +### Commands + +The list below offers a brief discussion of each command. +We provide detailed information on `insert` at the end of this section. + +`auth` +Prompts you for your username and password. +`influx` uses those credentials when querying a database. +Alternatively, set the username and password for the CLI with the +`INFLUX_USERNAME` and `INFLUX_PASSWORD` environment variables. + +`chunked` +Turns on chunked responses from the server when issuing queries. +This setting is enabled by default. + +`chunk size ` +Sets the size of the chunked responses. +The default size is `10,000`. +Setting it to `0` resets `chunk size` to its default value. + +`clear [ database | db | retention policy | rp ]` +Clears the current context for the [database](/product/version/concepts/glossary/#database) or [retention policy](/product/version/concepts/glossary/#retention-policy-rp). + +`connect ` +Connect to a different server without exiting the shell. +By default, `influx` connects to `localhost:8086`. +If you do not specify either the host or the port, `influx` assumes the default setting for the missing attribute. + +`consistency ` +Sets the write consistency level: `any`, `one`, `quorum`, or `all`. + +`Ctrl+C` +Terminates the currently running query. Useful when an interactive query is taking too long to respond +because it is trying to return too much data. + +`exit` `quit` `Ctrl+D` +Quits the `influx` shell. + +`format ` +Specifies the format of the server responses: `json`, `csv`, or `column`. +See the description of [-format](#specify-the-format-of-the-server-responses-with--format) for examples of each format. + +`history` +Displays your command history. +To use the history while in the shell, simply use the "up" arrow. +`influx` stores your last 1,000 commands in your home directory in `.influx_history`. + +`insert` +Write data using line protocol. +See [insert](#write-data-to-influxdb-with-insert). + +`precision ` +Specifies the format/precision of the timestamp: `rfc3339` (`YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ`), `h` (hours), `m` (minutes), `s` (seconds), `ms` (milliseconds), `u` (microseconds), `ns` (nanoseconds). +Precision defaults to nanoseconds. + +`pretty` +Turns on pretty print for the `json` format. + +`settings` +Outputs the current settings for the shell including the `Host`, `Username`, `Database`, `Retention Policy`, `Pretty` status, `Chunked` status, `Chunk Size`, `Format`, and `Write Consistency`. + +`use [ "" | ""."" ]` +Sets the current [database](/product/version/concepts/glossary/#database) and/or [retention policy](/product/version/concepts/glossary/#retention-policy-rp). +Once `influx` sets the current database and/or retention policy, there is no need to specify that database and/or retention policy in queries. +If you do not specify the retention policy, `influx` automatically queries the `use`d database's `DEFAULT` retention policy. + +#### Write data to InfluxDB with `insert` + +Enter `insert` followed by the data in [line protocol](/product/version/concepts/glossary/#influxdb-line-protocol) to write data to InfluxDB. +Use `insert into ` to write data to a specific [retention policy](/product/version/concepts/glossary/#retention-policy-rp). + +Write data to a single field in the measurement `treasures` with the tag `captain_id = pirate_king`. +`influx` automatically writes the point to the database's `DEFAULT` retention policy. +``` +INSERT treasures,captain_id=pirate_king value=2 + +``` + +Write the same point to the already-existing retention policy `oneday`: +``` +> INSERT INTO oneday treasures,captain_id=pirate_king value=2 +Using retention policy oneday +> +``` + +### Queries + +Execute all InfluxQL queries in `influx`. + +See [Data exploration](/product/version/query_language/explore-data/), [Schema exploration](/product/version/query_language/explore-schema/), [Database management](/product/version/query_language/manage-database/), [Authentication and authorization](/product/version/administration/authentication_and_authorization/) for InfluxQL documentation.