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 replacets-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 to8086
. If the TSDB for InfluxDB® instance is connected over the Internet, set this parameter to3242
.
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'
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
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
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.