From 5d275bdc0326b7d09a7408c927a065bfda570b5d Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 11 Feb 2022 13:12:10 -0600 Subject: [PATCH] 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 * 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 Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> --- .../reference/key-concepts/data-elements.md | 43 ++- .../v2.1/reference/syntax/line-protocol.md | 301 ++++++++++++------ .../resolve-high-cardinality.md | 4 +- .../best-practices/schema-design.md | 18 +- 4 files changed, 247 insertions(+), 119 deletions(-) diff --git a/content/influxdb/v2.1/reference/key-concepts/data-elements.md b/content/influxdb/v2.1/reference/key-concepts/data-elements.md index dd75ef882..867dc56d3 100644 --- a/content/influxdb/v2.1/reference/key-concepts/data-elements.md +++ b/content/influxdb/v2.1/reference/key-concepts/data-elements.md @@ -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 >}} \ No newline at end of file +{{< youtube 3qTTqsL27lI >}} diff --git a/content/influxdb/v2.1/reference/syntax/line-protocol.md b/content/influxdb/v2.1/reference/syntax/line-protocol.md index 8e3c4b026..722acb008 100644 --- a/content/influxdb/v2.1/reference/syntax/line-protocol.md +++ b/content/influxdb/v2.1/reference/syntax/line-protocol.md @@ -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 [,=[,=]] =[,=] [] +``` +#### 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_ * | _Limited_ * | -| Tag key | _Limited_ * | _Limited_ * | -| Tag value | _Limited_ * | _Limited_ * | -| Field key | _Limited_ * | _Limited_ * | -| 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\==\` | -\* _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. diff --git a/content/influxdb/v2.1/write-data/best-practices/resolve-high-cardinality.md b/content/influxdb/v2.1/write-data/best-practices/resolve-high-cardinality.md index 09030107f..d8a3a51e6 100644 --- a/content/influxdb/v2.1/write-data/best-practices/resolve-high-cardinality.md +++ b/content/influxdb/v2.1/write-data/best-practices/resolve-high-cardinality.md @@ -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) diff --git a/content/influxdb/v2.1/write-data/best-practices/schema-design.md b/content/influxdb/v2.1/write-data/best-practices/schema-design.md index 8ed79c535..f101df89b 100644 --- a/content/influxdb/v2.1/write-data/best-practices/schema-design.md +++ b/content/influxdb/v2.1/write-data/best-practices/schema-design.md @@ -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 >}} \ No newline at end of file +{{< youtube 3qTTqsL27lI >}}