Create a database using the HTTP API

To create a database send a POST request to the /query endpoint and set the URL parameter q to CREATE DATABASE <new_database_name>. The example below sends a request to InfluxDB running on locahost and create the database mydb.

curl -i -XPOST http://localhost:8086/query --data-urlencoded "q=CREATE DATABASE mydb"

Writing data using the HTTP API

The HTTP API is the primary means of writing data into InfluxDB, by sending POST requests to the /write endpoint. The example below writes a single point to the mydb database. The data consist of the measurement cpu_load_short. the tag keys host and region with the tag values server01 and us-west, the field key value with a field value of 0.64 and the timestamp 434055562000000000.

curl -i -XPOST 'http://localhost:8086/write?db=mydb' --data-binary 'cpu_load_short,host=server01,region=us-west value=0.64 1434055562000000000'

When writing points, you must specify an existing database in the db query parameter. Points will be written to db‘s default retention policy if you do not supply a retention policy via the rp query parameter.

The body of the POST - we call this the Line Protocol - contains the time-series data that you wish to store. They consist of a measurement, tags, fields, and a timestamp. InfluxDB requires a measurement name.

Strictly speaking, tags are optional but most series include tags to differentiate data sources and to make querying both easy and efficient. Both tag keys and tag values are strings.

Field keys are required and always strings, and by default, field values are floats. The timestamp - supplied at the end of the line in Unix time in nanoseconds since January 1, 1970 UTC - is optional. If you do not specify a timestamp InfluxDB uses the server’s local nanoseconds timestamp in Unix epoch.

Anything that has to do with tim ein InfluxDB is always UTC.

Writing multiple points

Post multiple points to multiple series at the same time by separating each point with a new line. Batching points in this manner results in much higher performance.

The following example writes three points to the database mydb.

The first point belongs to the series with the measurement cpu_load_short and tag set host-server02 and has the server’s local timestamp

The second point belongs to the series with the measurement cpu_load_short and tag set host=server02,region=us-west and has the specified timestamp 1422568543702900257.

The third point has the same specified timestamp as the second point, but it is written to the series with the measruement cpu_load_short and tag set direction=in,host=server01,region=us-west

curl -i -XPOST 'http://localhost:8086/write?db=mydb' --data-binary 'cpu_load_short,host=server02 value=0.67 cpu_load_short,host=server02,region=us-west value=0.5 cpu_load_short,direction=in,host=server01,region=us-west value=0.2'

Writing points from a file

Write points from a file by passing @filename to curl. The data in the file should follow InfluxDB’s line protocol syntax

Example of a properly-formatted file(cpu_data.txt)

cpu_load_short,host=server02 value=0.2
cpu_load_short,host=server02,region=us-west value=0.5
cpu_load_short,direction=in,host=server01,region=us-west value=0.2

Write the data in cpu_data.txt to the mydb datbase with:

curl -i -XPOST 'http://localhost:8086/write?db=mydb' --data-binary @cpu_data.txt

Note: If your data file has more than 5000 points, it may be necessary to split that file into several files in order to write your data in batches to influxDB. By default, the HTTP request times out after five seconds. InfluxDB will still attempt to write the points after that time out but there will be no confirmation that they were successfully written.

Schemaless Design

InfluxDB is a schemaless database. You can add new measurement, tags, and fields at any time. Note that if you attempt to write data with a different type than previous used(for example, writing a string to a field that previously accepted integers), InfluxDB will reject those data.

HTTP response summary

  • 2xx: If you write request received HTTP 204 No Content, it was a success

  • 4xx: InfluxDB could not understand the request

  • 5xx: The system is overloaded or significantly impaired.