README.md
1# Line Protocol
2
3The line protocol is a text based format for writing points to InfluxDB. Each line defines a single point.
4Multiple lines must be separated by the newline character `\n`. The format of the line consists of three parts:
5
6```
7[key] [fields] [timestamp]
8```
9
10Each section is separated by spaces. The minimum required point consists of a measurement name and at least one field. Points without a specified timestamp will be written using the server's local timestamp. Timestamps are assumed to be in nanoseconds unless a `precision` value is passed in the query string.
11
12## Key
13
14The key is the measurement name and any optional tags separated by commas. Measurement names, tag keys, and tag values must escape any spaces or commas using a backslash (`\`). For example: `\ ` and `\,`. All tag values are stored as strings and should not be surrounded in quotes.
15
16Tags should be sorted by key before being sent for best performance. The sort should match that from the Go `bytes.Compare` function (http://golang.org/pkg/bytes/#Compare).
17
18### Examples
19
20```
21# measurement only
22cpu
23
24# measurement and tags
25cpu,host=serverA,region=us-west
26
27# measurement with commas
28cpu\,01,host=serverA,region=us-west
29
30# tag value with spaces
31cpu,host=server\ A,region=us\ west
32```
33
34## Fields
35
36Fields are key-value metrics associated with the measurement. Every line must have at least one field. Multiple fields must be separated with commas and not spaces.
37
38Field keys are always strings and follow the same syntactical rules as described above for tag keys and values. Field values can be one of four types. The first value written for a given field on a given measurement defines the type of that field for all series under that measurement.
39
40* _integer_ - Numeric values that do not include a decimal and are followed by a trailing i when inserted (e.g. 1i, 345i, 2015i, -10i). Note that all values must have a trailing i. If they do not they will be written as floats.
41* _float_ - Numeric values that are not followed by a trailing i. (e.g. 1, 1.0, -3.14, 6.0+e5, 10).
42* _boolean_ - A value indicating true or false. Valid boolean strings are (t, T, true, TRUE, f, F, false, and FALSE).
43* _string_ - A text value. All string values _must_ be surrounded in double-quotes `"`. If the string contains
44a double-quote or backslashes, it must be escaped with a backslash, e.g. `\"`, `\\`.
45
46
47```
48# integer value
49cpu value=1i
50
51cpu value=1.1i # will result in a parse error
52
53# float value
54cpu_load value=1
55
56cpu_load value=1.0
57
58cpu_load value=1.2
59
60# boolean value
61error fatal=true
62
63# string value
64event msg="logged out"
65
66# multiple values
67cpu load=10,alert=true,reason="value above maximum threshold"
68```
69
70## Timestamp
71
72The timestamp section is optional but should be specified if possible. The value is an integer representing nanoseconds since the epoch. If the timestamp is not provided the point will inherit the server's local timestamp.
73
74Some write APIs allow passing a lower precision. If the API supports a lower precision, the timestamp may also be
75an integer epoch in microseconds, milliseconds, seconds, minutes or hours.
76
77## Full Example
78A full example is shown below.
79```
80cpu,host=server01,region=uswest value=1 1434055562000000000
81cpu,host=server02,region=uswest value=3 1434055562000010000
82```
83In this example the first line shows a `measurement` of "cpu", there are two tags "host" and "region, the `value` is 1.0, and the `timestamp` is 1434055562000000000. Following this is a second line, also a point in the `measurement` "cpu" but belonging to a different "host".
84```
85cpu,host=server\ 01,region=uswest value=1,msg="all systems nominal"
86cpu,host=server\ 01,region=us\,west value_int=1i
87```
88In these examples, the "host" is set to `server 01`. The field value associated with field key `msg` is double-quoted, as it is a string. The second example shows a region of `us,west` with the comma properly escaped. In the first example `value` is written as a floating point number. In the second, `value_int` is an integer.
89
90# Distributed Queries
91
92