All Products
Search

This Product

    Time Series Database:Line protocol tutorial

    Document Center

    Time Series Database:Line protocol tutorial

    Last Updated:Mar 28, 2026

    Line protocol is a text-based format for writing data points to TSDB for InfluxDB®. Each line of text represents one point. TSDB for InfluxDB® only accepts points in line protocol format.

    This page covers:

    | Syntax | Data types | Quotation marks | Special characters and keywords | Write data |

    Syntax

    A point in line protocol has the following structure:

    weather,location=us-midwest temperature=82 1465839830100400200
  |    -------------------- --------------  |
  |             |             |             |
  |             |             |             |
+-----------+--------+-+---------+-+---------+
|measurement|,tag_set| |field_set| |timestamp|
+-----------+--------+-+---------+-+---------+

    Each element is described below.

    Measurement

    The measurement name. Required.

    In the example above, the measurement is weather.

    Tag set

    One or more tag key-value pairs. Optional.

    • Separate the measurement and tag set with a comma (,). No spaces.

    • Separate each tag key and value with an equals sign (=). No spaces.

    • Separate multiple tag pairs with commas. No spaces.

    <tag_key>=<tag_value>
<tag_key>=<tag_value>,<tag_key>=<tag_value>

    In the example, the tag set is location=us-midwest. To add a second tag season=summer:

    weather,location=us-midwest,season=summer temperature=82 1465839830100400200

    For best write performance, sort tags by key before sending points. The sort order must match the Go bytes.Compare function.

    Space I

    A single space separating the measurement (or tag set) from the field set. Required.

    A point without tags is also valid:

    weather temperature=82 1465839830100400200

    Field set

    One or more field key-value pairs. Required — every point must have at least one field.

    • Separate the field key and value with an equals sign (=). No spaces.

    • Separate multiple field pairs with commas. No spaces.

    <field_key>=<field_value>
<field_key>=<field_value>,<field_key>=<field_value>

    In the example, the field set is temperature=82. To add a second field humidity=71:

    weather,location=us-midwest temperature=82,humidity=71 1465839830100400200

    Space II

    A single space separating the field set from the timestamp. Required if a timestamp is present.

    Timestamp

    A UNIX timestamp with nanosecond precision. Optional.

    If omitted, TSDB for InfluxDB® uses the server's local UTC time in nanoseconds.

    In the example, 1465839830100400200 corresponds to 2016-06-13T17:43:50.1004002Z in RFC 3339 format. The following point omits the timestamp — when written, it gets the server's current time instead:

    weather,location=us-midwest temperature=82

    To use a coarser time precision (microsecond, millisecond, or second), specify the precision via the HTTP API. Use the coarsest precision that meets your needs — it significantly improves data compression.

    Use Network Time Protocol (NTP) to synchronize clocks across hosts. TSDB for InfluxDB® timestamps data using the host's local UTC time, so an unsynchronized clock produces inaccurate timestamps.

    Data types

    Measurement names, tag keys, tag values, and field keys are always stored as strings.

    Because tag values are strings, InfluxQL functions cannot use them as primary arguments, and TSDB for InfluxDB® cannot perform math on them. Design your schema accordingly.

    Timestamps

    Timestamps are UNIX timestamps. The valid range is:

    BoundValueRFC 3339 equivalent
    Minimum-92233720368547758061677-09-21T00:12:43.145224194Z
    Maximum92233720368547758062262-04-11T23:47:16.854775806Z

    By default, TSDB for InfluxDB® uses nanosecond precision. To specify a different precision, see HTTP API.

    Field value types

    TSDB for InfluxDB® supports four field value types:

    TypeSyntaxExample
    FLOATDefault for numeric valuestemperature=82
    INTEGERAppend itemperature=82i
    STRINGEnclose in double quotestemperature="too warm"
    BOOLEANTRUE: t, T, true, True, TRUE — FALSE: f, F, false, False, FALSEtoo_hot=true

    FLOAT — All numeric values default to floating-point:

    weather,location=us-midwest temperature=82 1465839830100400200

    INTEGER — Append i to store the value as an integer:

    weather,location=us-midwest temperature=82i 1465839830100400200

    STRING — Enclose in double quotes:

    weather,location=us-midwest temperature="too warm" 1465839830100400200

    BOOLEAN — Use any of the accepted literal forms:

    weather,location=us-midwest too_hot=true 1465839830100400200
    The syntax for writing BOOLEAN values differs from the syntax for querying them. See FAQ.

    Type consistency across shards

    Field types must be consistent within a shard but can differ across shards.

    Writing an integer into the same shard that already holds floats for that field causes a type conflict:

    > INSERT weather,location=us-midwest temperature=82 1465839830100400200
> INSERT weather,location=us-midwest temperature=81i 1465839830100400300
ERR: {"error":"field type conflict: input field \"temperature\" on measurement \"weather\" is type int64, already exists as type float"}

    Writing an integer into a new shard succeeds even if earlier shards stored floats:

    > INSERT weather,location=us-midwest temperature=82 1465839830100400200
> INSERT weather,location=us-midwest temperature=81i 1467154750000000000
>

    For how type differences affect SELECT * queries, see the corresponding section in FAQ.

    Quotation marks

    ElementDouble quotes "Single quotes '
    TimestampsNever — invalidNever — invalid
    STRING field valuesRequiredNever — invalid
    Non-string field valuesAvoided — treated as STRINGN/A
    Measurement names, tag keys, tag values, field keysAccepted, but quotes become part of the nameAccepted, but quotes become part of the name

    Timestamp — never quote:

    > INSERT weather,location=us-midwest temperature=82 "1465839830100400200"
ERR: {"error":"unable to parse 'weather,location=us-midwest temperature=82 \"1465839830100400200\"': bad timestamp"}

    STRING field value — double quotes required, single quotes invalid:

    > INSERT weather,location=us-midwest temperature='too warm'
ERR: {"error":"unable to parse 'weather,location=us-midwest temperature='too warm'': invalid boolean"}

    Measurement names — quoting makes the quotes part of the name:

    > INSERT weather,location=us-midwest temperature=82 1465839830100400200
> INSERT "weather",location=us-midwest temperature=87 1465839830100400200
> SHOW MEASUREMENTS
name: measurements
------------------
name
"weather"
weather

    To query the "weather" measurement, escape the quotes inside the query string:

    > SELECT * FROM "\"weather\""
name: "weather"
---------------
time                            location     temperature
2016-06-13T17:43:50.1004002Z    us-midwest   87

    Non-string field values — do not double-quote; they become strings and numeric queries fail:

    > INSERT weather,location=us-midwest temperature="82"
> SELECT * FROM weather WHERE temperature >= 70
>

    STRING field values — double-quote to store and retrieve correctly:

    > INSERT weather,location=us-midwest temperature="too warm"
> SELECT * FROM weather
name: weather
-------------
time                            location     temperature
2016-06-13T19:10:09.995766248Z  us-midwest   too warm

    Special characters and keywords

    Escape characters

    Use a backslash (\) to escape the following characters:

    ElementCharacters to escape
    Measurement namesComma (,), space
    Tag keysComma (,), equals sign (=), space
    Tag valuesComma (,), equals sign (=), space
    Field keysComma (,), equals sign (=), space
    STRING field valuesDouble quotation mark (")

    Examples:

    # Comma in tag value
weather,location=us\,midwest temperature=82 1465839830100400200

# Equals sign in field key
weather,location=us-midwest temp\=rature=82 1465839830100400200

# Space in tag key
weather,location\ place=us-midwest temperature=82 1465839830100400200

# Comma in measurement name
wea\,ther,location=us-midwest temperature=82 1465839830100400200

# Space in measurement name
wea\ ther,location=us-midwest temperature=82 1465839830100400200

# Double quote in STRING field value
weather,location=us-midwest temperature="too\"hot\"" 1465839830100400200

    Backslash behavior

    Backslashes in STRING field values follow a pairing rule:

    WrittenStored
    \\
    \\\
    \\\\\
    \\\\\\
    \\\\\\\\

    Backslashes themselves do not need to be escaped. Writing \\ is accepted but treated the same as \. For example:

    weather,location=us-midwest temperature_str="too hot/cold" 1465839830100400201
weather,location=us-midwest temperature_str="too hot\cold" 1465839830100400202
weather,location=us-midwest temperature_str="too hot\\cold" 1465839830100400203
weather,location=us-midwest temperature_str="too hot\\\cold" 1465839830100400204
weather,location=us-midwest temperature_str="too hot\\\\cold" 1465839830100400205
weather,location=us-midwest temperature_str="too hot\\\\\cold" 1465839830100400206

    Query result:

    > SELECT * FROM "weather"
name: weather
time                location   temperature_str
----                --------   ---------------
1465839830100400201 us-midwest too hot/cold
1465839830100400202 us-midwest too hot\cold
1465839830100400203 us-midwest too hot\cold
1465839830100400204 us-midwest too hot\\cold
1465839830100400205 us-midwest too hot\\cold
1465839830100400206 us-midwest too hot\\\cold

    Other special characters

    All other special characters do not need to be escaped.

    Keywords

    Avoid using InfluxQL keywords as identifier names — they may be misinterpreted during queries.

    The time keyword is a special case: it can be used as a continuous query name, database name, measurement name, retention policy name, subscription name, or username without quoting. However, time cannot be used as a field key or tag key — TSDB for InfluxDB® rejects such writes. See FAQ for details.

    Write data to TSDB for InfluxDB®

    HTTP API

    Send a POST request to the /write endpoint with line protocol data in the request body:

    curl -i -XPOST "https://<Network address>:3242/write?db=science_is_cool&u=<Account name>&p=<Password>" \
  --data-binary 'weather,location=us-midwest temperature=82 1465839830100400200'

    For query parameters, status codes, and more examples, see HTTP API.

    CLI

    Start the CLI and prefix each line protocol point with INSERT:

    INSERT weather,location=us-midwest temperature=82 1465839830100400200

    You can also import data from a file using the CLI.

    For all available write methods, see Tools.

    Duplicate points

    A point is uniquely identified by its measurement name, tag set, and timestamp. If a new point matches an existing point on all three but has a different field set, the field sets are merged. When a field key appears in both, the new value takes precedence.

    For a complete example and guidance on handling duplicates, see the corresponding section in FAQ.

    InfluxDB® is a trademark registered by InfluxData, which is not affiliated with, and does not endorse, TSDB for InfluxDB®.