Access InfluxCloud using the command line interface (CLI)

To access the InfluxCloud instance through the command line interface (CLI), follow the instructions below.

What you need:

The following steps demonstrate how to use InfluxDB’s Command Line Interface to create a database, write some data to that database, and query that data back from your InfluxCloud instance.

1. Download and install InfluxDB

There are several ways to interact with InfluxDB, including the following: HTTP API and client libraries.

Note: While plugins for common data formats such as Graphite are available for InfluxDB, this option is unavailable via InfluxCloud.

Here, we’ll be working with InfluxDB’s Command Line Interface (CLI). The CLI is an easy-to-use interactive shell for writing data to InfluxDB, querying data interactively, and viewing query output in different formats.

Here, you’ll use the CLI on your local machine to connect to your InfluxCloud instance or cluster. To use the CLI on your local machine you need to download InfluxDB. Follow the instructions on the downloads page to install InfluxDB (it’s fast, we promise!).

2. Connect to InfluxDB’s Command Line Interface

Use the CLI on your local machine to connect to your InfluxCloud instance or cluster by entering the following command from your terminal, filling in <your_InfluxCloud_hostname> with your InfluxCloud hostname AND adding the -precision rfc3339 to the usual connection string:

influx -host <your host name> -port 8086 -username $INFLUX_USERNAME -password $INFLUX_PASSWORD -ssl -precision rfc3339

Notes: If you set the INFLUX_USERNAME and INFLUX_PASSWORD environment variables, you can eliminate them from your connection string.
Do not include the ‘https://’ or port as part of the host name. Specifying -precision rfc3339 tells the CLI to format timestamps as YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ (more on timestamps to come). Specifying -ssl tells the CLI to use HTTPS for requests. For more CLI configurations, see the InfluxDB CLI/Shell documentation.

Once you’re connected to the CLI, you’ll see the following text:

Connected to https://your_InfluxCloud_hostname:8086 version 1.8.x
InfluxDB shell 1.8.x
>

Now confirm that your connection is working and you are logged into the instance by executing the following command at the ‘>’ prompt:

> show users

This should output your username and admin status like this:

user             admin
----             -----
<your username>  true

If you do not see this output, you may have mistyped the username or password within the original connection string or environment variables.
Please exit the CLI and re-check these. Repeating steps 1 and 2 before attempting to continue.

3. Create your first database or Import from your existing InfluxDB Instance

Before you write any data to InfluxDB, you need to create a database. A database stores your data. (It also stores information about users, retention policies, and continuous queries but you don’t need to worry about those for now.)

Here, you create a database called state_fair_db using InfluxQL. InfluxQL is our SQL-like query language for interacting with InfluxDB.

> CREATE DATABASE state_fair_db
>

The CLI doesn’t return anything if you successfully create a database. To see your newly-created database, use the SHOW DATABASES command:

> SHOW DATABASES
name: databases
---------------
name
state_fair_db

4. Write data to your database

Now that you have a database, it’s time to write some data to it. First, tell the CLI to work with your newly-created database:

> USE state_fair_db
Using database state_fair_db
>

Let’s get familiar with the data you’ll be writing to the database. The chart below shows the number of funnel cakes at two locations (fair 1 and fair 2) over time.

InfluxDB’s data structure is made up of measurements, tags, fields, and timestamps. Translating the data in the chart into InfluxDB’s data structure looks like this:

  • foods, the title of the chart, is your measurement. Think of a measurement as a logical container for your data.
  • fair_id is your tag. It has two values: 1 and 2. Tags store meta data about the data stored in fields. Tags are an optional part of InfluxDB’s data structure.
  • funnel_cakes is your field. It has six different values. Fields store the actual time series data.
  • The dates and times on the x-axis serve as your timestamps. Every data point that you write to InfluxDB will have a timestamp; we are a time series database after all!

Now that you know how your data fit into the InfluxDB structure, it’s time to format your data so that InfluxDB can understand them. We call the format for writing points to InfluxDB Line Protocol. The Line Protocol for the first point in the chart where fair_id is 1 looks like this:

foods,fair_id=1 funnel_cakes=23 1439856000000000000

The measurement name (foods) comes first, followed by a comma and the tag key-value pair (fair_id=1). After the tag key-value pair, there’s a white space, followed by the field key-value pair (funnel_cakes=23). Finally, there’s another white space and the nanosecond timestamp (1439856000000000000). The timestamp must be in Unix time (the time that has passed since January 01, 1970 UTC). The timestamp is optional, and, if not specified, InfluxDB assigns your server’s local time (in nanoseconds) to the point.

Note: Timestamps don’t have to be in nanoseconds when you write them to the database. See Write Syntax for how to write non-nanosecond timestamps to InfluxDB using the HTTP API.

To write that first point to InfluxDB using the CLI, just put INSERT in front of it:

> INSERT foods,fair_id=1 funnel_cakes=23 1439856000000000000

Now INSERT the rest of the data:

> INSERT foods,fair_id=1 funnel_cakes=28 1439856360000000000
> INSERT foods,fair_id=1 funnel_cakes=27 1439856720000000000
> INSERT foods,fair_id=2 funnel_cakes=14 1439856000000000000
> INSERT foods,fair_id=2 funnel_cakes=18 1439856360000000000
> INSERT foods,fair_id=2 funnel_cakes=36 1439856720000000000

Notice that the CLI doesn’t return anything when you successfully write data to your database. Move on to the next section to see what your data look like in InfluxDB!

5. Query data in your database

As we mentioned earlier, InfluxQL is InfluxDB’s SQL-like query language. It’s designed to feel familiar to those coming from other SQL or SQL-like environments while providing features specific to storing and analyzing time series data.

Let’s start out with a simple InfluxQL query to view all fields and tags (*) in the measurement foods.

> SELECT * FROM foods

CLI response:

name: foods
-----------
time			 fair_id   funnel_cakes
2015-08-18T00:00:00Z	 1	   23
2015-08-18T00:00:00Z	 2	   14
2015-08-18T00:06:00Z	 1	   28
2015-08-18T00:06:00Z	 2	   18
2015-08-18T00:12:00Z	 1	   27
2015-08-18T00:12:00Z	 2	   36

The output shows the measurement name (foods), the timestamps in RFC3339 format (YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ) in the time column, the tag (fair_id) and its values, and the field (funnel_cakes) and its values. Every piece of data that you write to InfluxDB will have the time column.

Below, you’ll find several queries to give you an insight into what InfluxQL can do for you:

  • Select just the field funnel_cakes from the foods measurement:

    > SELECT funnel_cakes FROM foods
name: foods
-----------
time			         funnel_cakes
2015-08-18T00:00:00Z	 23
2015-08-18T00:00:00Z	 14
2015-08-18T00:06:00Z	 28
2015-08-18T00:06:00Z	 18
2015-08-18T00:12:00Z	 27
2015-08-18T00:12:00Z	 36

  • Calculate the average number of funnel_cakes in the measurement foods using one of InfluxQL’s functions:

    > SELECT mean(funnel_cakes) FROM foods
name: foods
-----------
time			        mean
1970-01-01T00:00:00Z	24.333333333333332

  • Calculate the average number of funnel_cakes in the measurement foods for each value of fair_id using InfluxQL’s GROUP BY clause:

    > SELECT mean(funnel_cakes) FROM foods GROUP BY fair_id
name: foods
tags: fair_id=1
time			        mean
----			        ----
1970-01-01T00:00:00Z	26

name: foods
tags: fair_id=2
time			        mean
----			        ----
1970-01-01T00:00:00Z	22.666666666666668

  • Calculate the sum of funnel_cakes in the measurement foods for every 12m interval of data using InfluxQL’s GROUP BY clause:

    > SELECT sum(funnel_cakes) FROM foods WHERE time >= '2015-08-18T00:00:00Z' and time <= '2015-08-18T00:12:00Z' GROUP BY time(12m)
name: foods
-----------
time			 sum
2015-08-18T00:00:00Z	 83
2015-08-18T00:12:00Z	 63

  • Perform the same query above but use InfluxQL’s INTO functionality to write the results of the query to a new measurement called downsampled_data:

    > SELECT sum(funnel_cakes) INTO downsampled_data FROM foods WHERE time >= '2015-08-18T00:00:00Z' and time <= '2015-08-18T00:12:00Z' GROUP BY time(12m)
name: result
------------
time			 written
1970-01-01T00:00:00Z	 2

> SELECT * FROM downsampled_data
name: downsampled_data
----------------------
time			 sum
2015-08-18T00:00:00Z	 83
2015-08-18T00:12:00Z	 63

    Note: You can make InfluxDB automatically perform this kind of downsampling (so periodically performing an aggregation and writing the results of that aggregation to a new measurement) with InfluxDB’s Continuous Queries.

You’ve now been introduced to the fundamentals of InfluxDB, its data structure, and its query language. To learn more about InfluxDB check out our documentation. For more on InfluxQL specifically, see our query language documentation.