All Products
Search
Document Center

CLI of TSDB for InfluxDB®

Last Updated: Jul 19, 2022

The influx CLI of TSDB for InfluxDB® provides an interactive shell for the HTTP API. You can use the influx CLI to manually write data or import data from files, query data in an interactive manner, and view query results in different formats.

Download the CLI

Download the binary package of the CLI that is specific to your OS by clicking one of the following links:

Decompress your binary package, and go to the folder that is extracted from the binary package. You can find the influx CLI. On Windows, the file name is influx.exe.

Start influx

Start influx in the cmd terminal. After your TSDB for InfluxDB® instance is connected, you can view the following output:

$ ./influx -ssl -username "myname" -password "mypassword" -host ts-xxxxxx.influxdata.rds.aliyuncs.com -port 3242
Connected to https://<Endpoint>:3242 version 1.8.x
InfluxDB shell version: 1.8.x

TSDB for InfluxDB® uses the SSL protocol to ensure security during data transmission. Each time you connect to a TSDB for InfluxDB® instance, you must set the five parameters: -ssl, -username, -password, -host, and -port.

Parameter description

  • -ssl: specifies that a TSDB for InfluxDB® server is connected over HTTPS.

  • -username: specifies the username that is used to log on to your TSDB for InfluxDB® instance.

  • -password: specifies the password that is used to log on to your TSDB for InfluxDB® instance.

  • -host: specifies the endpoint of your TSDB for InfluxDB® instance. You must replace ts-xxxxxx with the ID of your TSDB for InfluxDB® instance.

  • -port: specifies the network port. If the TSDB for InfluxDB® instance is connected over a virtual private cloud (VPC), set this parameter to 8086. If the TSDB for InfluxDB® instance is connected over the Internet, set this parameter to 3242.

After the influx CLI is started, you can execute InfluxQL statements and run CLI commands in your terminal. If you want to execute Flux statements, you must set the -type parameter to flux. You can run the help command to obtain available commands. If you want to terminate a long-running InfluxQL query, press Ctrl+C on your keyboard.

Environment variables

You can configure the following environment variables for your influx client. You can specify environment variables in lowercase or uppercase characters. Variables in uppercase characters are preferred.

HTTP_PROXY

Specifies the proxy server that is used for HTTP.

Format: [protocol://][:port]

HTTP_PROXY=http://localhost:1234

HTTPS_PROXY

Specifies the proxy server that is used for HTTPS. If both HTTP_PROXY and HTTPS_PROXY are specified, HTTPS_PROXY takes precedence.

Format: [protocol://][:port]

HTTPS_PROXY=https://localhost:1443

NO_PROXY

Specifies the hosts that do not use proxies. If you set this variable to an asterisk (*), all hosts do not use proxies.

Format: a list of comma-separated hosts

NO_PROXY=123.45.67.89,123.45.67.90

influx flags

When you start influx, you can pass flags to influx. You can run the $ influx --help command to query all available flags. This section provides a brief description for each flag that is supported by influx, and describes how to use the -execute, -format, and -import flags in details.

-compressed

If the import file is compressed, set this flag to true. The -compressed flag must be used in conjunction with the -import flag.

Specifies a write consistency level.

-database 'database name'

Specifies the database to which the influx CLI connects.

-execute '<command>'

Runs an InfluxQL command and quits.

-format 'jsoncsvcolumn'

Specifies the format of server responses.

-host '<hostname>'

Specifies the host to which the influx CLI connects.

-import

Imports new data from a file, or imports previously exported database data from a file.

-password '<password>'

Specifies the password that the influx CLI uses to connect to the server. If you do not specify the -password flag, influx prompts you to enter your password. You can also use the INFLUX_PASSWORD environment variable to specify a password for the CLI.

-path

Specifies the path of the file to be imported. The -path flag must be used in conjunction with the -import flag.

-port 'port #'

Specifies the port to which the influx CLI connects. By default, TSDB for InfluxDB® uses port 3242.

-pps

Specifies the number of data points that can be imported per second. By default, the -pps flag is set to 0 and influx does not limit the speed of importing data. The -pps flag must be used in conjunction with the -import flag.

-precision 'rfc3339hmsmsuns'
Specifies the format and precision of timestamps for data queries and writes: rfc3339 (YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ), h (hour), m (minute), s (second), ms (millisecond), u (microsecond), and ns (nanosecond). The default precision is ns.
-pretty

Enables pretty output print for JSON-formatted data to improve readability.

-ssl

Uses HTTPS for requests.

-type

Specifies the interactive shell that you want to use. The default value is influxql. If you want to use the Flux Read-Eval-Print Loop (REPL) shell, set the -type flag to flux.

-username 'username'

Specifies the username that the influx CLI uses to connect to the server. You can also use the INFLUX_USERNAME environment variable to specify a username for the CLI.

-version

Displays the version of TSDB for InfluxDB® and exits.

Run an InfluxQL command and quit by using -execute

If you want to query data from all available databases, run the following query:

$ influx -ssl -username <Username> -password <Password> -host <Endpoint> -port 3242 -execute 'SHOW DATABASES'
name: databases
---------------
name
NOAA_water_database
_internal
telegraf
pirates

If you want to query data from a specified database and change the precision of timestamps at the same time, run the following query:

$ influx -ssl -username <Username> -password <Password> -host <Endpoint> -port 3242 -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 server responses by using -format

The default format is column.

$ influx -ssl -username <Username> -password <Password> -host <Endpoint> -port 3242 -format=column
[...]
> SHOW DATABASES
name: databases
---------------
name
NOAA_water_database
_internal
telegraf
pirates

Change the format to csv.

$ influx -ssl -username <Username> -password <Password> -host <Endpoint> -port 3242 -format=csv
[...]
> SHOW DATABASES
name,name
databases,NOAA_water_database
databases,_internal
databases,telegraf
databases,pirates

Change the format to json.

$ influx -ssl -username <Username> -password <Password> -host <Endpoint> -port 3242 -format=json
[...]
> SHOW DATABASES
{"results":[{"series":[{"name":"databases","columns":["name"],"values":[["NOAA_water_database"],["_internal"],["telegraf"],["pirates"]]}]}]}

Change the format to json format and enable pretty output print.

$ influx -ssl -username <Username> -password <Password> -host <Endpoint> -port 3242 -format=json -pretty
[...]
> SHOW DATABASES
{
    "results": [  
        {
            "series": [
                {
                    "name": "databases",
                    "columns": [
                        "name"
                    ],
                    "values": [
                        [
                            "NOAA_water_database"                       
                        ],
                        [
                            "_internal"
                        ],
                        [
                            "telegraf"
                        ],
                        [
                            "pirates"
                        ]
                    ]
                }
            ]
        }
    ]
}

Import data from a file by using -import

The import file consists of two parts:

Example:

Suppose that a database named pirates and a retention policy named oneday are created.

File datarrr.txt:

# 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 -ssl -username <Username> -password <Password> -host <Endpoint> -port 3242 -import -path=datarrr.txt -precision=s

Results:

2015/12/22 12:25:06 Processed 0 commands
2015/12/22 12:25:06 Processed 5 inserts
2015/12/22 12:25:06 Failed 0 inserts
Description

Before you use -import, take note of the following items:

  • -pps

    You can use the -pps flag to specify the number of data points that can be imported per second. This setting is applied when data points are written to the database. By default, the -pps flag is set to 0.

    influx

    does not limit the speed of importing data.

  • You can import data from .gz files by including the following flag:

    -compressed

    .

  • You must provide timestamps for data points in files. Otherwise, TSDB for InfluxDB® assigns the same timestamp to data points that do not have timestamps. This may cause unexpected data overwriting.

  • If your data file contains more than 5,000 data points, you may need to split the data file into multiple smaller files. This allows you to write data to TSDB for InfluxDB® in batches. We recommend that you include 5,000 or 10,000 data points in each batch. If you include a smaller number of data points in each batch, a larger number of HTTP requests must be sent. This compromises the performance. By default, the timeout period for each HTTP request is five seconds. TSDB for InfluxDB® attempts to write data points after a request timeout, but the points may fail to be written.

influx commands

Run the help command in the influx CLI to obtain a partial list of available commands.

Commands

This section provides a brief description for each available command, and describes how to use the insert command in details.

auth

Prompts you to enter your username and password. The influx CLI requires the authentication information when you send requests to databases. You can also use the INFLUX_USERNAME environment variable to specify a username and use the INFLUX_PASSWORD environment variable to specify a password for the CLI.

chunked

Enables chunked responses from the server when you send a query request. By default, chunked responses are enabled.

chunk size <size>

Specifies the size for each chunk of the responses. The default chunk size is 10,000. You can reset the chunk size to the default value by setting the size parameter to 0.

clear [ database  db  retention policy  rp ]

Clears the context for the database or the retention policy.

connect <host:port>

Connects to another server without exiting from the shell. By default, the influx CLI connects to localhost:8086. If you do not specify the host or port parameter, the influx CLI uses the default settings for the parameter that you leave blank.

consistency <level>

Specifies a write consistency level. The valid values are any, one, quorum, and all.

Ctrl+C

Terminates a running query. This command is useful if you want to terminate long-running interactive queries in which the system takes too long to respond because it attempts to return large amounts of data.

exit quit Ctrl+D

Exits the influx shell.

format <format>

Specifies the format of server responses. The valid values are json, csv, and column.

history

Displays command history. To run the historical command in the shell, use the up arrow. The influx CLI stores your latest 1,000 commands in the .influx_history file that is located in your home directory.

insert

Writes data by using the line protocol.

precision <format>

Specifies the format and precision of timestamps for data queries and writes: rfc3339 (YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ ), h (hour), m (minute), s (second), ms (millisecond), u (microsecond), and ns (nanosecond). The default precision is ns.

pretty

Enables pretty output print for JSON-formatted data to improve readability.

settings

Returns the current settings of the shell, including the settings of Host, Username, Database, Retention Policy, Pretty, Chunked, Chunk Size, Format, and Write Consistency.

use [ "<database_name>"  "<database_name>"."<retention policy_name>" ]

Specifies the current database and/or retention policy. If the current database and/or the retention policy are specified in the influx CLI, you do not need to specify the database and/or the retention policy in queries. If you do not specify a retention policy, the influx CLI queries data from the database based on the default (DEFAULT) retention policy.

Write data to TSDB for InfluxDB® by running the insert command.

To write data to TSDB for InfluxDB®, enter insert, and then enter the data that uses the line protocol. You can run the insert into <retention policy> <line protocol> command to write data based on the specified retention policy.

In the following example, data is written to a single field in the treasures measurement that has the captain_id = pirate_king tag. The influx CLI writes data to the database based on the default (DEFAULT) retention policy.

> INSERT treasures,captain_id=pirate_king value=2
>

In the following example, the same data point that is used in the preceding example is written to the database based on the existing retention policy oneday.

> INSERT INTO oneday treasures,captain_id=pirate_king value=2
Using retention policy oneday
>

Queries

You can run all InfluxQL queries in the influx CLI.

For more information about InfluxQL, see Overview of data exploration, Schema exploration, and Database management.