diff --git a/.prettierrc.yaml b/.prettierrc.yaml index a0af81adc..d8d912cab 100644 --- a/.prettierrc.yaml +++ b/.prettierrc.yaml @@ -7,8 +7,11 @@ trailingComma: "es5" useTabs: false overrides: - files: - - "*.md" - - "*.markdown" + - "*.md" + - "*.markdown" options: proseWrap: "preserve" +plugins: + - "prettier-plugin-sql" + # Prettier also uses settings, such as indent, specified in .editorconfig \ No newline at end of file diff --git a/content/influxdb/cloud-dedicated/get-started/write.md b/content/influxdb/cloud-dedicated/get-started/write.md index 068fad1da..27e9267ba 100644 --- a/content/influxdb/cloud-dedicated/get-started/write.md +++ b/content/influxdb/cloud-dedicated/get-started/write.md @@ -69,13 +69,16 @@ Each line of line protocol contains the following elements: or [booleans](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#boolean). - **timestamp**: - [Unix timestamp](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#unix-timestamp) - associated with the data. InfluxDB supports up to nanosecond precision. _If - the precision of the timestamp is not in nanoseconds, you must specify the - precision when writing the data to InfluxDB._ +[Unix timestamp](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#unix-timestamp) +associated with the data. InfluxDB supports up to nanosecond precision. _If +the precision of the timestamp is not in nanoseconds, you must specify the +precision when writing the data to InfluxDB._ + #### Line protocol element parsing + + - **measurement**: Everything before the _first unescaped comma before the first whitespace_. - **tag set**: Key-value pairs between the _first unescaped comma_ and the @@ -98,6 +101,8 @@ _For schema design recommendations, see ## Construct line protocol + + With a basic understanding of line protocol, you can now construct line protocol and write data to InfluxDB. Consider a use case where you collect data from sensors in your home. @@ -154,7 +159,7 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 ## Write line protocol to InfluxDB -The following examples show how to write the +The following examples show how to write the preceding [sample data](#home-sensor-data-line-protocol), already in line protocol format, to an {{% product-name %}} database. @@ -235,6 +240,9 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200' {{% /code-placeholders %}} {{% /influxdb/custom-timestamps %}} +If successful, the output is the success message; otherwise, error details and +the failure message. + {{% /tab-content %}} @@ -492,7 +500,8 @@ Replace the following: a [database token](/influxdb/cloud-dedicated/admin/tokens/#database-token) with sufficient permissions to the specified database -If successful, the output is an HTTP `204 No Content` status code. +If successful, the output is an HTTP `204 No Content` status code; otherwise, +the error status code and failure message. @@ -603,7 +612,8 @@ Replace the following: [database token](/influxdb/cloud-dedicated/admin/tokens/#database-tokens) with sufficient permissions to the specified database -If successful, the output is an HTTP `204 No Content` status code. +If successful, the output is an HTTP `204 No Content` status code; otherwise, +the error status code and failure message. @@ -629,17 +639,12 @@ dependencies to your current project. 1. Create a module directory and navigate into it--for example: - - ```bash mkdir -p influxdb_py_client && cd influxdb_py_client ``` 2. Setup your Python virtual environment. - Inside of your module directory: + Inside of your module directory, enter the following command: @@ -765,6 +770,9 @@ dependencies to your current project. {{% /influxdb/custom-timestamps %}} +If successful, the output is the success message; otherwise, error details and +the failure message. + {{% /tab-content %}} @@ -940,17 +948,17 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3 } ``` -6. In your terminal, enter the following command to install the packages listed - in `imports`, build the `influxdb_go_client` module, and execute the - `main()` function: +6. To install dependencies and write the data to your {{% product-name %}} + database, enter the following command into your terminal: ```sh - go mod tidy && go build && go run influxdb_go_client + go mod tidy && go run influxdb_go_client ``` - The program writes the line protocol to your {{% product-name %}} database. +If successful, the output is the success message; otherwise, error details and +the failure message. {{% /influxdb/custom-timestamps %}} @@ -1146,6 +1154,9 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3 {{% /influxdb/custom-timestamps %}} +If successful, the output is the success message; otherwise, error details and +the failure message. + {{% /tab-content %}} @@ -1281,8 +1292,8 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3 with _write_ access to the specified database. _Store this in a secret store or environment variable to avoid exposing the raw token string._ - _Instantiating the client with the `using` statement ensures that the - client is disposed of when it's no longer needed._ + _The `using` statement ensures that the program disposes of the + client when it's no longer needed._ 2. Defines an array of line protocol strings where each string represents a data record. @@ -1324,19 +1335,23 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3 7. To build and execute the program and write the line protocol to your {{% product-name %}} database, enter the following command in your terminal: - + - ```sh - dotnet run - ``` + ```sh + dotnet run + ``` - +If successful, the output is the success message; otherwise, error details and +the failure message. - {{% /influxdb/custom-timestamps %}} - {{% /tab-content %}} - {{% tab-content %}} - {{% influxdb/custom-timestamps %}} - + + +{{% /influxdb/custom-timestamps %}} +{{% /tab-content %}} +{{% tab-content %}} +{{% influxdb/custom-timestamps %}} + + _The tutorial assumes using Maven version 3.9 and Java version >= 15._ @@ -1555,21 +1570,21 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._ 10. In your terminal or editor, execute `App.main()` to write to InfluxDB--for example, using Maven: - + - ```sh - mvn exec:java -Dexec.mainClass="com.influxdbv3.App" - ``` - - - - {{% /influxdb/custom-timestamps %}} - {{% /tab-content %}} - {{< /tabs-wrapper >}} + ```sh + mvn exec:java -Dexec.mainClass="com.influxdbv3.App" + ``` If successful, the output is the success message; otherwise, error details and the failure message. + + +{{% /influxdb/custom-timestamps %}} +{{% /tab-content %}} +{{< /tabs-wrapper >}} + {{< expand-wrapper >}} {{% expand "View the written data" %}} @@ -1610,4 +1625,5 @@ the failure message. **Congratulations!** You've written data to InfluxDB. Next, learn how to query your data. -{{< page-nav prev="/influxdb/cloud-dedicated/get-started/setup/" next="/influxdb/cloud-dedicated/get-started/query/" keepTab=true >}} +{{< page-nav prev="/influxdb/cloud-dedicated/get-started/setup/" +next="/influxdb/cloud-dedicated/get-started/query/" keepTab=true >}} diff --git a/content/influxdb/cloud-dedicated/write-data/line-protocol/_index.md b/content/influxdb/cloud-dedicated/write-data/line-protocol/_index.md index 3fb7905d3..0b974f6e0 100644 --- a/content/influxdb/cloud-dedicated/write-data/line-protocol/_index.md +++ b/content/influxdb/cloud-dedicated/write-data/line-protocol/_index.md @@ -22,15 +22,10 @@ your data to line protocol. However, if you already have CSV data, you might want to use tools that [consume CSV and write it to InfluxDB as line protocol](/influxdb/cloud-dedicated/write-data/csv/). - - - [Line protocol](#line-protocol) - [Line protocol elements](#line-protocol-elements) - - [Line protocol element parsing](#line-protocol-element-parsing) - [Write line protocol to InfluxDB](#write-line-protocol-to-influxdb) - - ## Line protocol All data written to InfluxDB is written using [line protocol](/influxdb/cloud-dedicated/reference/syntax/line-protocol/), a text-based @@ -44,7 +39,7 @@ Each line of line protocol contains the following elements: {{< req type="key" >}} -- {{< req "\*" >}} **measurement**: String that identifies the [measurement](/influxdb/cloud-dedicated/reference/glossary/#measurement) to store the data in. +- {{< req "\*" >}} **measurement**: String that identifies the [measurement](/influxdb/cloud-dedicated/reference/glossary/#measurement) to store the data in. - **tag set**: Comma-delimited list of key value pairs, each representing a tag. Tag keys and values are unquoted strings. _Spaces, commas, and equal characters must be escaped._ - {{< req "\*" >}} **field set**: Comma-delimited list of key value pairs, each representing a field. diff --git a/content/influxdb/cloud-dedicated/write-data/line-protocol/client-libraries.md b/content/influxdb/cloud-dedicated/write-data/line-protocol/client-libraries.md index f1567173c..40c40425d 100644 --- a/content/influxdb/cloud-dedicated/write-data/line-protocol/client-libraries.md +++ b/content/influxdb/cloud-dedicated/write-data/line-protocol/client-libraries.md @@ -89,8 +89,6 @@ client libraries to write data to InfluxDB v3, see {{< tabs-wrapper >}} {{% tabs %}} - - [Go](#) [Node.js](#) [Python](#) @@ -210,8 +208,6 @@ points. {{< tabs-wrapper >}} {{% tabs %}} - - [Go](#) [Node.js](#) [Python](#) diff --git a/content/influxdb/cloud-dedicated/write-data/line-protocol/influxctl-cli.md b/content/influxdb/cloud-dedicated/write-data/line-protocol/influxctl-cli.md index b2a348071..6262b0063 100644 --- a/content/influxdb/cloud-dedicated/write-data/line-protocol/influxctl-cli.md +++ b/content/influxdb/cloud-dedicated/write-data/line-protocol/influxctl-cli.md @@ -29,7 +29,7 @@ Consider a use case where you collect data from sensors in your home. Each sensor collects temperature, humidity, and carbon monoxide readings. To collect this data, use the following schema: -- **measurement**: `home` +- **measurement**: `home` - **tags** - `room`: Living Room or Kitchen - **fields** @@ -40,7 +40,7 @@ To collect this data, use the following schema: The following line protocol represent the schema described above: -``` +```text home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 @@ -66,10 +66,10 @@ to write the [home sensor sample data](#home-sensor-data-line-protocol) to your {{< product-name omit=" Clustered" >}} cluster. Provide the following: -- Database name using the `--database` flag -- [Database token](/influxdb/cloud-dedicated/admin/tokens/#database-tokens) +- The [database](/influxdb/clustered/admin/databases/) name using the `--database` flag +- A [database token](/influxdb/cloud-dedicated/admin/tokens/#database-tokens) (with write permissions on the target database) using the `--token` flag -- Timestamp precision as seconds (`s`) using the `--precision` flag +- The timestamp precision as seconds (`s`) using the `--precision` flag - [Line protocol](#construct-line-protocol). Pass the line protocol in one of the following ways: @@ -77,16 +77,17 @@ Provide the following: - a path to a file that contains the query - a single dash (`-`) to read the query from stdin -{{< code-tabs-wrapper >}} -{{% code-tabs %}} +{{< tabs-wrapper >}} +{{% tabs %}} [string](#) [file](#) [stdin](#) -{{% /code-tabs %}} -{{% code-tab-content %}} +{{% /tabs %}} +{{% tab-content %}} {{% influxdb/custom-timestamps %}} {{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}} + ```sh influxctl write \ --database DATABASE_NAME \ @@ -105,6 +106,7 @@ home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000' ``` + {{% /code-placeholders %}} {{% /influxdb/custom-timestamps %}} @@ -115,17 +117,43 @@ Replace the following: - {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: Database token with write permissions on the target database. -{{% /code-tab-content %}} -{{% code-tab-content %}} +{{% /tab-content %}} +{{% tab-content %}} {{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}} -```sh -influxctl write \ - --database DATABASE_NAME \ - --token DATABASE_TOKEN \ - --precision s \ - LINE_PROTOCOL_FILEPATH -``` + +1. In your terminal, enter the following command to create the sample data file: + + ```sh + cat < ./home.lp && LINE_PROTOCOL_FILEPATH=./home.lp + home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 + home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 + home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 + home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 + home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 + home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 + home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 + home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 + home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 + home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 + home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 + home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000 + + EOF + ``` + + + +2. Enter the following CLI command to write the data from the sample file: + + ```sh + influxctl write \ + --database DATABASE_NAME \ + --token DATABASE_TOKEN \ + --precision s \ + $LINE_PROTOCOL_FILEPATH + ``` + {{% /code-placeholders %}} Replace the following: @@ -134,21 +162,25 @@ Replace the following: Name of the database to write to. - {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: Database token with write permissions on the target database. -- {{% code-placeholder-key %}}`LINE_PROTOCOL_FILEPATH`{{% /code-placeholder-key %}}: +- {{% code-placeholder-key %}}`$LINE_PROTOCOL_FILEPATH`{{% /code-placeholder-key %}}: File path to the file containing the line protocol. Can be an absolute file path or relative to the current working directory. -{{% /code-tab-content %}} -{{% code-tab-content %}} +{{% /tab-content %}} +{{% tab-content %}} {{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}} + + + ```sh -cat LINE_PROTOCOL_FILEPATH | influxctl write \ +cat $LINE_PROTOCOL_FILEPATH | influxctl write \ --database DATABASE_NAME \ --token DATABASE_TOKEN \ --precision s \ - ``` + {{% /code-placeholders %}} Replace the following: @@ -157,9 +189,9 @@ Replace the following: Name of the database to write to. - {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: Database token with write permissions on the target database. -- {{% code-placeholder-key %}}`LINE_PROTOCOL_FILEPATH`{{% /code-placeholder-key %}}: +- {{% code-placeholder-key %}}`$LINE_PROTOCOL_FILEPATH`{{% /code-placeholder-key %}}: File path to the file containing the line protocol. Can be an absolute file path or relative to the current working directory. -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} +{{% /tab-content %}} +{{< /tabs-wrapper >}} diff --git a/content/influxdb/cloud-serverless/get-started/write.md b/content/influxdb/cloud-serverless/get-started/write.md index 0d10a786b..e1ac5e4ef 100644 --- a/content/influxdb/cloud-serverless/get-started/write.md +++ b/content/influxdb/cloud-serverless/get-started/write.md @@ -44,8 +44,6 @@ see the [Line protocol reference](/influxdb/cloud-serverless/reference/syntax/li Each line of line protocol contains the following elements: - - {{< req type="key" >}} - {{< req "\*" >}} **measurement**: String that identifies the [measurement](/influxdb/cloud-serverless/reference/glossary/#measurement) to store the data in. @@ -65,14 +63,16 @@ Each line of line protocol contains the following elements: #### Line protocol element parsing + - **measurement**: Everything before the _first unescaped comma before the first whitespace_. - **tag set**: Key-value pairs between the _first unescaped comma_ and the _first unescaped whitespace_. - **field set**: Key-value pairs between the _first and second unescaped whitespaces_. - **timestamp**: Integer value after the _second unescaped whitespace_. -- Lines are separated by the newline character (`\n`). -Line protocol is whitespace sensitive. +- Lines are separated by the newline character (`\n`). Line protocol is +whitespace sensitive. + --- @@ -84,6 +84,7 @@ _For schema design recommendations, see [InfluxDB schema design](/influxdb/cloud ## Construct line protocol + With a basic understanding of line protocol, you can now construct line protocol and write data to InfluxDB. Consider a use case where you collect data from sensors in your home. @@ -140,7 +141,7 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 ## Write line protocol to InfluxDB -The following examples show how to write the +The following examples show how to write the preceding [sample data](#home-sensor-data-line-protocol), already in line protocol format, to an {{% product-name %}} bucket. @@ -239,6 +240,8 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 ``` {{< /influxdb/custom-timestamps >}} +If successful, the output is the success message; otherwise, error details and +the failure message. {{% /tab-content %}} @@ -247,11 +250,14 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 {{< influxdb/custom-timestamps >}} -Use [Telegraf](/telegraf/v1/) to consume line protocol, and then write it to {{< product-name >}}. +Use [Telegraf](/telegraf/v1/) to consume line protocol, and then write it to +{{< product-name >}}. -1. If you haven't already, follow the instructions to [download and install Telegraf](/telegraf/v1/install/). +11. If you haven't already, follow the instructions to + [download and install Telegraf](/telegraf/v1/install/). -2. Copy and save the [home sensor data sample](#home-sensor-data-line-protocol) to a file on your local system--for example, `home.lp`. +2. Copy and save the [home sensor data sample](#home-sensor-data-line-protocol) + to a file on your local system--for example, `home.lp`. ```sh cat <<- EOF > home.lp @@ -398,12 +404,13 @@ guide. {{% /note %}} To write data to InfluxDB using the -[InfluxDB v1 HTTP API](/influxdb/cloud-serverless/reference/api/), send a -request to the +[InfluxDB v1 HTTP API](/influxdb/cloud-serverless/reference/api/), send a request +to the [InfluxDB API `/write` endpoint](/influxdb/cloud-serverless/api/#operation/PostLegacyWrite) using the `POST` request method. -{{% api-endpoint endpoint="https://{{< influxdb/host >}}/write" method="post" api-ref="/influxdb/cloud-serverless/api/#operation/PostLegacyWrite" %}} +{{% api-endpoint endpoint="https://{{< influxdb/host >}}/write" method="post" +api-ref="/influxdb/cloud-serverless/api/#operation/PostLegacyWrite"%}} Include the following with your request: @@ -485,7 +492,8 @@ _For InfluxDB to [auto-generate the DBRP mapping](/influxdb/cloud-serverless/gui [All-Access API token](/influxdb/cloud-serverless/admin/tokens/#all-access-api-token) in the write request_. -If successful, the output is an HTTP `204 No Content` status code. +If successful, the output is an HTTP `204 No Content` status code; otherwise, +the error status code and failure message. @@ -584,7 +592,7 @@ Replace the following: to the specified bucket If successful, the output is an HTTP `204 No Content` status code; otherwise, -the status code and error message. +the error status code and failure message. @@ -715,7 +723,7 @@ dependencies to your current project. - **`host`**: {{% product-name %}} region hostname (URL without protocol or trailing slash) - **`token`**: a [token](/influxdb/cloud-serverless/admin/tokens/) with - `write_ access to the specified bucket. + write access to the specified bucket. _Store this in a secret store or environment variable to avoid exposing the raw token string._ - **`database`**: the name of the {{% product-name %}} bucket to write to @@ -729,7 +737,7 @@ dependencies to your current project. [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) to seconds.** -1. To execute the module and write line protocol to your {{% product-name %}} +7. To execute the module and write line protocol to your {{% product-name %}} bucket, enter the following command in your terminal: @@ -739,6 +747,9 @@ dependencies to your current project. ``` {{% /influxdb/custom-timestamps %}} +If successful, the output is the success message; otherwise, error details and +the failure message. + {{% /tab-content %}} {{% tab-content %}} @@ -875,7 +886,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu `influxdb3.New(influxdb3.ClientConfig)` function and passes the following: - **`Host`**: your {{% product-name %}} region URL - **`Token`**: a [token](/influxdb/cloud-serverless/admin/tokens/) - with _write_ access to the specified bucket. _Store this in a + with write access to the specified bucket. _Store this in a secret store or environment variable to avoid exposing the raw token string._ - **`WriteOptions`**: `influxdb3.WriteOptions` options for writing @@ -883,7 +894,8 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu **Because the timestamps in the sample line protocol are in second precision, the example passes the `Precision: lineprotocol.Second` - option to set the [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) + option to set the + [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) to seconds.** 2. Defines a deferred function that closes the client when the function @@ -906,23 +918,26 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu } ``` -6. In your terminal, enter the following command to install the packages listed - in `imports`, build the `influxdb_go_client` module, and execute the - `main()` function: +6. To install dependencies and write the data to your {{% product-name %}} bucket, + enter the following command into your terminal: ```sh - go mod tidy && go build && go run influxdb_go_client + go mod tidy && go run influxdb_go_client ``` - The program writes the line protocol to your {{% product-name %}} bucket. +If successful, the output is the success message; otherwise, error details and +the failure message. {{% /influxdb/custom-timestamps %}} + + {{% /tab-content %}} {{% tab-content %}} {{% influxdb/custom-timestamps %}} + 1. If you haven't already, follow the instructions for @@ -1050,8 +1065,9 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu - **`host`**: your {{% product-name %}} region URL - **`token`**: a [token](/influxdb/cloud-serverless/admin/tokens/) - with _write_ access to the specified bucket. - _Store this in a secret store or environment variable to avoid exposing the raw token string._ + with write access to the specified bucket. + _Store this in a secret store or environment variable to avoid exposing + the raw token string._ 3. Defines a list of line protocol strings where each string represents a data record. @@ -1075,6 +1091,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu success and failure messages to a `writeResults` constant. 6. Iterates over and prints the messages in `writeResults`. 7. Closes the client to release resources. + 7. In your terminal or editor, create an `index.js` file. 8. Inside of `index.js`, enter the following sample code to import and call `writeLineProtocol()`: @@ -1104,6 +1121,9 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu {{% /influxdb/custom-timestamps %}} +If successful, the output is the success message; otherwise, error details and +the failure message. + {{% /tab-content %}} @@ -1126,14 +1146,15 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu ``` 3. Change into the generated `influxdb_csharp_client` directory. - + ```sh cd influxdb_csharp_client ``` -4. Run the following command to install the latest version of the InfluxDB v3 C# client library. +4. Run the following command to install the latest version of the InfluxDB v3 C# + client library. @@ -1158,7 +1179,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu /** * Writes line protocol to InfluxDB using the C# .NET client * library. - */ + */ public static async Task WriteLines() { // Set InfluxDB credentials @@ -1231,10 +1252,11 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu - **host**: your {{% product-name %}} region URL - **database**: the name of the {{% product-name %}} bucket to write to - - **token**: a [token](/influxdb/cloud-serverless/admin/tokens/) with _write_ access to the specified bucket. + - **token**: a [token](/influxdb/cloud-serverless/admin/tokens/) with write access to the specified bucket. _Store this in a secret store or environment variable to avoid exposing the raw token string._ - _Instantiating the client with the `using` statement ensures that the client is disposed of when it's no longer needed._ + _The `using` statement ensures that the program disposes of the + client when it's no longer needed._ 2. Defines an array of line protocol strings where each string represents a data record. 3. Calls the client's `WriteRecordAsync()` method to write each line protocol record to InfluxDB. @@ -1262,11 +1284,13 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu } ``` - The `Program` class shares the same `InfluxDBv3` namespace as the `Write` class you defined in the preceding step - and defines a `Main()` function that calls `Write.WriteLineProtocol()`. - The `dotnet` CLI recognizes `Program.Main()` as the entry point for your program. + The `Program` class shares the same `InfluxDBv3` namespace as the `Write` + class you defined in the preceding step and defines a `Main()` function that + calls `Write.WriteLineProtocol()`. The `dotnet` CLI recognizes + `Program.Main()` as the entry point for your program. -7. To build and execute the program and write the line protocol to your {{% product-name %}} bucket, enter the following command in your terminal: +7. To build and execute the program and write the line protocol to your + {{% product-name %}} bucket, enter the following command in your terminal: @@ -1274,6 +1298,9 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu dotnet run ``` +If successful, the output is the success message; otherwise, error details and +the failure message. + {{% /influxdb/custom-timestamps %}} {{% /tab-content %}} @@ -1283,7 +1310,9 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu _The tutorial assumes using Maven version 3.9 and Java version >= 15._ -1. If you haven't already, follow the instructions to download and install the [Java JDK](https://www.oracle.com/java/technologies/downloads/) and [Maven](https://maven.apache.org/download.cgi) for your system. +1. If you haven't already, follow the instructions to download and install the + [Java JDK](https://www.oracle.com/java/technologies/downloads/) and + [Maven](https://maven.apache.org/download.cgi) for your system. 2. In your terminal or editor, use Maven to generate a project--for example: ```bash @@ -1295,9 +1324,11 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._ ``` Maven creates the `` directory (`./influxdb_java_client`) that - contains a `pom.xml` and scaffolding for your `com.influxdbv3.influxdb_java_client` Java application. + contains a `pom.xml` and scaffolding for your + `com.influxdbv3.influxdb_java_client` Java application. -3. In your terminal or editor, change into the `./influxdb_java_client` directory--for example: +3. In your terminal or editor, change into the `./influxdb_java_client` + directory--for example: @@ -1305,7 +1336,8 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._ cd ./influxdb_java_client ``` -4. In your editor, open the `pom.xml` Maven configuration file and add the `com.influxdb.influxdb3-java` client library into `dependencies`. +4. In your editor, open the `pom.xml` Maven configuration file and add the + `com.influxdb.influxdb3-java` client library into `dependencies`. ```pom ... @@ -1329,7 +1361,9 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._ mvn validate ``` -6. In your editor, navigate to the `./influxdb_java_client/src/main/java/com/influxdbv3` directory and create a `Write.java` file. +6. In your editor, navigate to the + `./influxdb_java_client/src/main/java/com/influxdbv3` directory and create a + `Write.java` file. 7. In `Write.java`, enter the following sample code: ```java @@ -1344,7 +1378,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._ /** * Writes line protocol to InfluxDB using the Java client * library. - */ + */ public final class Write { /** * Write data to InfluxDB v3. @@ -1357,7 +1391,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._ * @throws Exception */ public static void writeLineProtocol() throws Exception { - + // Set InfluxDB credentials final String host = "https://{{< influxdb/host >}}"; final String database = "get-started"; @@ -1421,7 +1455,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._ The sample code does the following: 1. Imports the following classes: - + - `java.util.List`; - `com.influxdb.v3.client.InfluxDBClient` - `com.influxdb.v3.client.write.WriteParameters` @@ -1432,17 +1466,26 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._ - **`host`**: your {{% product-name %}} region URL - **`database`**: the name of the {{% product-name %}} bucket to write to - - **`token`**: a [token](/influxdb/cloud-serverless/admin/tokens/) with _write_ access to the specified bucket. - _Store this in a secret store or environment variable to avoid exposing the raw token string._ + - **`token`**: a + [token](/influxdb/cloud-serverless/admin/tokens/) with write access + to the specified bucket. + _Store this in a secret store or environment variable to avoid exposing + the raw token string._ - 2. Defines a list of line protocol strings where each string represents a data record. - 3. Calls the client's `writeRecord()` method to write each record separately to InfluxDB. + 3. Defines a list of line protocol strings where each string represents a + data record. + 4. Calls the client's `writeRecord()` method to write each record + separately to InfluxDB. **Because the timestamps in the sample line protocol are in second - precision, the example passes the [`WritePrecision.S` enum value](https://github.com/InfluxCommunity/influxdb3-java/blob/main/src/main/java/com/influxdb/v3/client/write/WritePrecision.java) - as the `precision` argument to set the write [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) to seconds.** + precision, the example passes the + [`WritePrecision.S` enum value](https://github.com/InfluxCommunity/influxdb3-java/blob/main/src/main/java/com/influxdb/v3/client/write/WritePrecision.java) + as the `precision` argument to set the write + [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) + to seconds.** -8. In your editor, open the `App.java` file (created by Maven) and replace its contents with the following sample code: +8. In your editor, open the `App.java` file (created by Maven) and replace its + contents with the following sample code: ```java // App.java @@ -1465,10 +1508,13 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._ } } ``` - - - The `App` class and `Write` class are part of the same `com.influxdbv3` package (your project **groupId**). + + - The `App` class and `Write` class are part of the same `com.influxdbv3` + package (your project **groupId**). - `App` defines a `main()` function that calls `Write.writeLineProtocol()`. -9. In your terminal or editor, use Maven to to install dependencies and compile the project code--for example: + +9. In your terminal or editor, use Maven to install dependencies and compile + the project code--for example: @@ -1476,20 +1522,23 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._ mvn compile ``` -10. In your terminal or editor, execute `App.main()` to write to InfluxDB--for example, using Maven: +10. In your terminal or editor, execute `App.main()` to write to InfluxDB--for + example, using Maven: ```sh mvn exec:java -Dexec.mainClass="com.influxdbv3.App" ``` + +If successful, the output is the success message; otherwise, error details and +the failure message. + {{% /influxdb/custom-timestamps %}} {{% /tab-content %}} {{< /tabs-wrapper >}} -If successful, the output is the success message; otherwise, error details and the failure message. - {{< expand-wrapper >}} {{% expand "View the written data" %}} diff --git a/content/influxdb/cloud-serverless/write-data/line-protocol/_index.md b/content/influxdb/cloud-serverless/write-data/line-protocol/_index.md new file mode 100644 index 000000000..bdf7f4c41 --- /dev/null +++ b/content/influxdb/cloud-serverless/write-data/line-protocol/_index.md @@ -0,0 +1,89 @@ +--- +title: Write line protocol data to InfluxDB Cloud Serverless +description: > + Use Telegraf and API clients to write line protocol data + to InfluxDB Cloud Serverless. +menu: + influxdb_cloud_serverless: + name: Write line protocol data + parent: Write data +weight: 103 +related: + - /influxdb/cloud-serverless/reference/syntax/line-protocol/ + - /influxdb/cloud-serverless/reference/syntax/annotated-csv/ + - /influxdb/cloud-serverless/reference/cli/influx/write/ + - /influxdb/cloud-serverless/get-started/write/ +--- + +Learn the fundamentals of constructing and writing line protocol data. +Use tools like Telegraf and InfluxDB client libraries to +build line protocol, and then write it to an InfluxDB bucket. + +You can use these tools to build line protocol from scratch or transform +your data to line protocol. +However, if you already have CSV data, you might want to use tools that +[consume CSV +and write it to InfluxDB as line protocol](/influxdb/cloud-serverless/write-data/csv). + +- [Line protocol](#line-protocol) + - [Line protocol elements](#line-protocol-elements) +- [Write line protocol to InfluxDB](#write-line-protocol-to-influxdb) + +## Line protocol + +All data written to InfluxDB is written using +[line protocol](/influxdb/cloud-serverless/reference/syntax/line-protocol/), a text-based +format that lets you provide the necessary information to write a data point to InfluxDB. + +### Line protocol elements + +In InfluxDB, a point contains a measurement name, one or more fields, +a timestamp, and optional tags that provide metadata about the observation. + +Each line of line protocol contains the following elements: + +{{< req type="key" >}} + +- {{< req "\*" >}} **measurement**: String that identifies the + [measurement](/influxdb/cloud-serverless/reference/glossary/#measurement) to + store the data in. +- **tag set**: Comma-delimited list of key value pairs, each representing a tag. + Tag keys and values are unquoted strings. _Spaces, commas, and equal characters + must be escaped._ +- {{< req "\*" >}} **field set**: Comma-delimited list of key value pairs, each + representing a field. + Field keys are unquoted strings. _Spaces and commas must be escaped._ + Field values can be [strings](/influxdb/cloud-serverless/reference/syntax/line-protocol/#string) + (quoted), + [floats](/influxdb/cloud-serverless/reference/syntax/line-protocol/#float), + [integers](/influxdb/cloud-serverless/reference/syntax/line-protocol/#integer), + [unsigned integers](/influxdb/cloud-serverless/reference/syntax/line-protocol/#uinteger), + or [booleans](/influxdb/cloud-serverless/reference/syntax/line-protocol/#boolean). +- **timestamp**: [Unix timestamp](/influxdb/cloud-serverless/reference/syntax/line-protocol/#unix-timestamp) + associated with the data. InfluxDB supports up to nanosecond precision. + _If the precision of the timestamp is not in nanoseconds, you must specify the + precision when writing the data to InfluxDB._ + +#### Line protocol element parsing + +- **measurement**: Everything before the _first unescaped comma before the first + whitespace_. +- **tag set**: Key-value pairs between the _first unescaped comma_ and the _first + unescaped whitespace_. +- **field set**: Key-value pairs between the _first and second unescaped whitespaces_. +- **timestamp**: Integer value after the _second unescaped whitespace_. +- Lines are separated by the newline character (`\n`). + Line protocol is whitespace sensitive. + +--- + +{{< influxdb/line-protocol >}} + +--- + +_For schema design recommendations, see +[InfluxDB schema design](/influxdb/cloud-serverless/write-data/best-practices/schema-design/)._ + +## Write line protocol to InfluxDB + +{{< children >}} diff --git a/content/influxdb/cloud-serverless/write-data/line-protocol/client-libraries.md b/content/influxdb/cloud-serverless/write-data/line-protocol/client-libraries.md new file mode 100644 index 000000000..bdab7973e --- /dev/null +++ b/content/influxdb/cloud-serverless/write-data/line-protocol/client-libraries.md @@ -0,0 +1,475 @@ +--- +title: Use InfluxDB client libraries to write line protocol data +description: > + Use InfluxDB API clients to write points as line protocol data to InfluxDB + Cloud Serverless. +menu: + influxdb_cloud_serverless: + name: Use client libraries + parent: Write line protocol + identifier: write-client-libs +weight: 103 +related: + - /influxdb/cloud-serverless/reference/syntax/line-protocol/ + - /influxdb/cloud-serverless/get-started/write/ +--- + +Use InfluxDB client libraries to construct data as time series points, and then +write them as line protocol to an {{% product-name %}} bucket. + +- [Construct line protocol](#construct-line-protocol) + - [Example home schema](#example-home-schema) +- [Set up your project](#set-up-your-project) +- [Construct points and write line protocol](#construct-points-and-write-line-protocol) + +## Construct line protocol + +With a +[basic understanding of line protocol](/influxdb/cloud-serverless/write-data/line-protocol/), +you can construct line protocol data and write it to InfluxDB. + +All InfluxDB client libraries write data in line protocol format to InfluxDB. +Client library `write` methods let you provide data as raw line protocol or as +`Point` objects that the client library converts to line protocol. If your +program creates the data you write to InfluxDB, use the client library `Point` +interface to take advantage of type safety in your program. + +### Example home schema + +Consider a use case where you collect data from sensors in your home. Each +sensor collects temperature, humidity, and carbon monoxide readings. + +To collect this data, use the following schema: + + + +- **measurement**: `home` + - **tags** + - `room`: Living Room or Kitchen + - **fields** + - `temp`: temperature in °C (float) + - `hum`: percent humidity (float) + - `co`: carbon monoxide in parts per million (integer) + - **timestamp**: Unix timestamp in _second_ precision + + + +The following example shows how to construct and write points that follow the +`home` schema. + +## Set up your project + +The examples in this guide assume you followed +[Set up InfluxDB](/influxdb/cloud-serverless/get-started/setup/) and +[Write data set up](/influxdb/cloud-serverless/get-started/write/#set-up-your-project-and-credentials) +instructions in [Get started](/influxdb/cloud-serverless/get-started/). + +After setting up InfluxDB and your project, you should have the following: + +- {{< product-name >}} credentials: + + - [Bucket](/influxdb/cloud-serverless/admin/buckets/) + - [API token](/influxdb/cloud-serverless/admin/tokens/) + - InfluxDB region hostname + +- A directory for your project. + +- Credentials stored as environment variables or in a project configuration + file--for example, a `.env` ("dotenv") file. + +- Client libraries installed for writing data to InfluxDB. + +The following examples show how to construct `Point` objects that follow the +[example `home` schema](#example-home-schema), and then write the data as line +protocol to an {{% product-name %}} bucket. + +The examples use InfluxDB v3 client libraries. +For examples using InfluxDB v2 +client libraries to write data to InfluxDB v3, see +[InfluxDB v2 clients](/influxdb/cloud-serverless/reference/client-libraries/v2/). + +{{< tabs-wrapper >}} +{{% tabs %}} +[Go](#) +[Node.js](#) +[Python](#) +{{% /tabs %}} +{{% tab-content %}} + +The following steps set up a Go project using the +[InfluxDB v3 Go client](https://github.com/InfluxCommunity/influxdb3-go/): + + + +1. Install [Go 1.13 or later](https://golang.org/doc/install). + +1. Create a directory for your Go module and change to the directory--for + example: + + ```sh + mkdir iot-starter-go && cd $_ + ``` + +1. Initialize a Go module--for example: + + ```sh + go mod init iot-starter + ``` + +1. Install [`influxdb3-go`](https://github.com/InfluxCommunity/influxdb3-go/), + which provides the InfluxDB `influxdb3` Go client library module. + + ```sh + go get github.com/InfluxCommunity/influxdb3-go + ``` + + + +{{% /tab-content %}} {{% tab-content %}} + + + +The following steps set up a JavaScript project using the +[InfluxDB v3 JavaScript client](https://github.com/InfluxCommunity/influxdb3-js/). + +1. Install [Node.js](https://nodejs.org/en/download/). + +1. Create a directory for your JavaScript project and change to the + directory--for example: + + ```sh + mkdir -p iot-starter-js && cd $_ + ``` + +1. Initialize a project--for example, using `npm`: + + + + ```sh + npm init + ``` + +1. Install the `@influxdata/influxdb3-client` InfluxDB v3 JavaScript client + library. + + ```sh + npm install @influxdata/influxdb3-client + ``` + + + +{{% /tab-content %}} {{% tab-content %}} + + + +The following steps set up a Python project using the +[InfluxDB v3 Python client](https://github.com/InfluxCommunity/influxdb3-python/): + +1. Install [Python](https://www.python.org/downloads/) + +1. Inside of your project directory, create a directory for your Python module + and change to the module directory--for example: + + ```sh + mkdir -p iot-starter-py && cd $_ + ``` + +1. **Optional, but recommended**: Use + [`venv`](https://docs.python.org/3/library/venv.html) or + [`conda`](https://docs.continuum.io/anaconda/install/) to activate a virtual + environment for installing and executing code--for example, enter the + following command using `venv` to create and activate a virtual environment + for the project: + + ```bash + python3 -m venv envs/iot-starter && source ./envs/iot-starter/bin/activate + ``` + +1. Install + [`influxdb3-python`](https://github.com/InfluxCommunity/influxdb3-python), + which provides the InfluxDB `influxdb_client_3` Python client library module + and also installs the + [`pyarrow` package](https://arrow.apache.org/docs/python/index.html) for + working with Arrow data. + + ```sh + pip install influxdb3-python + ``` + + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +## Construct points and write line protocol + +Client libraries provide one or more `Point` constructor methods. Some libraries +support language-native data structures, such as Go's `struct`, for creating +points. + +{{< tabs-wrapper >}} +{{% tabs %}} +[Go](#) +[Node.js](#) +[Python](#) +{{% /tabs %}} +{{% tab-content %}} + + + +1. Create a file for your module--for example: `main.go`. + +1. In `main.go`, enter the following sample code: + + ```go + package main + + import ( + "context" + "os" + "fmt" + "time" + "github.com/InfluxCommunity/influxdb3-go/influxdb3" + "github.com/influxdata/line-protocol/v2/lineprotocol" + ) + + func Write() error { + url := os.Getenv("INFLUX_HOST") + token := os.Getenv("INFLUX_TOKEN") + database := os.Getenv("INFLUX_BUCKET") + + // To instantiate a client, call New() with InfluxDB credentials. + client, err := influxdb3.New(influxdb3.ClientConfig{ + Host: url, + Token: token, + Database: database, + }) + + /** Use a deferred function to ensure the client is closed when the + * function returns. + **/ + defer func (client *influxdb3.Client) { + err = client.Close() + if err != nil { + panic(err) + } + }(client) + + /** Use the NewPoint method to construct a point. + * NewPoint(measurement, tags map, fields map, time) + **/ + point := influxdb3.NewPoint("home", + map[string]string{ + "room": "Living Room", + }, + map[string]any{ + "temp": 24.5, + "hum": 40.5, + "co": 15i}, + time.Now(), + ) + + /** Use the NewPointWithMeasurement method to construct a point with + * method chaining. + **/ + point2 := influxdb3.NewPointWithMeasurement("home"). + SetTag("room", "Living Room"). + SetField("temp", 23.5). + SetField("hum", 38.0). + SetField("co", 16i). + SetTimestamp(time.Now()) + + fmt.Println("Writing points") + points := []*influxdb3.Point{point, point2} + + /** Write points to InfluxDB. + * You can specify WriteOptions, such as Gzip threshold, + * default tags, and timestamp precision. Default precision is lineprotocol.Nanosecond + **/ + err = client.WritePoints(context.Background(), points, + influxdb3.WithPrecision(lineprotocol.Second)) + return nil + } + + func main() { + Write() + } + ``` + +1. To run the module and write the data to your {{% product-name %}} bucket, + enter the following command in your terminal: + + + + ```sh + go run main.go + ``` + + + +{{% /tab-content %}} {{% tab-content %}} + + + +1. Create a file for your module--for example: `write-points.js`. + +1. In `write-points.js`, enter the following sample code: + + ```js + // write-points.js + import { InfluxDBClient, Point } from '@influxdata/influxdb3-client'; + + /** + * Set InfluxDB credentials. + */ + const host = process.env.INFLUX_HOST ?? ''; + const database = process.env.INFLUX_BUCKET; + const token = process.env.INFLUX_TOKEN; + + /** + * Write line protocol to InfluxDB using the JavaScript client library. + */ + export async function writePoints() { + /** + * Instantiate an InfluxDBClient. + * Provide the host URL and the database token. + */ + const client = new InfluxDBClient({ host, token }); + + /** Use the fluent interface with chained methods to construct Points. */ + const point = Point.measurement('home') + .setTag('room', 'Living Room') + .setFloatField('temp', 22.2) + .setFloatField('hum', 35.5) + .setIntegerField('co', 7) + .setTimestamp(new Date().getTime() / 1000); + + const point2 = Point.measurement('home') + .setTag('room', 'Kitchen') + .setFloatField('temp', 21.0) + .setFloatField('hum', 35.9) + .setIntegerField('co', 0) + .setTimestamp(new Date().getTime() / 1000); + + /** Write points to InfluxDB. + * The write method accepts an array of points, the target database (bucket), + * and an optional configuration object. + * You can specify WriteOptions, such as Gzip threshold, default tags, + * and timestamp precision. Default precision is lineprotocol.Nanosecond + **/ + + try { + await client.write([point, point2], database, '', { precision: 's' }); + console.log('Data has been written successfully!'); + } catch (error) { + console.error(`Error writing data to InfluxDB: ${error.body}`); + } + + client.close(); + } + + writePoints(); + ``` + +1. To run the module and write the data to your {{\< product-name >}} bucket, + enter the following command in your terminal: + + + + ```sh + node writePoints.js + ``` + + + + {{% /tab-content %}} {{% tab-content %}} + + + +1. Create a file for your module--for example: `write-points.py`. + +1. In `write-points.py`, enter the following sample code to write data in + batching mode: + + ```python + import os + from influxdb_client_3 import ( + InfluxDBClient3, InfluxDBError, Point, WritePrecision, + WriteOptions, write_client_options) + + host = os.getenv('INFLUX_HOST') + token = os.getenv('INFLUX_TOKEN') + database = os.getenv('INFLUX_BUCKET') + + # Create an array of points with tags and fields. + points = [Point("home") + .tag("room", "Kitchen") + .field("temp", 25.3) + .field('hum', 20.2) + .field('co', 9)] + + # With batching mode, define callbacks to execute after a successful or + # failed write request. + # Callback methods receive the configuration and data sent in the request. + def success(self, data: str): + print(f"Successfully wrote batch: data: {data}") + + def error(self, data: str, exception: InfluxDBError): + print(f"Failed writing batch: config: {self}, data: {data} due: {exception}") + + def retry(self, data: str, exception: InfluxDBError): + print(f"Failed retry writing batch: config: {self}, data: {data} retry: {exception}") + + # Configure options for batch writing. + write_options = WriteOptions(batch_size=500, + flush_interval=10_000, + jitter_interval=2_000, + retry_interval=5_000, + max_retries=5, + max_retry_delay=30_000, + exponential_base=2) + + # Create an options dict that sets callbacks and WriteOptions. + wco = write_client_options(success_callback=success, + error_callback=error, + retry_callback=retry, + write_options=write_options) + + # Instantiate a synchronous instance of the client with your + # InfluxDB credentials and write options, such as Gzip threshold, default tags, + # and timestamp precision. Default precision is nanosecond ('ns'). + with InfluxDBClient3(host=host, + token=token, + database=database, + write_client_options=wco) as client: + + client.write(points, write_precision='s') + ``` + +1. To run the module and write the data to your {{< product-name >}} bucket, + enter the following command in your terminal: + + + + ```sh + python write-points.py + ``` + + + + {{% /tab-content %}} {{< /tabs-wrapper >}} + +The sample code does the following: + + + +1. Instantiates a client configured with the InfluxDB URL and API token. +2. Constructs `home` + [measurement](/influxdb/cloud-serverless/reference/glossary/#measurement) + `Point` objects. +3. Sends data as line protocol format to InfluxDB and waits for the response. +4. If the write succeeds, logs the success message to stdout; otherwise, logs + the failure message and error details. +5. Closes the client to release resources. + + diff --git a/content/influxdb/clustered/get-started/write.md b/content/influxdb/clustered/get-started/write.md index 961ace8fe..62de9e0d4 100644 --- a/content/influxdb/clustered/get-started/write.md +++ b/content/influxdb/clustered/get-started/write.md @@ -55,29 +55,36 @@ Each line of line protocol contains the following elements: - {{< req "\*" >}} **measurement**: A string that identifies the [table](/influxdb/clustered/reference/glossary/#table) to store the data in. - **tag set**: Comma-delimited list of key value pairs, each representing a tag. - Tag keys and values are unquoted strings. _Spaces, commas, and equal characters must be escaped._ -- {{< req "\*" >}} **field set**: Comma-delimited list of key value pairs, each representing a field. + Tag keys and values are unquoted strings. _Spaces, commas, and equal characters + must be escaped._ +- {{< req "\*" >}} **field set**: Comma-delimited list of key value pairs, each + representing a field. Field keys are unquoted strings. _Spaces and commas must be escaped._ - Field values can be [strings](/influxdb/clustered/reference/syntax/line-protocol/#string) (quoted), + Field values can be [strings](/influxdb/clustered/reference/syntax/line-protocol/#string) + (quoted), [floats](/influxdb/clustered/reference/syntax/line-protocol/#float), [integers](/influxdb/clustered/reference/syntax/line-protocol/#integer), [unsigned integers](/influxdb/clustered/reference/syntax/line-protocol/#uinteger), or [booleans](/influxdb/clustered/reference/syntax/line-protocol/#boolean). - **timestamp**: [Unix timestamp](/influxdb/clustered/reference/syntax/line-protocol/#unix-timestamp) - associated with the data. InfluxDB supports up to nanosecond precision. - _If the precision of the timestamp is not in nanoseconds, you must specify the - precision when writing the data to InfluxDB._ +associated with the data. InfluxDB supports up to nanosecond precision. +_If the precision of the timestamp is not in nanoseconds, you must specify the +precision when writing the data to InfluxDB._ + #### Line protocol element parsing + + - **measurement**: Everything before the _first unescaped comma before the first whitespace_. - **tag set**: Key-value pairs between the _first unescaped comma_ and the _first unescaped whitespace_. - **field set**: Key-value pairs between the _first and second unescaped whitespaces_. - **timestamp**: Integer value after the _second unescaped whitespace_. -- Lines are separated by the newline character (`\n`). - Line protocol is whitespace sensitive. +- Lines are separated by the newline character (`\n`). Line protocol is +whitespace sensitive. + --- @@ -85,10 +92,13 @@ Each line of line protocol contains the following elements: --- -_For schema design recommendations, see [InfluxDB schema design](/influxdb/clustered/write-data/best-practices/schema-design/)._ +_For schema design recommendations, see +[InfluxDB schema design](/influxdb/clustered/write-data/best-practices/schema-design/)._ ## Construct line protocol + + With a basic understanding of line protocol, you can now construct line protocol and write data to InfluxDB. Consider a use case where you collect data from sensors in your home. @@ -145,7 +155,7 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 ## Write line protocol to InfluxDB -The following examples show how to write the +The following examples show how to write the preceding [sample data](#home-sensor-data-line-protocol), already in line protocol format, to an {{% product-name %}} database. @@ -225,6 +235,9 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200' {{% /code-placeholders %}} {{% /influxdb/custom-timestamps %}} +If successful, the output is the success message; otherwise, error details and +the failure message. + {{% /tab-content %}} @@ -237,9 +250,11 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200' Use [Telegraf](/telegraf/v1/) to consume line protocol, and then write it to {{< product-name >}}. -1. If you haven't already, follow the instructions to [download and install Telegraf](/telegraf/v1/install/). +1. If you haven't already, follow the instructions to + [download and install Telegraf](/telegraf/v1/install/). -2. Copy and save the [home sensor data sample](#home-sensor-data-line-protocol) to a file on your local system--for example, `home.lp`. +2. Copy and save the [home sensor data sample](#home-sensor-data-line-protocol) + to a file on your local system--for example, `home.lp`. ```sh cat <<- EOF > home.lp @@ -285,64 +300,63 @@ and then write it to {{< product-name >}}. 4. In your editor, open `./telegraf.conf` and configure the following: - - **`file` input plugin**: In the `[[inputs.file]].files` list, replace - `"/tmp/metrics.out"` with your sample data filename. If Telegraf can't - find a file when started, it stops processing and exits. + - **`file` input plugin**: In the `[[inputs.file]].files` list, replace + `"/tmp/metrics.out"` with your sample data filename. If Telegraf can't + find a file when started, it stops processing and exits. - ```toml - [[inputs.file]] - ## Files to parse each interval. Accept standard unix glob matching rules, - ## as well as ** to match recursive files and directories. - files = ["home.lp"] - ``` + ```toml + [[inputs.file]] + ## Files to parse each interval. Accept standard unix glob matching rules, + ## as well as ** to match recursive files and directories. + files = ["home.lp"] + ``` - + - - **`output-influxdb_v2` output plugin**: In the `[[outputs.influxdb_v2]]` + - **`output-influxdb_v2` output plugin**: In the `[[outputs.influxdb_v2]]` + section, replace the default values with the following configuration for + your {{% product-name %}} database: - section, replace the default values with the following configuration for your - {{% product-name %}} database: + ```toml + [[outputs.influxdb_v2]] + # InfluxDB cluster URL + urls = ["${INFLUX_HOST}"] - ```toml - [[outputs.influxdb_v2]] - # InfluxDB cluster URL - urls = ["${INFLUX_HOST}"] + # INFLUX_TOKEN is an environment variable you assigned to your database token + token = "${INFLUX_TOKEN}" - # INFLUX_TOKEN is an environment variable you assigned to your database token - token = "${INFLUX_TOKEN}" + # An empty string (InfluxDB ignores this parameter) + organization = "" - # An empty string (InfluxDB ignores this parameter) - organization = "" + # Database name + bucket = "get-started" + ``` - # Database name - bucket = "get-started" - ``` + - + The example configuration uses the following InfluxDB credentials: - The example configuration uses the following InfluxDB credentials: - - - **`urls`**: an array containing your **`INFLUX_HOST`** environment - variable - - **`token`**: your **`INFLUX_TOKEN`** environment variable - - **`organization`**: an empty string (InfluxDB ignores this parameter) - - **`bucket`**: the name of the database to write to + - **`urls`**: an array containing your **`INFLUX_HOST`** environment + variable + - **`token`**: your **`INFLUX_TOKEN`** environment variable + - **`organization`**: an empty string (InfluxDB ignores this parameter) + - **`bucket`**: the name of the database to write to 5. To write the data, start the `telegraf` daemon with the following options: @@ -364,8 +378,9 @@ and then write it to {{< product-name >}}. 2023-05-31T20:09:19Z D! [outputs.influxdb_v2] Buffer fullness: 0 / 10000 metrics ``` -Telegraf and its plugins provide many options for reading and writing data. -To learn more, see how to [use Telegraf to write data](/influxdb/clustered/write-data/use-telegraf/). +Telegraf and its plugins provide many options for reading and writing data. To +learn more, see how to +[use Telegraf to write data](/influxdb/clustered/write-data/use-telegraf/). {{% /influxdb/custom-timestamps %}} @@ -411,11 +426,11 @@ Include the following with your request: {{% note %}} With the {{% product-name %}} -[v1 API `/write` endpoint](/influxdb/cloud-dedicated/api/#operation/PostLegacyWrite), +[v1 API `/write` endpoint](/influxdb/clustered/api/#operation/PostLegacyWrite), `Authorization: Bearer` and `Authorization: Token` are equivalent and you can use either scheme to pass a database token in your request. For more information about HTTP API token schemes, see how to -[authenticate API requests](/influxdb/cloud-dedicated/guides/api-compatibility/v1/). +[authenticate API requests](/influxdb/clustered/guides/api-compatibility/v1/). {{% /note %}} The following example uses cURL and the InfluxDB v1 API to write line protocol @@ -479,7 +494,8 @@ Replace the following: a [database token](/influxdb/clustered/admin/tokens/#database-tokens) with sufficient permissions to the specified database -If successful, the output is an HTTP `204 No Content` status code. +If successful, the output is an HTTP `204 No Content` status code; otherwise, +the error status code and failure message. @@ -590,7 +606,7 @@ Replace the following: sufficient permissions to the specified database If successful, the output is an HTTP `204 No Content` status code; otherwise, -the status code and error message. +the error status code and failure message. @@ -616,17 +632,12 @@ dependencies to your current project. 1. Create a module directory and navigate into it--for example: - - ```bash mkdir -p influxdb_py_client && cd influxdb_py_client ``` 2. Setup your Python virtual environment. - Inside of your module directory: + Inside of your module directory, enter the following command: @@ -752,6 +763,9 @@ dependencies to your current project. {{% /influxdb/custom-timestamps %}} +If successful, the output is the success message; otherwise, error details and +the failure message. + {{% /tab-content %}} @@ -927,17 +941,17 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3 } ``` -6. In your terminal, enter the following command to install the packages listed - in `imports`, build the `influxdb_go_client` module, and execute the - `main()` function: +6. To install dependencies and write the data to your {{% product-name %}} + database, enter the following command into your terminal: ```sh - go mod tidy && go build && go run influxdb_go_client + go mod tidy && go run influxdb_go_client ``` - The program writes the line protocol to your {{% product-name %}} database. +If successful, the output is the success message; otherwise, error details and +the failure message. {{% /influxdb/custom-timestamps %}} @@ -1133,6 +1147,9 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3 {{% /influxdb/custom-timestamps %}} +If successful, the output is the success message; otherwise, error details and +the failure message. + {{% /tab-content %}} @@ -1268,8 +1285,8 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3 with _write_ access to the specified database. _Store this in a secret store or environment variable to avoid exposing the raw token string._ - _Instantiating the client with the `using` statement ensures that the - client is disposed of when it's no longer needed._ + _The `using` statement ensures that the program disposes of the + client when it's no longer needed._ 2. Defines an array of line protocol strings where each string represents a data record. @@ -1311,19 +1328,23 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3 7. To build and execute the program and write the line protocol to your {{% product-name %}} database, enter the following command in your terminal: - + - ```sh - dotnet run - ``` + ```sh + dotnet run + ``` - +If successful, the output is the success message; otherwise, error details and +the failure message. - {{% /influxdb/custom-timestamps %}} - {{% /tab-content %}} - {{% tab-content %}} - {{% influxdb/custom-timestamps %}} - + + +{{% /influxdb/custom-timestamps %}} +{{% /tab-content %}} +{{% tab-content %}} +{{% influxdb/custom-timestamps %}} + + _The tutorial assumes using Maven version 3.9 and Java version >= 15._ @@ -1542,21 +1563,21 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._ 10. In your terminal or editor, execute `App.main()` to write to InfluxDB--for example, using Maven: - + - ```sh - mvn exec:java -Dexec.mainClass="com.influxdbv3.App" - ``` - - - - {{% /influxdb/custom-timestamps %}} - {{% /tab-content %}} - {{< /tabs-wrapper >}} + ```sh + mvn exec:java -Dexec.mainClass="com.influxdbv3.App" + ``` If successful, the output is the success message; otherwise, error details and the failure message. + + +{{% /influxdb/custom-timestamps %}} +{{% /tab-content %}} +{{< /tabs-wrapper >}} + {{< expand-wrapper >}} {{% expand "View the written data" %}} @@ -1597,4 +1618,5 @@ the failure message. **Congratulations!** You've written data to InfluxDB. Next, learn how to query your data. -{{< page-nav prev="/influxdb/clustered/get-started/setup/" next="/influxdb/clustered/get-started/query/" keepTab=true >}} +{{< page-nav prev="/influxdb/clustered/get-started/setup/" +next="/influxdb/clustered/get-started/query/" keepTab=true >}} diff --git a/content/influxdb/clustered/write-data/line-protocol/client-libraries.md b/content/influxdb/clustered/write-data/line-protocol/client-libraries.md index 046e55ebe..582947d5b 100644 --- a/content/influxdb/clustered/write-data/line-protocol/client-libraries.md +++ b/content/influxdb/clustered/write-data/line-protocol/client-libraries.md @@ -6,7 +6,7 @@ description: > menu: influxdb_clustered: name: Use client libraries - parent: Write line protocol + parent: Write line protocol data identifier: write-client-libs weight: 103 related: @@ -14,8 +14,8 @@ related: - /influxdb/clustered/get-started/write/ --- -Use InfluxDB client libraries to build time series points, and then write them -line protocol to an {{% product-name %}} database. +Use InfluxDB client libraries to construct data as time series points, and then +write them as line protocol to an {{% product-name %}} database. - [Construct line protocol](#construct-line-protocol) - [Example home schema](#example-home-schema) @@ -79,15 +79,21 @@ After setting up InfluxDB and your project, you should have the following: - Client libraries installed for writing data to InfluxDB. -The following example shows how to construct `Point` objects that follow the +The following examples show how to construct `Point` objects that follow the [example `home` schema](#example-home-schema), and then write the data as line protocol to an {{% product-name %}} database. -The examples use InfluxDB v3 client libraries. For examples using InfluxDB v2 +The examples use InfluxDB v3 client libraries. +For examples using InfluxDB v2 client libraries to write data to InfluxDB v3, see [InfluxDB v2 clients](/influxdb/clustered/reference/client-libraries/v2/). -{{< tabs-wrapper >}} {{% tabs %}} [Go](#) [Node.js](#) [Python](#) {{% /tabs %}} +{{< tabs-wrapper >}} +{{% tabs %}} +[Go](#) +[Node.js](#) +[Python](#) +{{% /tabs %}} {{% tab-content %}} The following steps set up a Go project using the @@ -192,7 +198,8 @@ The following steps set up a Python project using the -{{% /tab-content %}} {{< /tabs-wrapper >}} +{{% /tab-content %}} +{{< /tabs-wrapper >}} ## Construct points and write line protocol @@ -200,7 +207,12 @@ Client libraries provide one or more `Point` constructor methods. Some libraries support language-native data structures, such as Go's `struct`, for creating points. -{{< tabs-wrapper >}} {{% tabs %}} [Go](#) [Node.js](#) [Python](#) {{% /tabs %}} +{{< tabs-wrapper >}} +{{% tabs %}} +[Go](#) +[Node.js](#) +[Python](#) +{{% /tabs %}} {{% tab-content %}} @@ -452,12 +464,12 @@ The sample code does the following: 1. Instantiates a client configured with the InfluxDB URL and API token. -1. Constructs `home` +2. Constructs `home` [measurement](/influxdb/clustered/reference/glossary/#measurement) `Point` objects. -1. Sends data as line protocol format to InfluxDB and waits for the response. -1. If the write succeeds, logs the success message to stdout; otherwise, logs +3. Sends data as line protocol format to InfluxDB and waits for the response. +4. If the write succeeds, logs the success message to stdout; otherwise, logs the failure message and error details. -1. Closes the client to release resources. +5. Closes the client to release resources. diff --git a/content/influxdb/clustered/write-data/line-protocol/influxctl-cli.md b/content/influxdb/clustered/write-data/line-protocol/influxctl-cli.md new file mode 100644 index 000000000..4fd656685 --- /dev/null +++ b/content/influxdb/clustered/write-data/line-protocol/influxctl-cli.md @@ -0,0 +1,197 @@ +--- +title: Use the influxctl CLI to write line protocol data +description: > + Use the [`influxctl` CLI](/influxdb/clustered/reference/cli/influxctl/) + to write line protocol data to InfluxDB Clustered. +menu: + influxdb_clustered: + name: Use the influxctl CLI + parent: Write line protocol data + identifier: write-influxctl +weight: 101 +related: + - /influxdb/clustered/reference/cli/influxctl/write/ + - /influxdb/clustered/reference/syntax/line-protocol/ + - /influxdb/clustered/get-started/write/ +--- + +Use the [`influxctl` CLI](/influxdb/clustered/reference/cli/influxctl/) +to write line protocol data to {{< product-name >}}. + +- [Construct line protocol](#construct-line-protocol) +- [Write the line protocol to InfluxDB](#write-the-line-protocol-to-influxdb) + +## Construct line protocol + +With a [basic understanding of line protocol](/influxdb/clustered/write-data/line-protocol/), +you can now construct line protocol and write data to InfluxDB. +Consider a use case where you collect data from sensors in your home. +Each sensor collects temperature, humidity, and carbon monoxide readings. +To collect this data, use the following schema: + +- **measurement**: `home` + - **tags** + - `room`: Living Room or Kitchen + - **fields** + - `temp`: temperature in °C (float) + - `hum`: percent humidity (float) + - `co`: carbon monoxide in parts per million (integer) + - **timestamp**: Unix timestamp in _second_ precision + +The following line protocol represent the schema described above: + +```text +home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 +home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 +home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 +home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 +home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 +home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 +home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 +home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 +home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 +home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 +home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 +home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000 +``` + +For this tutorial, you can either pass this line protocol directly to the +`influxctl write` command as a string, via `stdin`, or you can save it to and read +it from a file. + +## Write the line protocol to InfluxDB + +Use the [`influxctl write` command](/influxdb/clustered/reference/cli/influxctl/write/) +to write the [home sensor sample data](#home-sensor-data-line-protocol) to your +{{< product-name omit=" Clustered" >}} cluster. +Provide the following: + +- The [database](/influxdb/clustered/admin/databases/) name using the `--database` flag +- A [database token](/influxdb/clustered/admin/tokens/#database-tokens) + (with write permissions on the target database) using the `--token` flag +- The timestamp precision as seconds (`s`) using the `--precision` flag +- [Line protocol](#construct-line-protocol). + Pass the line protocol in one of the following ways: + + - a string on the command line + - a path to a file that contains the query + - a single dash (`-`) to read the query from stdin + +{{< tabs-wrapper >}} +{{% tabs %}} +[string](#) +[file](#) +[stdin](#) +{{% /tabs %}} +{{% tab-content %}} + +{{% influxdb/custom-timestamps %}} +{{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}} + +```sh +influxctl write \ + --database DATABASE_NAME \ + --token DATABASE_TOKEN \ + --precision s \ + 'home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 +home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 +home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 +home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 +home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 +home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 +home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 +home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 +home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 +home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 +home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 +home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000' +``` + +{{% /code-placeholders %}} +{{% /influxdb/custom-timestamps %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + Name of the database to write to. +- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: + Database token with write permissions on the target database. + +{{% /tab-content %}} +{{% tab-content %}} + +{{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}} + +1. In your terminal, enter the following command to create the sample data file: + + ```sh + cat < ./home.lp && LINE_PROTOCOL_FILEPATH=./home.lp + home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 + home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 + home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 + home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 + home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200 + home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200 + home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800 + home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800 + home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400 + home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400 + home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000 + home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000 + + EOF + ``` + + + +2. Enter the following CLI command to write the data from the sample file: + + ```sh + influxctl write \ + --database DATABASE_NAME \ + --token DATABASE_TOKEN \ + --precision s \ + $LINE_PROTOCOL_FILEPATH + ``` + +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + Name of the database to write to. +- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: + Database token with write permissions on the target database. +- {{% code-placeholder-key %}}`$LINE_PROTOCOL_FILEPATH`{{% /code-placeholder-key %}}: + File path to the file containing the line protocol. Can be an absolute file path + or relative to the current working directory. + +{{% /tab-content %}} +{{% tab-content %}} + +{{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}} + + + +```sh +cat $LINE_PROTOCOL_FILEPATH | influxctl write \ + --database DATABASE_NAME \ + --token DATABASE_TOKEN \ + --precision s \ + - +``` + +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: + Name of the database to write to. +- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: + Database token with write permissions on the target database. +- {{% code-placeholder-key %}}`$LINE_PROTOCOL_FILEPATH`{{% /code-placeholder-key %}}: + File path to the file containing the line protocol. Can be an absolute file path + or relative to the current working directory. + +{{% /tab-content %}} +{{< /tabs-wrapper >}}