The influx
command-line interface (CLI) of TSDB for InfluxDB® is a shell that allows you to interact with the HTTP API. You can use the influx
CLI to manually write data, write data from files, interactively query data, and view query results that use various formats.
Download the CLI
Download the CLI by using this link: Download, and select v1.7.6.
Download a binary package that is specific to your operating system. The following figure shows the binary packages for different operating systems.
Then, decompress your binary package, and go to the folder that is extracted from the binary package. In the usr/bin/ directory, you can find the influx CLI. If you download a Windows binary package, you can find the influx.exe binary file in the folder extracted from the package. If you use the Mac OS X operating system, run the following commands to download the binary package and go to the directory where influx resides:
$ wget https://dl.influxdata.com/influxdb/releases/influxdb-1.7.6_darwin_amd64.tar.gz
$ tar zxvf influxdb-1.7.6_darwin_amd64.tar.gz
$ cd influxdb-1.7.6-1/usr/bin
$
Start influx
To use the CLI, start influx
in your terminal first. After your TSDB for InfluxDB® instance is connected, you can view the following output:
$ ./influx -ssl -username <Username> -password <Password> -host <Domain name> -port 3242
Connected to https://<Domain name>:3242 version 1.7.x
InfluxDB shell version: 1.7.x
TSDB for InfluxDB® uses the Secure Sockets Layer (SSL) protocol to ensure security during data transmission. Therefore, each time you connect to a TSDB for InfluxDB® instance, you must set the following five parameters: -ssl
, -username
, -password
, -host
, and -port
.
Parameter description
-ssl
: indicates that HTTPS is used to connect to TSDB for InfluxDB® servers.-username
: specifies the username that is used to connect to the servers.-password
: specifies the password for the username.-host
: specifies the domain name. You can find the domain name on the Instance Details page in the TSDB console. The following figure shows the Instance Details page.
-port
: specifies a network port. The default port is port 3242.
Then, you can enter InfluxQL query statements and CLI-specific commands in your terminal. If you want to enter Flux query statements, you must set the -type
parameter to flux
. You can use the help
command to obtain available commands. You can use the Ctrl+C
keyboard shortcut to terminate long-running InfluxQL queries.
Use environment variables
You can use the following environment variables to configure the settings for the influx
client. You can specify the environment variables by using uppercase or lowercase characters, but the uppercase version has a higher priority.
HTTP_PROXY
This environment variable defines the proxy server that is used for HTTP.
Value format: [protocol://]
HTTP_PROXY=http://localhost:1234
HTTPS_PROXY
This environment variable defines the proxy server that is used for HTTPS. If you set the HTTP_PROXY and HTTPS_PROXY variables, the HTTPS_PROXY value has a higher priority than the HTTP_PROXY value for HTTPS.
Value format: [protocol://]
HTTPS_PROXY=https://localhost:1443
NO_PROXY
This environment variable specifies a list of host names that do not use proxies. If you set this variable to an asterisk (*
) only, the variable matches all hosts.
Value format: a comma-separated list of hosts
NO_PROXY=123.45.67.89,123.45.67.90
Arguments for influx
You can pass available arguments into influx
when you start influx
. To obtain the list of available arguments, run the $influx --help
command. This section provides a brief description about each available argument, and offers the details about the -execute
, -format
, and -import
arguments.
-compressed
Specifies whether to compress data. The -compressed
argument is used in conjunction with the -import
argument. If an imported file is compressed, set this argument to true.
-consistency 'any|one|quorum|all'
Specifies a consistency level for data writes.
-database 'database name'
Specifies the database to which the influx
CLI connects.
-execute '<command>'
Executes an InfluxQL statement and exits.
-format 'json|csv|column'
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 this argument (-password ''
), the influx
CLI 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 where the file to be imported resides. The -path
argument must be used in conjunction with the -import
argument.
-port 'port #'
Specifies the port to which the influx
CLI connects. By default, TSDB for InfluxDB® runs on port 3242
.
-pps
Specifies the number of points that can be imported per second. By default, the -pps argument is set to 0 and the influx CLI does not limit the speed of importing data. The -pps
argument must be used in conjunction with the -import
argument.
-precision 'rfc3339|h|m|s|ms|u|ns'
Specifies the format and the granularity of timestamps for data queries and writes: rfc3339
(YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ
), h
(hours), m
(minutes), s
(seconds), ms
(milliseconds), u
(microseconds), and ns
(nanoseconds). The default granularity is nanoseconds.
Note: If the granularity is set to
rfc3339
(-precision rfc3339
), this argument can be used in conjunction with the-execute
argument but cannot be used in conjunction with the-import
argument. If the granularity is set to the other formats, this argument can be used in conjunction with-execute
and-import
arguments. The other granularity formats includeh
,m
,s
,ms
,u
, andns
.
-pretty
Beautifies JSON-formatted data to deliver improved reading experience.
-ssl
Enables HTTPS for requests.
-type
Specifies the interactive shell that is used. The default value is influxql
. If you want to use the Flux REPL shell, set -type
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
Shows the TSDB for InfluxDB® version and exits.
Execute an InfluxQL statement and exit by using -execute
If you want to query data from all available databases, run the following query:
$ influx -ssl -username <Username> -password <Password> -host <Domain name> -port 3242 -execute 'SHOW DATABASES'
name: databases
---------------
name
NOAA_water_database
_internal
telegraf
pirates
If you want to query data from a specific database and change the timestamp granularity, run the following query:
$ influx -ssl -username <Username> -password <Password> -host <Domain name> -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 value for the -format argument is column
.
$ influx -ssl -username <Username> -password <Password> -host <Domain name> -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 <Domain name> -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 <Domain name> -port 3242 -format=json
[...]
> SHOW DATABASES
{"results":[{"series":[{"name":"databases","columns":["name"],"values":[["NOAA_water_database"],["_internal"],["telegraf"],["pirates"]]}]}]}
Change the format to json
and beautify the output data.
$ influx -ssl -username <Username> -password <Password> -host <Domain name> -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
An imported file consists of two parts:
- Data Definition Language (DDL): includes InfluxQL statements that are used to create the relevant database and manage the retention policy. If your database and retention policy have been created, you can skip this part in the file.
- Data Manipulation Language (DML): lists the relevant database and the retention policy if you require the retention policy, and contains the data that uses the line protocol.
Example
Assume that the pirates
database and the oneday
retention policy have been 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 <Domain name> -port 3242 -import -path=datarrr.txt -precision=s
Result:
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
Note: For large datasets, the
influx
CLI provides a status message every 100,000 points. An example of the status message is provided as follows:
2015/08/21 14:48:01 Processed 3100000 lines. Time elapsed: 56.740578415s. Points per second (PPS): 54634
To use -import
, you must pay attention to the following considerations:
- You can use the
-pps
argument to specify the number of points that can be imported per second. This setting is applied when you write points to the database. By default, the -pps argument is set to 0 and the influx CLI does not limit the speed of importing data. - You can import data from .gz files by including
-compressed
in the command. - You must provide timestamps for the points that are stored in files. Otherwise, TSDB for InfluxDB® assigns the same timestamp to points that do not have timestamps. This may cause unexpected data overwriting.
- If your data file has more than 5,000 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 points in each batch. If you include a smaller number of points in each batch, a larger number of HTTP requests must be sent. This compromises the performance. By default, the time-out period for each HTTP request is five seconds. TSDB for InfluxDB® attempts to write points after a request time-out, but the points may fail to be written.
Commands of the influx CLI
You can enter help
in the CLI to obtain available commands.
Commands
This section provides a brief description of each available command, and provides the details about the insert
command.
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
and INFLUX_PASSWORD
environment variables to specify the username and the password for the CLI, respectively.
chunked
Returns chunked responses sent from a server when you run queries. By default, chunked responses are returned.
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 its default value by setting the size parameter to 0.
clear [ database | db | retention policy | rp ]
Clears the context for the current database or the retention policy.
connect <host:port>
Connects to another server without the need to exit from the shell. By default, the influx
CLI connects to localhost:8086
. If you do not specify the host or the port, the influx
CLI uses the default settings for the parameters that you do not specify.
consistency <level>
Specifies a consistency level for data writes. The valid values are any
, one
, quorum
, and all
.
Ctrl+C
Terminates a running query. This command is especially useful if you want to terminate long-running interactive queries where the system 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
Shows your command history. To run the history 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 the granularity of timestamps for data queries and writes: rfc3339
(YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ
), h
(hours), m
(minutes), s
(seconds), ms
(milliseconds), u
(microseconds), or ns
(nanoseconds). The default granularity is nanoseconds.
pretty
Beautifies JSON-formatted data to deliver improved reading experience.
settings
Returns the current settings of the shell. The current settings include the settings of the Host
, Username
, Database
, Retention Policy
, Pretty
, Chunked
, Chunk Size
, Format
, and Write Consistency
elements.
use [ "<database_name>" | "<database_name>"."<retention policy_name>" ]
Specifies the current database and retention policy. If the current database and the retention policy are specified in the influx
CLI, you do not need to specify the database or the retention policy in queries. If you do not specify a retention policy, the influx
CLI queries data from the default (DEFAULT
) retention policy of the database by default.
Write data to TSDB for InfluxDB® by using insert
To write the data to TSDB for InfluxDB®, enter insert, and then enter the data that uses the line protocol. To write data to a specific retention policy, use insert into <retention policy> <line protocol>
.
The following example writes data into a single field in the treasures
measurement that includes the captain_id = pirate_king
tag. By default, the influx
CLI writes the point to the default (DEFAULT
) retention policy of the database.
> INSERT treasures,captain_id=pirate_king value=2
>
The following example writes the same point in the preceding example to the existing oneday
retention policy.
> INSERT INTO oneday treasures,captain_id=pirate_king value=2
Using retention policy oneday
>
Queries
Run all InfluxQL queries in the influx
CLI.
For more information about InfluxQL, see Data exploration, Schema exploration, and Database management.
InfluxDB® is a trademark registered by InfluxData, which is not affiliated with, and does not endorse, TSDB for InfluxDB®.