All Products
Search
Document Center

Connect to TSDB for InfluxDB® by using the influx CLI

Last Updated: Nov 17, 2021

You can use the influx CLI to connect to a Time Series Database (TSDB) for InfluxDB® instance to perform read and write operations. This topic describes how to perform these operations.

Before you begin

On the official website of Alibaba Cloud, purchase a TSDB for InfluxDB® instance. For more information, see Purchase a TSDB for InfluxDB® instance. Then, create an account that can be used to access the instance. For more information, see Manage user accounts and databases. The account and its password are required to connect to the TSDB for InfluxDB® instance by using the influx CLI.

Download the CLI

  1. On the page on which you can download the CLI, click v1.7.6, as shown in the following figure.

  2. Select the binary installation package for your OS, as shown in the following figure.

  3. Decompress the package. For Mac OS X and Linux, the binary file influx.exe is available in the usr/bin/ path. For Windows, the binary file influx.exe is available in the directory that is automatically created after you decompress the binary package. For example, if you use Mac OS X, you can run the following commands to download the installation package and open the directory where the influx CLI is available:

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

Connect to the TSDB for InfluxDB® instance by using the CLI

Open the CLI. Run the following command to connect to the purchased instance:

./influx -ssl -username <Username>-password <Password>-host <Domain name>-port 3242

TSDB for InfluxDB® uses SSL to ensure secure data transmission. You must specify the -ssl, -username, -password, -host, and -port flags each time you connect to a TSDB for InfluxDB® instance.

Flags

  • -ssl specifies that the connection to be established between your server and the TSDB for InfluxDB® instance is an HTTPS connection.

  • -username specifies a username that can be used to access the TSDB for InfluxDB® instance.

  • -password specifies the password for the username.

  • -host specifies the domain name of the TSDB for InfluxDB® instance. You can view the domain name on the instance details page in the console, as shown in the following figure.

  • -port: specifies the port number. The default value is 3242.

Write data by using the CLI

Before you write data, create a database. For more information, see Create a database. In this example, a database named mydb is created.

  • Write a single point

    1. Connect to TSDB for InfluxDB by running the following command in the influx CLI.

      ./influx -ssl -username <Username>-password <Password>-host <Domain name>-port 3242
    2. Specify mydb as the database to which you want to write data.

      > USE mydb
      Using database mydb
    3. Write a single point to the database mydb.

      > INSERT cpu,host=serverA,region=us_west value=0.64

      This statement writes a point to the database mydband and attaches the default retention policy to the point. cpu is a measurement. host and region are tag keys. value is a field. The point is written in the line protocol format. For more information, see Line protocol. If you do not specify a timestamp in the statement, the system uses the UNIX timestamp of your local server as the timestamp of the point. The timestamp is in nanoseconds. In TSDB for InfluxDB®, all timestamps are in Coordinated Universal Time (UTC).

  • Write multiple points by importing a file

    1. In this example, the test.txt file that contains multiple points is used.

      # DML
      # CONTEXT-DATABASE: mydb
      # CONTEXT-RETENTION-POLICY: autogen
      h2o_feet,location=coyote_creek water_level=3.524,level\ description="between 3 and 6 feet"1439868600
      h2o_feet,location=coyote_creek water_level=3.399,level\ description="between 3 and 6 feet"1439868960
      h2o_feet,location=coyote_creek water_level=3.278,level\ description="between 3 and 6 feet"1439869320
      h2o_feet,location=coyote_creek water_level=3.159,level\ description="between 3 and 6 feet"1439869680
      h2o_feet,location=coyote_creek water_level=3.048,level\ description="between 3 and 6 feet"1439870040
      h2o_feet,location=coyote_creek water_level=2.943,level\ description="below 3 feet"1439870400
      h2o_feet,location=coyote_creek water_level=2.831,level\ description="below 3 feet"1439870760
      h2o_feet,location=coyote_creek water_level=2.717,level\ description="below 3 feet"1439871120
      h2o_feet,location=coyote_creek water_level=2.625,level\ description="below 3 feet"1439871480
      h2o_feet,location=coyote_creek water_level=2.533,level\ description="below 3 feet"1439871840
    2. Import the file to the TSDB for InfluxDB® instance.

      ./influx -ssl -username <Username>-password <Password>-host <Domain name>-port 3242-import-path=test.txt

      Use -import to import the file to the TSDB for InfluxDB® instance. -path specifies the file that you want to import. This statement imports multiple points to the database mydb at a time. h2o_feet is a measurement. location is a tag key. water_level and level description are fields.

Query data by using the CLI

TSDB for InfluxDB® supports various InfluxQL statements. InfluxQL is a query language that is similar to SQL. InfluxQL allows users to perform operations on data in a quick manner. For more information, see Data exploration and Schema exploration.

  1. Before you query data from a TSDB for InfluxDB® instance, connect to the instance.

    ./influx -ssl -username <Username>-password <Password>-host <Domain name>-port 3242
  2. Specify the database from which you want to query data. In the example, the data source is the database mydb.

    > USE mydb
    Using database mydb

Query all points that correspond to a specified measurement

> SELECT * FROM "h2o_feet"
name: h2o_feet
time       level description    location     water_level
----------------------------------------
1439868600 between 3and6 feet coyote_creek 3.524
1439868960 between 3and6 feet coyote_creek 3.399
1439869320 between 3and6 feet coyote_creek 3.278
1439869680 between 3and6 feet coyote_creek 3.159
1439870040 between 3and6 feet coyote_creek 3.048
1439870400 below 3 feet         coyote_creek 2.943
1439870760 below 3 feet         coyote_creek 2.831
1439871120 below 3 feet         coyote_creek 2.717
1439871480 below 3 feet         coyote_creek 2.625
1439871840 below 3 feet         coyote_creek 2.533

All points that correspond to the h2o_feet measurement are returned.

Query a specified field that corresponds to a specified measurement and perform mathematical operations on the field

> SELECT ("water_level"+2)*3 FROM "h2o_feet"
name: h2o_feet
time       water_level
---------------
143986860016.572
143986896016.197
143986932015.834000000000001
143986968015.477
143987004015.144
143987040014.828999999999999
143987076014.492999999999999
143987112014.151000000000002
143987148013.875
143987184013.598999999999998

water_level is a field that corresponds to the h2o_feet measurement. The values of the water_level field are calculated by using the following formula: (water_level + 2) * 3. In TSDB for InfluxDB®, mathematical operations are performed in the standard order. For more information, see Mathematical operations.

Query points whose field values meet the specified requirements

> SELECT * FROM "h2o_feet" WHERE "water_level">3
name: h2o_feet
time       level description    location     water_level
----------------------------------------
1439868600 between 3and6 feet coyote_creek 3.524
1439868960 between 3and6 feet coyote_creek 3.399
1439869320 between 3and6 feet coyote_creek 3.278
1439869680 between 3and6 feet coyote_creek 3.159
1439870040 between 3and6 feet coyote_creek 3.048

The statements query the points that correspond to the h2o_feet measurement. The points in which the value of water_level is greater than 3 are returned. For more information about the WHERE clause, see WHERE clause.

Group the query results

> SELECT MEAN("water_level") FROM "h2o_feet" GROUP BY "location"

name: h2o_feet
tags: location=coyote_creek
time mean
--------
03.0057

This query groups the query results by the location tag and calculates the average value of all water_level values that correspond to each value of the location tag. For more information about the GROUP BY clause, see GROUP BY clause.

Use a regular expression to filter field keys and tag keys

> SELECT /level/ FROM "h2o_feet"
name: h2o_feet
time       level description    water_level
--------------------------------
1439868600 between 3and6 feet 3.524
1439868960 between 3and6 feet 3.399
1439869320 between 3and6 feet 3.278
1439869680 between 3and6 feet 3.159
1439870040 between 3and6 feet 3.048
1439870400 below 3 feet         2.943
1439870760 below 3 feet         2.831
1439871120 below 3 feet         2.717
1439871480 below 3 feet         2.625
1439871840 below 3 feet         2.533

This query returns the values of all field keys and tag keys that contain the "level" string. For more information about regular expressions, see Regular expressions.