diff --git a/assets/styles/layouts/article/_html-diagrams.scss b/assets/styles/layouts/article/_html-diagrams.scss index 5d2cedd9c..edd7240a0 100644 --- a/assets/styles/layouts/article/_html-diagrams.scss +++ b/assets/styles/layouts/article/_html-diagrams.scss @@ -322,6 +322,7 @@ table tr.point{ } } + &.v3 {p span.measurement::before{content: "table";}} &.hide-elements {p span.el { border: none; &:before, &:after {display: none}}} &.hide-commas {p span.comma { border: none; &:before, &:after {display: none}}} &.hide-whitespace {p span.whitespace { border: none; &:before, &:after {display: none}}} diff --git a/content/influxdb3/core/reference/line-protocol.md b/content/influxdb3/core/reference/line-protocol.md new file mode 100644 index 000000000..3c94bcc65 --- /dev/null +++ b/content/influxdb3/core/reference/line-protocol.md @@ -0,0 +1,21 @@ +--- +title: Line protocol reference +description: > + InfluxDB 3 Core uses line protocol to write data points. + It is a text-based format that provides the table, tag set, field set, and timestamp of a data point. +menu: + influxdb3_core: + name: Line protocol + parent: Reference +weight: 101 +influxdb3/core/tags: [write, line protocol, syntax] +related: + - /influxdb3/core/write-data/ +aliases: + - /influxdb3/core/reference/syntax/line-protocol +source: /shared/v3-line-protocol.md +--- + +<!-- +The content of this file is at content/shared/v3-line-protocol.md +--> diff --git a/content/influxdb3/enterprise/reference/line-protocol.md b/content/influxdb3/enterprise/reference/line-protocol.md new file mode 100644 index 000000000..85b5b0295 --- /dev/null +++ b/content/influxdb3/enterprise/reference/line-protocol.md @@ -0,0 +1,21 @@ +--- +title: Line protocol reference +description: > + InfluxDB 3 Enterprise uses line protocol to write data points. + It is a text-based format that provides the table, tag set, field set, and timestamp of a data point. +menu: + influxdb3_enterprise: + name: Line protocol + parent: Reference +weight: 101 +influxdb3/enterprise/tags: [write, line protocol, syntax] +related: + - /influxdb3/enterprise/write-data/ +aliases: + - /influxdb3/enterprise/reference/syntax/line-protocol +source: /shared/v3-line-protocol.md +--- + +<!-- +The content of this file is at content/shared/v3-line-protocol.md +--> diff --git a/content/shared/v3-line-protocol.md b/content/shared/v3-line-protocol.md new file mode 100644 index 000000000..63e0c94a2 --- /dev/null +++ b/content/shared/v3-line-protocol.md @@ -0,0 +1,288 @@ +<!-- --> +{{< product-name >}} uses line protocol to write data points. +It is a text-based format that provides the table, tag set, field set, and +timestamp of a data point. + +- [Elements of line protocol](#elements-of-line-protocol) +- [Data types and format](#data-types-and-format) +- [Quotes](#quotes) +- [Special characters](#special-characters) +- [Comments](#comments) +- [Naming restrictions](#naming-restrictions) +- [Duplicate points](#duplicate-points) + +```js +// Syntax +<table>[,<tag_key>=<tag_value>[,<tag_key>=<tag_value>]] <field_key>=<field_value>[,<field_key>=<field_value>] [<timestamp>] + +// Example +myTable,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. + +{{% note %}} +Line protocol does not support the newline character `\n` in tag or field values. +{{% /note %}} + +## Elements of line protocol + +{{< influxdb/line-protocol commas=false whitespace=false version="v3" >}} + +### Table + +({{< req >}}) +The table name. +InfluxDB accepts one table per point. +_Table names are case-sensitive and subject to [naming restrictions](#naming-restrictions)._ + +_**Data type:** [String](#string)_ + +> [!Note] +> If familiar with previous InfluxDB versions, "**table**" is synonymous with +> "**measurement**." + +### Tag set + +_**Optional**_ – +All tag key-value pairs for the point. +Key-value relationships are denoted with 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). +Tag values cannot be empty; instead, omit the tag from the tag set._ + +_**Key data type:** [String](#string)_ +_**Value data type:** [String](#string)_ + +### Field set + +({{< req >}}) +All field 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)._ + +_**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 +tableName fieldKey="field string value" 1556813561098000000 +``` +{{% /note %}} + +### Timestamp + +_**Optional**_ – +The [unix timestamp](/influxdb3/version/reference/glossary/#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. + +_**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 {{< product-name >}}. +{{% /note %}} + +### Whitespace + +Whitespace in line protocol determines how InfluxDB interprets the data point. +The **first unescaped space** delimits the table and the tag set from the field set. +The **second unescaped space** delimits the field set from the timestamp. + +{{< influxdb/line-protocol elements=false commas=false version="v3" >}} + +## Data types and format + +### Float + +IEEE-754 64-bit floating-point numbers. +Default numerical type. +_InfluxDB supports scientific notation in float field values._ + +##### Float field value examples + +```js +myTable fieldKey=1.0 +myTable fieldKey=1 +myTable fieldKey=-1.234456e+78 +``` + +### Integer + +Signed 64-bit integers. +Trailing `i` on the number specifies an integer. + +| Minimum integer | Maximum integer | +| --------------- | --------------- | +| `-9223372036854775808i` | `9223372036854775807i` | + +##### Integer field value examples + +```js +myTable fieldKey=1i +myTable fieldKey=12485903i +myTable fieldKey=-12485903i +``` + +### UInteger + +Unsigned 64-bit integers. +Trailing `u` on the number specifies an unsigned integer. + +| Minimum uinteger | Maximum uinteger | +| ---------------- | ---------------- | +| `0u` | `18446744073709551615u` | + +##### UInteger field value examples + +```js +myTable fieldKey=1u +myTable fieldKey=12485903u +``` + +### String + +Plain text string. +Length limit 64KB. + +##### String example + +```sh +# String table name, field key, and field value +myTable fieldKey="this is a string" +``` + +### Boolean + +Stores `true` or `false` values. + +| Boolean value | Accepted syntax | +|:-------------:|:--------------- | +| True | `t`, `T`, `true`, `True`, `TRUE` | +| False | `f`, `F`, `false`, `False`, `FALSE` | + +##### Boolean field value examples + +```js +myTable fieldKey=true +myTable fieldKey=false +myTable fieldKey=t +myTable fieldKey=f +myTable fieldKey=TRUE +myTable 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](/influxdb3/version/reference/glossary/#unix-timestamp). +Default precision is nanoseconds (`ns`). + +| Minimum timestamp | Maximum timestamp | +| ----------------- | ----------------- | +| `-9223372036854775806` | `9223372036854775806` | + +##### Unix timestamp example + +```js +myTableName fieldKey="fieldValue" 1556813561098000000 +``` + +## Quotes + +Line protocol supports single and double quotes as described in the following table: + +| Element | Double quotes | Single quotes | +| :---------- | :-------------------------------------: | :-------------------------------------: | +| Table | _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 | + +<sup class="required">\*</sup> _Line protocol accepts double and single quotes in +table names, tag keys, tag values, and field keys, but interprets them as +part of the name, key, or value._ + +## 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 | +| :---------- | :------------------------ | +| Table | 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 +# Table name with spaces +my\ Table fieldKey="string value" + +# Double quotes in a string field value +myTable fieldKey="\"string\" within a string" + +# Tag keys and values with spaces +myTable,tag\ Key1=tag\ Value1,tag\ Key2=tag\ Value2 fieldKey=100 + +# Emojis +myTable,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 +and ignores all subsequent characters until the next newline `\n`. + +```sh +# This is a comment +myTable fieldKey="string value" 1556813561098000000 +``` + +## Naming restrictions + +Table names, tag keys, and field keys are alphanumeric and must begin with a +letter or a number. They can contain dashes (`-`) and underscores (`_`). + +## Duplicate points + +A point is uniquely identified by the table name, tag set, and timestamp. +If you submit line protocol with the same table, 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. diff --git a/layouts/shortcodes/influxdb/line-protocol.html b/layouts/shortcodes/influxdb/line-protocol.html index f04f591ca..b4bb0dcf7 100644 --- a/layouts/shortcodes/influxdb/line-protocol.html +++ b/layouts/shortcodes/influxdb/line-protocol.html @@ -1,9 +1,12 @@ {{- $includeElements := .Get "elements" | default true -}} {{- $includeCommas := .Get "commas" | default true -}} {{- $includeWhitespace := .Get "whitespace" | default true -}} -<div id="line-protocol-anatomy" class="{{ if not $includeElements }}hide-elements {{ end }}{{ if not $includeCommas }}hide-commas {{ end }}{{ if not $includeWhitespace }}hide-whitespace{{ end }}"> +{{- $version := .Get "version" | default "v2" -}} +{{- $isV3 := eq $version "v3" -}} +{{- $storageName := cond $isV3 "table" "measurement" -}} +<div id="line-protocol-anatomy" class="{{ if not $includeElements }}hide-elements {{ end }}{{ if not $includeCommas }}hide-commas {{ end }}{{ if not $includeWhitespace }}hide-whitespace{{ end }} {{ $version }}"> <p> - <span class="el measurement">measurement</span><span class="comma">,</span><span class="el tagset">tag1=val1,tag2=val2</span><span class="whitespace" data-whitespace="1st"> </span> + <span class="el measurement">my{{ title $storageName }}</span><span class="comma">,</span><span class="el tagset">tag1=val1,tag2=val2</span><span class="whitespace" data-whitespace="1st"> </span> <span class="el fieldset">field1="v1",field2=1i</span><span class="whitespace" data-whitespace="2nd"> </span><span class="el timestamp">0000000000000000000</span> </p> </div> \ No newline at end of file