Fix/3715 line protocol ref (#3749)
* WIP: apply corrections and additions from line-protocol-spec. * fix: line protocol reference per the line protocol spec. * fix: line protocol escape sequences. * fix: Flux link * fix: backslash escaping, naming restrictions, and canonical form (#3715) * fix: add toc links (#3715) * fix: underscore quotes. * Apply suggestions from code review Co-authored-by: Roger Peppe <rogpeppe@gmail.com> * fix: line protocol examples. Remove misleading table for backslashes. Add links and notes for schema design best practices. Fix missing link targets. * Update content/influxdb/v2.1/reference/syntax/line-protocol.md Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> * fix: specify that field values aren't indexed. Cleanup. Co-authored-by: Roger Peppe <rogpeppe@gmail.com> Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com>pull/3640/head^2
Jason Stirnaman
GitHub
parent
3a9f6cb9e9
commit
5d275bdc03
|
|
@ -8,7 +8,7 @@ menu:
|
|||
parent: Key concepts
|
||||
name: Data elements
|
||||
influxdb/v2.1/tags: [key concepts, schema]
|
||||
related:
|
||||
related:
|
||||
- /resources/videos/data-model-building-blocks/
|
||||
---
|
||||
|
||||
|
|
@ -51,19 +51,19 @@ The `_measurement` column shows the name of the measurement `census`. Measureme
|
|||
|
||||
## Fields
|
||||
|
||||
A field includes a field key stored in the `_field` column and a field value stored in the `_value` column.
|
||||
A field includes a field key stored in the `_field` column and a field value stored in the `_value` column. A [measurement](#measurement) requires at least one field.
|
||||
|
||||
### Field key
|
||||
|
||||
A field key is a string that represents the name of the field. In the sample data above, `bees` and `ants` are field keys.
|
||||
A field key is a string that represents the name of the field. In the [sample data](#sample-data) above, `bees` and `ants` are field keys.
|
||||
|
||||
### Field value
|
||||
|
||||
A field value represents the value of an associated field. Field values can be strings, floats, integers, or booleans. The field values in the sample data show the number of `bees` at specified times: `23`, and `28` and the number of `ants` at a specified time: `30` and `32`.
|
||||
A field value represents the value of an associated field. Field values can be strings, floats, integers, or booleans. The field values in the [sample data](#sample-data) show the number of `bees` at specified times: `23`, and `28` and the number of `ants` at a specified time: `30` and `32`.
|
||||
|
||||
### Field set
|
||||
|
||||
A field set is a collection of field key-value pairs associated with a timestamp. The sample data includes the following field sets:
|
||||
A field set is a collection of field key-value pairs associated with a timestamp. A [measurement](#measurement) requires at least one field. The [sample data](#sample-data) includes the following field sets:
|
||||
|
||||
```bash
|
||||
|
||||
|
|
@ -75,17 +75,21 @@ census bees=28i,ants=32i 1566086760000000000
|
|||
```
|
||||
|
||||
{{% note %}}
|
||||
**Fields aren't indexed:** Fields are required in InfluxDB data and are not indexed. Queries that filter field values must scan all field values to match query conditions. As a result, queries on tags > are more performant than queries on fields. **Store commonly queried metadata in tags.**
|
||||
|
||||
**Field values aren't indexed**. Store commonly queried metadata in tags.
|
||||
|
||||
To learn how to use fields and tags to improve your queries, see [best practices for schema design](/influxdb/v2.1/write-data/best-practices/schema-design/).
|
||||
|
||||
{{% /note %}}
|
||||
|
||||
## Tags
|
||||
|
||||
The columns in the sample data, `location` and `scientist`, are tags.
|
||||
Tags include tag keys and tag values that are stored as strings and metadata.
|
||||
In the [sample data](#sample-data), the columns `location` and `scientist` are tags that provide metadata for the point.
|
||||
Tags include tag keys and tag values that are stored as strings.
|
||||
|
||||
### Tag key
|
||||
|
||||
The tag keys in the sample data are `location` and `scientist`.
|
||||
The tag keys in the [sample data](#sample-data) are `location` and `scientist`.
|
||||
_For information about tag key requirements, see [Line protocol – Tag set](/influxdb/v2.1/reference/syntax/line-protocol/#tag-set)._
|
||||
|
||||
### Tag value
|
||||
|
|
@ -96,7 +100,7 @@ _For information about tag value requirements, see [Line protocol – Tag set](/
|
|||
|
||||
### Tag set
|
||||
|
||||
The collection of tag key-value pairs make up a tag set. The sample data includes the following four tag sets:
|
||||
The collection of tag key-value pairs make up a tag set. The [sample data](#sample-data) includes the following four tag sets:
|
||||
|
||||
```bash
|
||||
location = klamath, scientist = anderson
|
||||
|
|
@ -106,12 +110,11 @@ location = portland, scientist = mullen
|
|||
```
|
||||
|
||||
{{% note %}}
|
||||
**Tags are indexed:** Tags are optional. You don't need tags in your data structure, but it's typically a good idea to include tags.
|
||||
Because tags are indexed, queries on tags are faster than queries on fields. This makes tags ideal for storing commonly-queried metadata.
|
||||
{{% /note %}}
|
||||
|
||||
{{% note %}}
|
||||
Tags containing highly variable information like UUIDs, hashes, and random strings will lead to a large number of unique series in the database, known as **high series cardinality**. High series cardinality is a primary driver of high memory usage for many database workloads. See [series cardinality](/influxdb/v2.1/reference/glossary/#series-cardinality) for more information.
|
||||
**Field values aren't indexed**. Store commonly queried metadata in tags.
|
||||
|
||||
To learn how to use fields and tags to improve your queries, see [best practices for schema design](/influxdb/v2.1/write-data/best-practices/schema-design/).
|
||||
|
||||
{{% /note %}}
|
||||
|
||||
|
||||
|
|
@ -125,7 +128,7 @@ from(bucket: "bucket-name")
|
|||
|> filter(fn: (r) => r._field == "bees" and r._value == 23)
|
||||
```
|
||||
|
||||
InfluxDB scans every field value in the dataset for `bees` before the query returns a response. If our sample `census` data grew to millions of rows, to optimize your query, you could rearrange your [schema](/influxdb/v2.1/reference/glossary/#schema) so the fields (`bees` and `ants`) becomes tags and the tags (`location` and `scientist`) become fields:
|
||||
InfluxDB scans every field value in the dataset for `bees` before the query returns a response. If our `census` [sample data](#sample-data) grew to millions of rows, to optimize your query, you could rearrange your [schema](/influxdb/v2.1/reference/glossary/#schema) so the fields (`bees` and `ants`) becomes tags and the tags (`location` and `scientist`) become fields:
|
||||
|
||||
| _time | _measurement | {{< tooltip "Tag key" "bees" >}} | _field | _value |
|
||||
|:------------------- |:------------ |:------- |:-- |:------ |
|
||||
|
|
@ -143,6 +146,12 @@ InfluxDB scans every field value in the dataset for `bees` before the query retu
|
|||
|
||||
Now that `bees` and `ants` are tags, InfluxDB doesn't have to scan all `_field` and `_value` columns. This makes your queries faster.
|
||||
|
||||
{{% note %}}
|
||||
|
||||
For more information about designing measurements, tags, and fields for querying, see [best practices for schema design](/influxdb/v2.1/write-data/best-practices/schema-design/).
|
||||
|
||||
{{% /note %}}
|
||||
|
||||
## Bucket schema
|
||||
|
||||
In InfluxDB Cloud, a bucket with the `explicit` schema-type requires an explicit
|
||||
|
|
@ -204,4 +213,4 @@ If you're just starting out, we recommend taking a look at the following guides:
|
|||
|
||||
For an overview of how these elements interconnect within InfluxDB's data model, watch the follwoing video:
|
||||
|
||||
{{< youtube 3qTTqsL27lI >}}
|
||||
{{< youtube 3qTTqsL27lI >}}
|
||||
|
|
|
|||
|
|
@ -14,6 +14,8 @@ aliases:
|
|||
- /influxdb/v2.1/write_protocols/line_protocol_reference/
|
||||
related:
|
||||
- /influxdb/v2.1/write-data/
|
||||
- /influxdb/v2.1/reference/key-concepts/data-elements/
|
||||
- /influxdb/v2.1/write-data/best-practices/schema-design/
|
||||
---
|
||||
|
||||
InfluxDB uses line protocol to write data points.
|
||||
|
|
@ -26,25 +28,38 @@ It is a text-based format that provides the measurement, tag set, field set, and
|
|||
- [Comments](#comments)
|
||||
- [Naming restrictions](#naming-restrictions)
|
||||
- [Duplicate points](#duplicate-points)
|
||||
- [Out of range values](#out-of-range-values)
|
||||
- [Parse errors](#parse-errors)
|
||||
|
||||
```js
|
||||
// Syntax
|
||||
#### Syntax
|
||||
|
||||
```py
|
||||
# Line protocol syntax
|
||||
<measurement>[,<tag_key>=<tag_value>[,<tag_key>=<tag_value>]] <field_key>=<field_value>[,<field_key>=<field_value>] [<timestamp>]
|
||||
```
|
||||
#### Example
|
||||
|
||||
// Example
|
||||
```py
|
||||
# Line protocol example
|
||||
myMeasurement,tag1=value1,tag2=value2 fieldKey="fieldValue" 1556813561098000000
|
||||
```
|
||||
|
||||
Lines separated by the newline character `\n` represent a single point
|
||||
in InfluxDB. Line protocol is whitespace sensitive.
|
||||
## Lines
|
||||
|
||||
{{% note %}}
|
||||
Line protocol does not support the newline character `\n` in tag or field values.
|
||||
{{% /note %}}
|
||||
Line protocol consists of zero or more entries, each terminated by the newline character (`\n`).
|
||||
A line contains one of the following:
|
||||
- [data point](#elements-of-line-protocol) that represents a [point](/influxdb/v2.1/reference/key-concepts/data-elements) in InfluxDB
|
||||
- blank line that consists entirely of [whitespace](#whitespace)
|
||||
- [comment](#comments) that starts with `#` optionally preceded by whitespace.
|
||||
|
||||
Line protocol is [whitespace-sensitive](#whitespace).
|
||||
Line protocol string elements may support certain [special characters](#special-characters).
|
||||
|
||||
## Elements of line protocol
|
||||
|
||||
```
|
||||
Lines that represent data points contain a [measurement name](#measurement), optional [tags](#tag-set), at least one [field](#field-set), and an optional [timestamp](#timestamp).
|
||||
|
||||
```js
|
||||
measurementName,tagKey=tagValue fieldKey="fieldValue" 1465839830100400200
|
||||
--------------- --------------- --------------------- -------------------
|
||||
| | | |
|
||||
|
|
@ -52,6 +67,7 @@ measurementName,tagKey=tagValue fieldKey="fieldValue" 1465839830100400200
|
|||
```
|
||||
|
||||
### Measurement
|
||||
|
||||
({{< req >}})
|
||||
The measurement name.
|
||||
InfluxDB accepts one measurement per point.
|
||||
|
|
@ -59,11 +75,17 @@ _Measurement names are case-sensitive and subject to [naming restrictions](#nami
|
|||
|
||||
_**Data type:** [String](#string)_
|
||||
|
||||
{{% note %}}
|
||||
|
||||
To learn more about designing efficient measurements for InfluxDB, see [best practices for schema design](/influxdb/v2.1/write-data/best-practices/schema-design/).
|
||||
|
||||
{{% /note %}}
|
||||
|
||||
### Tag set
|
||||
|
||||
_**Optional**_ –
|
||||
All tag key-value pairs for the point.
|
||||
Key-value relationships are denoted with the `=` operand.
|
||||
All [tag](/influxdb/v2.1/reference/key-concepts/data-elements/#tags) key-value pairs for the point.
|
||||
Key-value relationships are denoted by the `=` operand.
|
||||
Multiple tag key-value pairs are comma-delimited.
|
||||
_Tag keys and tag values are case-sensitive.
|
||||
Tag keys are subject to [naming restrictions](#naming-restrictions)._
|
||||
|
|
@ -71,9 +93,28 @@ Tag keys are subject to [naming restrictions](#naming-restrictions)._
|
|||
_**Key data type:** [String](#string)_
|
||||
_**Value data type:** [String](#string)_
|
||||
|
||||
#### Canonical form
|
||||
|
||||
**Canonical form** describes a [tag set](/influxdb/v2.1/reference/key-concepts/data-elements/#tag-set) in which the tags' decoded values are in lexical order, lowest to highest.
|
||||
Line protocol consumers are often more efficient at decoding points with tags in canonical form.
|
||||
|
||||
The data point in the following example has a tag set in canonical form:
|
||||
|
||||
```py
|
||||
# The tag set below is in canonical form.
|
||||
foo,a\ b=x,aB=y value=99
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
|
||||
To learn more about designing efficient tags for InfluxDB, see [best practices for schema design](/influxdb/v2.1/write-data/best-practices/schema-design/).
|
||||
|
||||
{{% /note %}}
|
||||
|
||||
### Field set
|
||||
|
||||
({{< req >}})
|
||||
All field key-value pairs for the point.
|
||||
All [field](/influxdb/v2.1/reference/key-concepts/data-elements/#fields) key-value pairs for the point.
|
||||
Points must have at least one field.
|
||||
_Field keys and string values are case-sensitive.
|
||||
Field keys are subject to [naming restrictions](#naming-restrictions)._
|
||||
|
|
@ -82,35 +123,51 @@ _**Key data type:** [String](#string)_
|
|||
_**Value data type:** [Float](#float) | [Integer](#integer) | [UInteger](#uinteger) | [String](#string) | [Boolean](#boolean)_
|
||||
|
||||
{{% note %}}
|
||||
_Always double quote string field values. More on quotes [below](#quotes)._
|
||||
|
||||
```sh
|
||||
measurementName fieldKey="field string value" 1556813561098000000
|
||||
Always double quote string field values. Learn more about using [quotes in line protocol](#quotes).
|
||||
|
||||
```py
|
||||
measurementName fieldKey="string field value" 1556813561098000000
|
||||
measurementName fieldKey="\"quoted words\" in a string field value" 1556813561098000000
|
||||
```
|
||||
|
||||
{{% /note %}}
|
||||
|
||||
{{% note %}}
|
||||
|
||||
To learn more about designing efficient fields for InfluxDB, see [best practices for schema design](/influxdb/v2.1/write-data/best-practices/schema-design/).
|
||||
|
||||
{{% /note %}}
|
||||
|
||||
### Timestamp
|
||||
|
||||
_**Optional**_ –
|
||||
The [unix timestamp](/influxdb/v2.1/reference/glossary/#unix-timestamp) for the data point.
|
||||
Unix timestamp for the data point.
|
||||
InfluxDB accepts one timestamp per point.
|
||||
If no timestamp is provided, InfluxDB uses the system time (UTC) of its host machine.
|
||||
|
||||
If no timestamp is provided, InfluxDB uses the system time (UTC) of its host machine. To ensure a data point includes the time a metric is observed (not received by InfluxDB), include the timestamp.
|
||||
|
||||
Nanoseconds is the default precision for timestamps. If your timestamps are not in nanoseconds, specify the precision when [writing the data to InfluxDB](/influxdb/v2.1/write-data/#timestamp-precision).
|
||||
|
||||
_**Data type:** [Unix timestamp](#unix-timestamp)_
|
||||
|
||||
{{% note %}}
|
||||
#### Important notes about timestamps
|
||||
- To ensure a data point includes the time a metric is observed (not received by InfluxDB),
|
||||
include the timestamp.
|
||||
- If your timestamps are not in nanoseconds, specify the precision of your timestamps
|
||||
when [writing the data to InfluxDB](/influxdb/v2.1/write-data/#timestamp-precision).
|
||||
{{% /note %}}
|
||||
#### Example
|
||||
|
||||
```py
|
||||
myMeasurementName fieldKey="fieldValue" 1556813561098000000
|
||||
-------------------
|
||||
|
|
||||
Timestamp
|
||||
```
|
||||
|
||||
### Whitespace
|
||||
Whitespace in line protocol determines how InfluxDB interprets the data point.
|
||||
The **first unescaped space** delimits the measurement and the tag set from the field set.
|
||||
The **second unescaped space** delimits the field set from the timestamp.
|
||||
|
||||
```
|
||||
Whitespace in line protocol determines how InfluxDB interprets the data point.
|
||||
Allowed whitespace characters are regular spaces (` `) and carriage-returns (`\r`). Carriage-returns (`\r`) are only allowed as whitespace when they immediately precede a newline (`\n`).
|
||||
The **first unescaped space** after the start of the measurement delimits the [measurement](#measurement) and the [tag set](#tag-set) from the [field set](#field-set).
|
||||
The **second unescaped space** delimits the field set from the [timestamp](#timestamp).
|
||||
|
||||
```js
|
||||
measurementName,tagKey=tagValue fieldKey="fieldValue" 1465839830100400200
|
||||
| |
|
||||
1st space 2nd space
|
||||
|
|
@ -118,19 +175,30 @@ measurementName,tagKey=tagValue fieldKey="fieldValue" 1465839830100400200
|
|||
|
||||
## Data types and format
|
||||
|
||||
### Float
|
||||
IEEE-754 64-bit floating-point numbers.
|
||||
Default numerical type.
|
||||
_InfluxDB supports scientific notation in float field values._
|
||||
### Character set
|
||||
|
||||
##### Float field value examples
|
||||
```js
|
||||
Line protocol is composed of Unicode characters encoded in UTF-8. Non-printable ASCII characters (0x00 - 0x1f and 0x7f) are not allowed.
|
||||
|
||||
### Float
|
||||
|
||||
64-bit floating-point numbers. Note that non-finite numbers (NaN and Inf) are not allowed.
|
||||
Default numerical type.
|
||||
|
||||
#### Float field value examples
|
||||
|
||||
```py
|
||||
myMeasurement fieldKey=1.0
|
||||
myMeasurement fieldKey=1
|
||||
myMeasurement fieldKey=-1.234456e+78
|
||||
```
|
||||
|
||||
InfluxDB supports scientific notation in float field values.
|
||||
|
||||
```py
|
||||
myMeasurement fieldKey=-1.234456e+78
|
||||
|
||||
```
|
||||
### Integer
|
||||
|
||||
Signed 64-bit integers.
|
||||
Trailing `i` on the number specifies an integer.
|
||||
|
||||
|
|
@ -138,14 +206,16 @@ Trailing `i` on the number specifies an integer.
|
|||
| --------------- | --------------- |
|
||||
| `-9223372036854775808i` | `9223372036854775807i` |
|
||||
|
||||
##### Integer field value examples
|
||||
```js
|
||||
#### Integer field value examples
|
||||
|
||||
```py
|
||||
myMeasurement fieldKey=1i
|
||||
myMeasurement fieldKey=12485903i
|
||||
myMeasurement fieldKey=-12485903i
|
||||
```
|
||||
|
||||
### UInteger
|
||||
|
||||
Unsigned 64-bit integers.
|
||||
Trailing `u` on the number specifies an unsigned integer.
|
||||
|
||||
|
|
@ -153,23 +223,27 @@ Trailing `u` on the number specifies an unsigned integer.
|
|||
| ---------------- | ---------------- |
|
||||
| `0u` | `18446744073709551615u` |
|
||||
|
||||
##### UInteger field value examples
|
||||
```js
|
||||
#### UInteger field value examples
|
||||
|
||||
```py
|
||||
myMeasurement fieldKey=1u
|
||||
myMeasurement fieldKey=12485903u
|
||||
```
|
||||
|
||||
### String
|
||||
Plain text string.
|
||||
Length limit 64KB.
|
||||
|
||||
##### String example
|
||||
```sh
|
||||
Plain text string.
|
||||
Length limit is 1.8432MB. 64K is the recommended length limit.
|
||||
|
||||
#### String example
|
||||
|
||||
```py
|
||||
# String measurement name, field key, and field value
|
||||
myMeasurement fieldKey="this is a string"
|
||||
```
|
||||
|
||||
### Boolean
|
||||
|
||||
Stores `true` or `false` values.
|
||||
|
||||
| Boolean value | Accepted syntax |
|
||||
|
|
@ -177,8 +251,9 @@ Stores `true` or `false` values.
|
|||
| True | `t`, `T`, `true`, `True`, `TRUE` |
|
||||
| False | `f`, `F`, `false`, `False`, `FALSE` |
|
||||
|
||||
##### Boolean field value examples
|
||||
```js
|
||||
#### Boolean field value examples
|
||||
|
||||
```py
|
||||
myMeasurement fieldKey=true
|
||||
myMeasurement fieldKey=false
|
||||
myMeasurement fieldKey=t
|
||||
|
|
@ -188,55 +263,73 @@ myMeasurement fieldKey=FALSE
|
|||
```
|
||||
|
||||
{{% note %}}
|
||||
|
||||
Do not quote boolean field values.
|
||||
Quoted field values are interpreted as strings.
|
||||
|
||||
{{% /note %}}
|
||||
|
||||
### Unix timestamp
|
||||
Unix timestamp in a [specified precision](/influxdb/v2.1/reference/glossary/#unix-timestamp).
|
||||
Default precision is nanoseconds (`ns`).
|
||||
|
||||
[Unix timestamp](/influxdb/v2.1/reference/glossary/#unix-timestamp) within the range `1677-09-21T00:12:43.145224194Z` to `2262-04-11T23:47:16.854775806Z` (i.e., almost the range of a 64-bit signed integer when expressed as nanoseconds from the epoch, but with a few nanoseconds removed at either end to allow for sentinel values).
|
||||
|
||||
| Minimum timestamp | Maximum timestamp |
|
||||
| ----------------- | ----------------- |
|
||||
| `-9223372036854775806` | `9223372036854775806` |
|
||||
|
||||
##### Unix timestamp example
|
||||
```js
|
||||
myMeasurementName fieldKey="fieldValue" 1556813561098000000
|
||||
## Special characters
|
||||
|
||||
- Line protocol supports special characters in [string elements](#string).
|
||||
- Line protocol supports both literal backslashes and backslashes as an escape character.
|
||||
|
||||
The following contexts require [escaping](#escaping-backslashes) certain characters with a backslash (`\`):
|
||||
|
||||
### Escaping rules
|
||||
|
||||
| Escape sequence | Supported in elements |
|
||||
|:----------------|:----------------------|
|
||||
| `\n` is replaced with `U+000A` (newline) | string field values |
|
||||
| `\r` is replaced with `U+000D` (carriage-return) | string field values |
|
||||
| `\t` is replaced with `U+0009` (tab) | string field values |
|
||||
| `\ ` is replaced with `U+0020` (space) | all except string field values |
|
||||
| `\,` is replaced with `,` | all except string field values |
|
||||
| `\=` is replaced with `=` | all except string field values and measurements |
|
||||
| `\”` is replaced with `”` | string field values |
|
||||
| `\\` is replaced with `\` | string field values |
|
||||
|
||||
To unescape a character within a backslash escape sequence, InfluxDB removes _the last backslash_ and its following character and replaces them with the replacement character.
|
||||
If the backslash is followed by a character that the line protocol element doesn't support, InfluxDB leaves the backslash and the following character in place, unchanged.
|
||||
|
||||
The [escaping rules](#escaping-rules) imply the following for [tag keys](/influxdb/v2.1/reference/glossary/#tag-key), [tag values](/influxdb/v2.1/reference/glossary/#tag-value), [field keys](/influxdb/v2.1/reference/glossary/#field-key), and [measurements](/influxdb/v2.1/reference/glossary/#measurement):
|
||||
- they cannot end with a backslash (`\`).
|
||||
- they accept double quote (`"`) and single quote (`'`) characters as part of the name, key, or value.
|
||||
|
||||
In _string_ [field values](/influxdb/v2.1/reference/glossary/#field-value) with two contiguous backslashes, the first backslash is interpreted as an escape character.
|
||||
|
||||
Given the following line protocol:
|
||||
|
||||
```py
|
||||
# Escaped = in tag value.
|
||||
# Literal backslash at start of string field value.
|
||||
# Escaped backslash at end of string field value.
|
||||
airSensor,sensor_id=TLM\=0201 desc="\=My data==\\"
|
||||
|
||||
# Measurement name with literal backslashes.
|
||||
# Escaped = in tag value.
|
||||
# Escaped \ and escaped " in string field value.
|
||||
air\\\\\Sensor,sensor_id=TLM\=0201 desc="\\\"==My data\==\\"
|
||||
```
|
||||
|
||||
## Quotes
|
||||
Line protocol supports single and double quotes as described in the following table:
|
||||
InfluxDB writes the following points:
|
||||
|
||||
| Element | Double quotes | Single quotes |
|
||||
| :------ | :------------: |:-------------: |
|
||||
| Measurement | _Limited_ <sup class="required">*</sup> | _Limited_ <sup class="required">*</sup> |
|
||||
| Tag key | _Limited_ <sup class="required">*</sup> | _Limited_ <sup class="required">*</sup> |
|
||||
| Tag value | _Limited_ <sup class="required">*</sup> | _Limited_ <sup class="required">*</sup> |
|
||||
| Field key | _Limited_ <sup class="required">*</sup> | _Limited_ <sup class="required">*</sup> |
|
||||
| Field value | **Strings only** | Never |
|
||||
| Timestamp | Never | Never |
|
||||
| _measurement | _sensor_id | _field | _value |
|
||||
|:-----------------|------------|------------|--------|
|
||||
| `airSensor` | `TLM=0201` | `desc` | `\=My data==\` |
|
||||
| `air\\\\\Sensor` | `TLM=0201` | `desc` | `\"==My data\==\` |
|
||||
|
||||
<sup class="required">\*</sup> _Line protocol accepts double and single quotes in
|
||||
measurement names, tag keys, tag values, and field keys, but interprets them as
|
||||
part of the name, key, or value._
|
||||
#### Examples of special characters in line protocol
|
||||
|
||||
## Special Characters
|
||||
Line protocol supports special characters in [string elements](#string).
|
||||
In the following contexts, it requires escaping certain characters with a backslash (`\`):
|
||||
|
||||
| Element | Escape characters |
|
||||
|:------- |:----------------- |
|
||||
| Measurement | Comma, Space |
|
||||
| Tag key | Comma, Equals Sign, Space |
|
||||
| Tag value | Comma, Equals Sign, Space |
|
||||
| Field key | Comma, Equals Sign, Space |
|
||||
| Field value | Double quote, Backslash |
|
||||
|
||||
You do not need to escape other special characters.
|
||||
|
||||
##### Examples of special characters in line protocol
|
||||
```sh
|
||||
```py
|
||||
# Measurement name with spaces
|
||||
my\ Measurement fieldKey="string value"
|
||||
|
||||
|
|
@ -246,39 +339,53 @@ myMeasurement fieldKey="\"string\" within a string"
|
|||
# Tag keys and values with spaces
|
||||
myMeasurement,tag\ Key1=tag\ Value1,tag\ Key2=tag\ Value2 fieldKey=100
|
||||
|
||||
# Measurement name and tag key with quotes
|
||||
joe'smeasurement,pat'sTag=tag1 fieldKey=100
|
||||
|
||||
# Emojis
|
||||
myMeasurement,tagKey=🍭 fieldKey="Launch 🚀" 1556813561098000000
|
||||
```
|
||||
|
||||
### Escaping backslashes
|
||||
Line protocol supports both literal backslashes and backslashes as an escape character.
|
||||
With two contiguous backslashes, the first is interpreted as an escape character.
|
||||
For example:
|
||||
|
||||
| Backslashes | Interpreted as |
|
||||
|:-----------:|:-------------:|
|
||||
| `\` | `\` |
|
||||
| `\\` | `\` |
|
||||
| `\\\` | `\\` |
|
||||
| `\\\\` | `\\` |
|
||||
| `\\\\\` | `\\\` |
|
||||
| `\\\\\\` | `\\\` |
|
||||
|
||||
## Comments
|
||||
Line protocol interprets `#` at the beginning of a line as a comment character
|
||||
|
||||
If a line contains `#` as the first non-whitespace character, line protocol interprets it as a comment
|
||||
and ignores all subsequent characters until the next newline `\n`.
|
||||
|
||||
```sh
|
||||
```py
|
||||
# This is a comment
|
||||
myMeasurement fieldKey="string value" 1556813561098000000
|
||||
```
|
||||
|
||||
## Naming restrictions
|
||||
Measurement names, tag keys, and field keys cannot begin with an underscore `_`.
|
||||
The `_` namespace is reserved for InfluxDB system use.
|
||||
|
||||
InfluxDB reserves the underscore (`_`) namespace and certain words for system use.
|
||||
- Measurement names, tag keys, and field keys cannot begin with an underscore (`_`).
|
||||
- Tag keys and tag values cannot end with a backslash (`\`).
|
||||
- Tag keys and field keys cannot be named `time`.
|
||||
- Tag keys cannot be named `field`.
|
||||
|
||||
To make your schema easier to query, [avoid using Flux keywords and special characters](/influxdb/v2.1/write-data/best-practices/schema-design/#keep-keys-simple) in keys.
|
||||
|
||||
## Duplicate points
|
||||
|
||||
A point is uniquely identified by the measurement name, tag set, and timestamp.
|
||||
If you submit line protocol with the same measurement, tag set, and timestamp,
|
||||
but with a different field set, the field set becomes the union of the old
|
||||
field set and the new field set, where any conflicts favor the new field set.
|
||||
|
||||
See how InfluxDB [handles duplicate points](/influxdb/v2.1/write-data/best-practices/duplicate-points/).
|
||||
|
||||
## Out of range values
|
||||
|
||||
Fields can contain numeric values, which have the potential for falling outside supported ranges.
|
||||
Integer and float values should be considered **out of range** if they can't fit within a 64-bit value of the appropriate type. Out of range values may cause [parsing errors](#parsing-errors).
|
||||
|
||||
For detail about supported ranges, see the minimum and maximum values for [data types](#data-types-and-format).
|
||||
|
||||
## Parse errors
|
||||
|
||||
When a line protocol decoder encounters an invalid line, tag, or field (e.g., with an [out-of-range value](#out-of-range-values)),
|
||||
the decoder may choose to recover from the error by ignoring the offending value or it may fail the decoding.
|
||||
One common approach to handling syntax errors is for the decoder to recover by discarding data until the next newline character and then resume parsing.
|
||||
|
||||
See [how to troubleshoot issues writing data](/influxdb/v2.1/write-data/troubleshoot/) to InfluxDB.
|
||||
|
|
|
|||
|
|
@ -20,14 +20,14 @@ Take steps to understand and resolve high series cardinality.
|
|||
|
||||
{{% oss-only %}}
|
||||
|
||||
IndexDB indexes the following data elements to speed up reads:
|
||||
InfluxDB indexes the following data elements to speed up reads:
|
||||
- [measurement](/influxdb/v2.1/reference/glossary/#measurement)
|
||||
- [tags](/influxdb/v2.1/reference/glossary/#tag)
|
||||
|
||||
{{% /oss-only %}}
|
||||
{{% cloud-only %}}
|
||||
|
||||
IndexDB indexes the following data elements to speed up reads:
|
||||
InfluxDB indexes the following data elements to speed up reads:
|
||||
- [measurement](/influxdb/v2.1/reference/glossary/#measurement)
|
||||
- [tags](/influxdb/v2.1/reference/glossary/#tag)
|
||||
- [field keys](/influxdb/cloud/reference/glossary/#field-key)
|
||||
|
|
|
|||
|
|
@ -134,10 +134,16 @@ In addition to keeping your keys free of data, follow these additional guideline
|
|||
|
||||
##### Avoid keywords and special characters in keys
|
||||
|
||||
To simplify query writing, don't include reserved keywords or special characters in tag and field keys.
|
||||
To simplify query writing, don't include Flux keywords or special characters in tag and field keys.
|
||||
If you use [Flux keywords](/{{< latest "flux" >}}/spec/lexical-elements/#keywords) in keys,
|
||||
then you'll have to wrap the keys in double quotes.
|
||||
If you use non-alphanumeric characters in keys, then you'll have to use [bracket notation](/{{< latest "flux" >}}/data-types/composite/record/#bracket-notation) in [Flux]((/{{< latest "flux" >}}/).
|
||||
If you use non-alphanumeric characters in keys, then you'll have to use [bracket notation](/{{< latest "flux" >}}/data-types/composite/record/#bracket-notation) in [Flux](/{{< latest "flux" >}}/).
|
||||
|
||||
{{% warn %}}
|
||||
|
||||
InfluxDB doesn't allow writing points that use the following **reserved tag keys**: `time`, `field`, `_measurement`.
|
||||
|
||||
{{% /warn %}}
|
||||
|
||||
##### Avoid duplicate names for tags and fields
|
||||
|
||||
|
|
@ -158,6 +164,12 @@ Use [explicit bucket schemas]() to enforce unique tag and field keys within a sc
|
|||
This means that querying tags is more performant than querying fields.
|
||||
Your queries should guide what you store in tags and what you store in fields.
|
||||
|
||||
{{% note %}}
|
||||
|
||||
For more information about indexing and query performance, see how to [resolve high series cardinality](/influxdb/v2.1/write-data/best-practices/resolve-high-cardinality/).
|
||||
|
||||
{{% /note %}}
|
||||
|
||||
### Use fields for unique and numeric data
|
||||
|
||||
- Store unique or frequently changing values as field values.
|
||||
|
|
@ -249,4 +261,4 @@ from(bucket:"example-bucket")
|
|||
|
||||
For an overview of the InfluxDB data model, watch the following video:
|
||||
|
||||
{{< youtube 3qTTqsL27lI >}}
|
||||
{{< youtube 3qTTqsL27lI >}}
|
||||
|
|
|
|||
Loading…
Reference in New Issue