Get started with InfluxDB OSS

    If you’ve installed InfluxDB locally, the influx command should be available via the command line. Executing influx will start the CLI and automatically connect to the local InfluxDB instance (assuming you have already started the server with service influxdb start or by running influxd directly). The output should look like this:

    Notes:

    • The InfluxDB API runs on port 8086 by default. Therefore, influx will connect to port 8086 and localhost by default. If you need to alter these defaults, run influx --help.
    • The -precision argument specifies the format/precision of any returned timestamps. In the example above, rfc3339 tells InfluxDB to return timestamps in (YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ).

    The command line is now ready to take input in the form of the Influx Query Language (a.k.a InfluxQL) statements. To exit the InfluxQL shell, type exit and hit return.

    A fresh install of InfluxDB has no databases (apart from the system _internal), so creating one is our first task. You can create a database with the CREATE DATABASE <db-name> InfluxQL statement, where <db-name> is the name of the database you wish to create. Names of databases can contain any unicode character as long as the string is double-quoted. Names can also be left unquoted if they contain only ASCII letters, digits, or underscores and do not begin with a digit.

    Throughout this guide, we’ll use the database name mydb:

    1. > CREATE DATABASE mydb
    2. >

    Now that the mydb database is created, we’ll use the SHOW DATABASES statement to display all existing databases:

    1. > SHOW DATABASES
    3. name
    4. ----
    5. mydb
    7. >

    Unlike SHOW DATABASES, most InfluxQL statements must operate against a specific database. You may explicitly name the database with each query, but the CLI provides a convenience statement, USE <db-name>, which will automatically set the database for all future requests. For example:

    Now future commands will only be run against the mydb database.

    Writing and exploring data

    Now that we have a database, InfluxDB is ready to accept queries and writes.

    First, a short primer on the datastore. Data in InfluxDB is organized by “time series”, which contain a measured value, like “cpu_load” or “temperature”. Time series have zero to many points, one for each discrete sample of the metric. Points consist of time (a timestamp), a measurement (“cpu_load”, for example), at least one key-value field (the measured value itself, e.g. “value=0.64”, or “temperature=21.2”), and zero to many key-value tags containing any metadata about the value (e.g. “host=server01”, “region=EMEA”, “dc=Frankfurt”).

    Conceptually you can think of a measurement as an SQL table, where the primary index is always time. tags and fields are effectively columns in the table. tags are indexed, and fields are not. The difference is that, with InfluxDB, you can have millions of measurements, you don’t have to define schemas up-front, and null values aren’t stored.

    Points are written to InfluxDB using the InfluxDB line protocol, which follows the following format:

    1. <measurement>[,<tag-key>=<tag-value>...] <field-key>=<field-value>[,<field2-key>=<field2-value>...] [unix-nano-timestamp]

    The following lines are all examples of points that can be written to InfluxDB:

    1. cpu,host=serverA,region=us_west value=0.64
    2. payment,device=mobile,product=Notepad,method=credit billed=33,licenses=3i 1434067467100293230
    3. stock,symbol=AAPL bid=127.46,ask=127.48

    A point with the measurement name of cpu and tags host and region has now been written to the database, with the measured value of 0.64.

    Now we will query for the data we just wrote:

    1. > SELECT "host", "region", "value" FROM "cpu"
    2. name: cpu
    3. time                                     host         region   value
    4. 2015-10-21T19:28:07.580664347Z  serverA      us_west     0.64
    6. >

    Note: We did not supply a timestamp when writing our point. When no timestamp is supplied for a point, InfluxDB assigns the local current timestamp when the point is ingested. That means your timestamp will be different.

    Let’s try storing another type of data, with two fields in the same measurement:

    1. > INSERT temperature,machine=unit42,type=assembly external=25,internal=37
    2. >

    To return all fields and tags with a query, you can use the * operator:

    InfluxQL has many that are not covered here, including support for Go-style regex. For example:

    1. > SELECT * FROM /.*/ LIMIT 1
    2. --
    3. > SELECT * FROM "cpu_load_short"
    4. --

    This is all you need to know to write data into InfluxDB and query it back. To learn more about the InfluxDB write protocol, check out the guide on Writing Data. To further explore the query language, check out the guide on . For more information on InfluxDB concepts, check out the Key Concepts page.