Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

chore: fix formatting

pull/5503/head
Jason Stirnaman 2024-06-24 09:42:44 -05:00
parent 5c74f013a1
commit 3274742abe
3 changed files with 278 additions and 177 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
content/influxdb/cloud-dedicated/get-started/write.md
View File

@ -48,6 +48,8 @@ information, see the
Each line of line protocol contains the following elements: Each line of line protocol contains the following elements:
<!-- vale InfluxDataDocs.v3Schema = NO -->
{{< req type="key" >}} {{< req type="key" >}}
- {{< req "\*" >}} **measurement**: A string that identifies the - {{< req "\*" >}} **measurement**: A string that identifies the
@ -74,8 +76,6 @@ Each line of line protocol contains the following elements:
#### Line protocol element parsing #### Line protocol element parsing
<!-- vale InfluxDataDocs.v3Schema = NO -->
- **measurement**: Everything before the _first unescaped comma before the first - **measurement**: Everything before the _first unescaped comma before the first
whitespace_. whitespace_.
- **tag set**: Key-value pairs between the _first unescaped comma_ and the - **tag set**: Key-value pairs between the _first unescaped comma_ and the
@ -99,11 +99,10 @@ _For schema design recommendations, see
## Construct line protocol ## Construct line protocol
With a basic understanding of line protocol, you can now 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 and write data to InfluxDB.
sensors in your home. Each sensor collects temperature, humidity, and carbon Consider a use case where you collect data from sensors in your home.
monoxide readings. To collect this data, use the following schema: Each sensor collects temperature, humidity, and carbon monoxide readings.
To collect this data, use the following schema:
<!-- vale InfluxDataDocs.v3Schema = NO -->
- **measurement**: `home` - **measurement**: `home`
- **tags** - **tags**
@ -115,10 +114,8 @@ monoxide readings. To collect this data, use the following schema:
- **timestamp**: Unix timestamp in _second_ precision - **timestamp**: Unix timestamp in _second_ precision
<!-- vale InfluxDataDocs.v3Schema = YES --> <!-- vale InfluxDataDocs.v3Schema = YES -->
Data is collected hourly beginning at The following line protocol sample represents data collected hourly beginning at
{{% influxdb/custom-timestamps-span %}}**2022-01-01T08:00:00Z (UTC)** until {{% influxdb/custom-timestamps-span %}}**2022-01-01T08:00:00Z (UTC)** until **2022-01-01T20:00:00Z (UTC)**{{% /influxdb/custom-timestamps-span %}}.
**2022-01-01T20:00:00Z (UTC)**{{% /influxdb/custom-timestamps-span %}}. The
resulting line protocol would look something like the following:
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
@ -161,10 +158,10 @@ The following examples show how to write the
[sample data](#home-sensor-data-line-protocol), already in line protocol format, [sample data](#home-sensor-data-line-protocol), already in line protocol format,
to an {{% product-name %}} database. to an {{% product-name %}} database.
To learn more about available tools and options, see To learn more about available tools and options, see [Write data](/influxdb/cloud-dedicated/write-data/).
[Write data](/influxdb/cloud-dedicated/write-data/).
{{% note %}} Some examples in this getting started tutorial assume your InfluxDB {{% note %}}
Some examples in this getting started tutorial assume your InfluxDB
credentials (**URL**, **organization**, and **token**) are provided by credentials (**URL**, **organization**, and **token**) are provided by
[environment variables](/influxdb/cloud-dedicated/get-started/setup/?t=InfluxDB+API#configure-authentication-credentials). [environment variables](/influxdb/cloud-dedicated/get-started/setup/?t=InfluxDB+API#configure-authentication-credentials).
{{% /note %}} {{% /note %}}
@ -690,7 +687,7 @@ dependencies to your current project.
# database WRITE token value. # database WRITE token value.
token = os.getenv('INFLUX_TOKEN') token = os.getenv('INFLUX_TOKEN')
# host is the URL without protocol or trailing slash # host is the URL hostname without protocol or trailing slash
client = InfluxDBClient3( client = InfluxDBClient3(
host='{{< influxdb/host >}}', host='{{< influxdb/host >}}',
org='', org='',
@ -1011,7 +1008,7 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3
/** /**
* Set InfluxDB credentials. * Set InfluxDB credentials.
*/ */
const host = 'https://cluster-id.influxdb.io'; const host = '{{< influxdb/host >}}';
const database = 'get-started'; const database = 'get-started';
/** /**
* INFLUX_TOKEN is an environment variable you assigned to your * INFLUX_TOKEN is an environment variable you assigned to your

258
content/influxdb/cloud-serverless/get-started/write.md
View File

@ -44,6 +44,8 @@ see the [Line protocol reference](/influxdb/cloud-serverless/reference/syntax/li
Each line of line protocol contains the following elements: Each line of line protocol contains the following elements:
<!-- vale InfluxDataDocs.v3Schema = NO -->
{{< req type="key" >}} {{< req type="key" >}}
- {{< req "\*" >}} **measurement**: String that identifies the [measurement](/influxdb/cloud-serverless/reference/glossary/#measurement) to store the data in. - {{< req "\*" >}} **measurement**: String that identifies the [measurement](/influxdb/cloud-serverless/reference/glossary/#measurement) to store the data in.
@ -63,12 +65,14 @@ Each line of line protocol contains the following elements:
#### Line protocol element parsing #### Line protocol element parsing
- **measurement**: Everything before the _first unescaped comma before the first whitespace_. - **measurement**: Everything before the _first unescaped comma before the first
- **tag set**: Key-value pairs between the _first unescaped comma_ and the _first unescaped whitespace_. 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_. - **field set**: Key-value pairs between the _first and second unescaped whitespaces_.
- **timestamp**: Integer value after the _second unescaped whitespace_. - **timestamp**: Integer value after the _second unescaped whitespace_.
- Lines are separated by the newline character (`\n`). - Lines are separated by the newline character (`\n`).
Line protocol is whitespace sensitive. Line protocol is whitespace sensitive.
--- ---
@ -94,10 +98,10 @@ To collect this data, use the following schema:
- `hum`: percent humidity (float) - `hum`: percent humidity (float)
- `co`: carbon monoxide in parts per million (integer) - `co`: carbon monoxide in parts per million (integer)
- **timestamp**: Unix timestamp in _second_ precision - **timestamp**: Unix timestamp in _second_ precision
<!-- vale InfluxDataDocs.v3Schema = YES -->
Data is collected hourly beginning at The following line protocol sample represents data collected hourly beginning at
{{% influxdb/custom-timestamps-span %}}**2022-01-01T08:00:00Z (UTC)** until **2022-01-01T20:00:00Z (UTC)**{{% /influxdb/custom-timestamps-span %}}. {{% influxdb/custom-timestamps-span %}}**2022-01-01T08:00:00Z (UTC)** until **2022-01-01T20:00:00Z (UTC)**{{% /influxdb/custom-timestamps-span %}}.
The resulting line protocol would look something like the following:
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
@ -280,7 +284,9 @@ Use [Telegraf](/telegraf/v1/) to consume line protocol, and then write it to {{<
EOF EOF
``` ```
3. Run the following command to generate a Telegraf configuration file (`./telegraf.conf`) that enables the `inputs.file` and `outputs.influxdb_v2` plugins: 3. Run the following command to generate a Telegraf configuration file
(`./telegraf.conf`) that enables the `inputs.file` and `outputs.influxdb_v2`
plugins:
```sh ```sh
telegraf --sample-config \ telegraf --sample-config \
@ -291,8 +297,9 @@ Use [Telegraf](/telegraf/v1/) to consume line protocol, and then write it to {{<
4. In your editor, open `./telegraf.conf` and configure the following: 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. - **`file` input plugin**: In the `[[inputs.file]].files` list, replace
If Telegraf can't find a file when started, it stops processing and exits. `"/tmp/metrics.out"` with your sample data filename. If Telegraf can't
find a file when started, it stops processing and exits.
```toml ```toml
[[inputs.file]] [[inputs.file]]
@ -304,13 +311,13 @@ Use [Telegraf](/telegraf/v1/) to consume line protocol, and then write it to {{<
<!--test <!--test
```bash ```bash
echo '[[inputs.file]]' > telegraf.conf echo '[[inputs.file]]' > telegraf.conf
echo ' ## Files to parse each interval. Accept standard unix glob matching rules,' >> telegraf.conf
echo ' ## as well as ** to match recursive files and directories.' >> telegraf.conf
echo ' files = ["home.lp"]' >> telegraf.conf echo ' files = ["home.lp"]' >> telegraf.conf
``` ```
--> -->
- **`output-influxdb_v2` output plugin**: In the `[[outputs.influxdb_v2]]` section, replace the default values with the following configuration for your {{% product-name %}} bucket: - **`output-influxdb_v2` output plugin**: In the `[[outputs.influxdb_v2]]`
section, replace the default values with the following configuration for your
{{% product-name %}} bucket:
```toml ```toml
[[outputs.influxdb_v2]] [[outputs.influxdb_v2]]
@ -330,16 +337,12 @@ Use [Telegraf](/telegraf/v1/) to consume line protocol, and then write it to {{<
<!--test <!--test
```bash ```bash
echo '[[outputs.influxdb_v2]]' >> telegraf.conf echo '[[outputs.influxdb_v2]]' >> telegraf.conf
echo ' # InfluxDB URL' >> telegraf.conf
echo ' urls = ["${INFLUX_HOST}"]' >> telegraf.conf echo ' urls = ["${INFLUX_HOST}"]' >> telegraf.conf
echo '' >> telegraf.conf echo '' >> telegraf.conf
echo ' # INFLUX_TOKEN is an environment variable you assigned to your API token' >> telegraf.conf
echo ' token = "${INFLUX_TOKEN}"' >> telegraf.conf echo ' token = "${INFLUX_TOKEN}"' >> telegraf.conf
echo '' >> telegraf.conf echo '' >> telegraf.conf
echo ' # An empty string (InfluxDB ignores this parameter)' >> telegraf.conf
echo ' organization = ""' >> telegraf.conf echo ' organization = ""' >> telegraf.conf
echo '' >> telegraf.conf echo '' >> telegraf.conf
echo ' # Database name' >> telegraf.conf
echo ' bucket = "get-started"' >> telegraf.conf echo ' bucket = "get-started"' >> telegraf.conf
``` ```
--> -->
@ -354,7 +357,8 @@ Use [Telegraf](/telegraf/v1/) to consume line protocol, and then write it to {{<
5. To write the data, start the `telegraf` daemon with the following options: 5. To write the data, start the `telegraf` daemon with the following options:
- `--config`: Specifies the path of the configuration file. - `--config`: Specifies the path of the configuration file.
- `--once`: Runs a single Telegraf collection cycle for the configured inputs and outputs, and then exits. - `--once`: Runs a single Telegraf collection cycle for the configured
inputs and outputs, and then exits.
Enter the following command in your terminal: Enter the following command in your terminal:
@ -381,16 +385,23 @@ To learn more, see how to [use Telegraf to write data](/influxdb/cloud-serverles
<!----------------------------- BEGIN v1 API CONTENT -----------------------------> <!----------------------------- BEGIN v1 API CONTENT ----------------------------->
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
Write data with your existing workloads that already use the InfluxDB v1 `/write` API endpoint. Write data with your existing workloads that already use the InfluxDB v1 `/write`
API endpoint.
{{% note %}} {{% note %}}
If migrating data from InfluxDB 1.x, see the [Migrate data from InfluxDB 1.x to InfluxDB {{% product-name %}}](/influxdb/cloud-serverless/guides/migrate-data/migrate-1x-to-serverless/) guide. If migrating data from InfluxDB 1.x, see the
[Migrate data from InfluxDB 1.x to InfluxDB
{{% product-name %}}](/influxdb/cloud-serverless/guides/migrate-data/migrate-1x-to-serverless/)
guide.
{{% /note %}} {{% /note %}}
To write data to InfluxDB using the [InfluxDB v1 HTTP API](/influxdb/cloud-serverless/reference/api/), send a To write data to InfluxDB using the
request to the [InfluxDB API `/write` endpoint](/influxdb/cloud-serverless/api/#operation/PostLegacyWrite) using the `POST` request method. [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" %}}
@ -408,12 +419,15 @@ Include the following with your request:
The following example uses cURL and the InfluxDB v1 API to write line protocol The following example uses cURL and the InfluxDB v1 API to write line protocol
to InfluxDB. to InfluxDB.
Given that `API_TOKEN` is an [All-Access API token](/influxdb/cloud-serverless/admin/tokens/#all-access-api-token), InfluxDB creates a bucket named `get-started/autogen` and an `autogen` DBRP mapping, and then writes the data to the bucket. Given that `API_TOKEN` is an
[All-Access API token](/influxdb/cloud-serverless/admin/tokens/#all-access-api-token),
InfluxDB creates a bucket named `get-started/autogen` and an
`autogen` DBRP mapping, and then writes the data to the bucket.
{{% code-placeholders "API_TOKEN " %}} {{% code-placeholders "API_TOKEN " %}}
```sh ```sh
curl --silent -w "%{response_code}: %{errormsg}\n" \ response=$(curl --silent --write-out "%{response_code}:%{errormsg}" \
"https://{{< influxdb/host >}}/write?db=get-started&precision=s" \ "https://{{< influxdb/host >}}/write?db=get-started&precision=s" \
--header "Authorization: Token API_TOKEN" \ --header "Authorization: Token API_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \ --header "Content-type: text/plain; charset=utf-8" \
@ -445,36 +459,57 @@ home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600
home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600 home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600
home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200 home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200
home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200
" ")
# Format the response code and error message output.
response_code=${response%%:*}
errormsg=${response#*:}
# Remove leading and trailing whitespace from errormsg
errormsg=$(echo "${errormsg}" | tr -d '[:space:]')
echo "$response_code"
if [[ $errormsg ]]; then
echo "$errormsg"
fi
``` ```
{{% /code-placeholders %}} {{% /code-placeholders %}}
Replace the following: Replace the following:
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the specified bucket. - {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}:
_For InfluxDB to [auto-generate the DBRP mapping](/influxdb/cloud-serverless/guides/api-compatibility/v1/#retention-policy-and-dbrp-mapping), you must use an [All-Access API token](/influxdb/cloud-serverless/admin/tokens/#all-access-api-token) in the write request_. a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions
to the specified bucket.
_For InfluxDB to [auto-generate the DBRP mapping](/influxdb/cloud-serverless/guides/api-compatibility/v1/#retention-policy-and-dbrp-mapping), you must use an
[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.
<!--pytest-codeblocks:expected-output--> <!--pytest-codeblocks:expected-output-->
``` ```
204: 204
``` ```
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
<!------------------------------ END v1 API CONTENT ------------------------------> <!------------------------------ END v1 API CONTENT ------------------------------>
{{% /tab-content %}} {{% /tab-content %}}
{{% tab-content %}} {{% tab-content %}}
<!----------------------------- BEGIN v2 API CONTENT -----------------------------> <!----------------------------- BEGIN v2 API CONTENT ----------------------------->
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
To write data to InfluxDB using the [InfluxDB v2 HTTP API](/influxdb/cloud-serverless/reference/api/), send a To write data to InfluxDB using the
request to the InfluxDB API `/api/v2/write` endpoint using the `POST` request method. [InfluxDB v2 HTTP API](/influxdb/cloud-serverless/reference/api/), send a request
to the InfluxDB API `/api/v2/write` endpoint using the `POST` request method.
{{< api-endpoint endpoint="https://{{< influxdb/host >}}/api/v2/write" method="post" api-ref="/influxdb/cloud-serverless/api/#operation/PostWrite" >}} {{< api-endpoint endpoint="https://{{< influxdb/host >}}/api/v2/write"
method="post" api-ref="/influxdb/cloud-serverless/api/#operation/PostWrite" >}}
Include the following with your request: Include the following with your request:
@ -493,9 +528,9 @@ to InfluxDB:
{{% code-placeholders "API_TOKEN" %}} {{% code-placeholders "API_TOKEN" %}}
```sh ```sh
curl --silent -w "%{response_code}: %{errormsg}\n" \ response=$(curl --silent --write-out "%{response_code}:%{errormsg}" \
"https://{{< influxdb/host >}}/api/v2/write?bucket=get-started&precision=s" \ "https://{{< influxdb/host >}}/api/v2/write?bucket=get-started&precision=s" \
--header "Authorization: Token API_TOKEN" \ --header "Authorization: Bearer DATABASE_TOKEN" \
--header "Content-Type: text/plain; charset=utf-8" \ --header "Content-Type: text/plain; charset=utf-8" \
--header "Accept: application/json" \ --header "Accept: application/json" \
--data-binary " --data-binary "
@ -525,28 +560,47 @@ home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600
home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600 home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600
home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200 home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200
home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200
" ")
# Format the response code and error message output.
response_code=${response%%:*}
errormsg=${response#*:}
# Remove leading and trailing whitespace from errormsg
errormsg=$(echo "${errormsg}" | tr -d '[:space:]')
echo "$response_code"
if [[ $errormsg ]]; then
echo "$errormsg"
fi
``` ```
{{% /code-placeholders %}} {{% /code-placeholders %}}
Replace the following: Replace the following:
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the specified bucket - {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}:
a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions
to the specified bucket
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 status code and error message.
<!--pytest-codeblocks:expected-output--> <!--pytest-codeblocks:expected-output-->
``` ```
204: 204
``` ```
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
<!------------------------------ END v2 API CONTENT ------------------------------> <!------------------------------ END v2 API CONTENT ------------------------------>
{{% /tab-content %}} {{% /tab-content %}}
{{% tab-content %}} {{% tab-content %}}
<!---------------------------- BEGIN PYTHON CONTENT ---------------------------> <!---------------------------- BEGIN PYTHON CONTENT --------------------------->
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
To write data to {{% product-name %}} using Python, use the To write data to {{% product-name %}} using Python, use the
@ -590,7 +644,10 @@ dependencies to your current project.
pip install influxdb3-python pip install influxdb3-python
``` ```
The `influxdb3-python` package provides the `influxdb_client_3` module and also installs the [`pyarrow` package](https://arrow.apache.org/docs/python/index.html) for working with Arrow data returned from queries. The `influxdb3-python` package provides the `influxdb_client_3` module and
also installs the
[`pyarrow` package](https://arrow.apache.org/docs/python/index.html) for
working with Arrow data returned from queries.
5. In your terminal or editor, create a new file for your code--for example: `write.py`. 5. In your terminal or editor, create a new file for your code--for example: `write.py`.
@ -610,7 +667,7 @@ dependencies to your current project.
# API WRITE token value. # API WRITE token value.
token = os.getenv('INFLUX_TOKEN') token = os.getenv('INFLUX_TOKEN')
# host is the URL without protocol or trailing slash # host is the URL hostname without protocol or trailing slash
client = InfluxDBClient3( client = InfluxDBClient3(
host='{{< influxdb/host >}}', host='{{< influxdb/host >}}',
token=token, token=token,
@ -655,9 +712,12 @@ dependencies to your current project.
2. Calls the `InfluxDBClient3()` constructor to instantiate an InfluxDB client 2. Calls the `InfluxDBClient3()` constructor to instantiate an InfluxDB client
configured with the following credentials: configured with the following credentials:
- **`host`**: {{% product-name %}} region hostname (URL without protocol or trailing slash) - **`host`**: {{% product-name %}} region hostname (URL without protocol
- **`token`**: a [token](/influxdb/cloud-serverless/admin/tokens/) with _write_ access to the specified bucket. or trailing slash)
_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._
- **`database`**: the name of the {{% product-name %}} bucket to write to - **`database`**: the name of the {{% product-name %}} bucket to write to
3. Defines a list of line protocol strings where each string represents a data record. 3. Defines a list of line protocol strings where each string represents a data record.
@ -665,9 +725,11 @@ dependencies to your current project.
**Because the timestamps in the sample line protocol are in second **Because the timestamps in the sample line protocol are in second
precision, the example passes the `write_precision='s'` option precision, the example passes the `write_precision='s'` option
to set the [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) to seconds.** to set the
[timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision)
to seconds.**
6. To execute the module and write line protocol to your {{% product-name %}} 1. To execute the module and write line protocol to your {{% product-name %}}
bucket, enter the following command in your terminal: bucket, enter the following command in your terminal:
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
@ -686,7 +748,8 @@ dependencies to your current project.
To write data to {{% product-name %}} using Go, use the To write data to {{% product-name %}} using Go, use the
InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommunity/influxdb3-go). InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommunity/influxdb3-go).
1. Inside of your project directory, create a new module directory and navigate into it. 1. Inside of your project directory, create a new module directory and navigate
into it.
<!-- <!--
Using bash here is required when running with pytest. Using bash here is required when running with pytest.
@ -705,7 +768,8 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
go mod init influxdb_go_client go mod init influxdb_go_client
``` ```
3. In your terminal or editor, create a new file for your code--for example: `write.go`. 3. In your terminal or editor, create a new file for your code--for example:
`write.go`.
<!--pytest-codeblocks:cont--> <!--pytest-codeblocks:cont-->
@ -805,29 +869,33 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
The sample does the following: The sample does the following:
1. Imports required packages. 1. Imports required packages.
2. Defines a `WriteLineProtocol()` function that does the following: 2. Defines a `WriteLineProtocol()` function that does the following:
1. To instantiate the client, calls the `influxdb3.New(influxdb3.ClientConfig)` function and passes the following: 1. To instantiate the client, calls the
`influxdb3.New(influxdb3.ClientConfig)` function and passes the following:
- **`Host`**: your {{% product-name %}} region URL - **`Host`**: your {{% product-name %}} region URL
- **`Token`**: a [token](/influxdb/cloud-serverless/admin/tokens/) with _write_ access to the specified bucket. - **`Token`**: a [token](/influxdb/cloud-serverless/admin/tokens/)
_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
- **`WriteOptions`**: `influxdb3.WriteOptions` options for writing to InfluxDB. secret store or environment variable to avoid exposing the raw
token string._
- **`WriteOptions`**: `influxdb3.WriteOptions` options for writing
to InfluxDB.
**Because the timestamps in the sample line protocol are in second **Because the timestamps in the sample line protocol are in second
precision, the example passes the `Precision: lineprotocol.Second` option precision, the example passes the `Precision: lineprotocol.Second`
to set the [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) to seconds.** 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 returns.
2. Defines a deferred function that closes the client when the function
returns.
3. Defines an array of line protocol strings where each string 3. Defines an array of line protocol strings where each string
represents a data record. represents a data record.
4. Iterates through the array of line protocol and calls the write
client's `Write()` method to write each line of line protocol
separately to InfluxDB.
4. Iterates through the array of line protocol and calls the 5. In your editor, create a `main.go` file and enter the following sample code
write client's `Write()` method that calls the `WriteLineProtocol()` function:
to write each line of line protocol separately to InfluxDB.
4. In your editor, create a `main.go` file and enter the following sample code that calls the `WriteLineProtocol()` function:
```go ```go
package main package main
@ -838,7 +906,9 @@ 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. 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:
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
@ -855,15 +925,19 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
<!---------------------------- BEGIN NODE.JS CONTENT ---------------------------> <!---------------------------- BEGIN NODE.JS CONTENT --------------------------->
1. If you haven't already, follow the instructions for [Downloading and installing Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) for your system. 1. If you haven't already, follow the instructions for
2. In your terminal, enter the following command to create a `influxdb_js_client` directory for your project: [Downloading and installing Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
for your system.
2. In your terminal, enter the following command to create a
`influxdb_js_client` directory for your project:
```bash ```bash
mkdir influxdb_js_client && cd influxdb_js_client mkdir influxdb_js_client && cd influxdb_js_client
``` ```
3. Inside of `influxdb_js_client`, enter the following command to initialize a package. 3. Inside of `influxdb_js_client`, enter the following command to initialize a
This example configures the package to use [ECMAScript modules (ESM)](https://nodejs.org/api/packages.html#modules-loaders). package. This example configures the package to use
[ECMAScript modules (ESM)](https://nodejs.org/api/packages.html#modules-loaders).
<!--pytest-codeblocks:cont--> <!--pytest-codeblocks:cont-->
@ -871,7 +945,8 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
npm init -y; npm pkg set type="module" npm init -y; npm pkg set type="module"
``` ```
4. Install the `@influxdata/influxdb3-client` JavaScript client library as a dependency to your project. 4. Install the `@influxdata/influxdb3-client` JavaScript client library as a
dependency to your project.
<!--pytest-codeblocks:cont--> <!--pytest-codeblocks:cont-->
@ -896,8 +971,8 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
/** /**
* Set InfluxDB credentials. * Set InfluxDB credentials.
*/ */
const host = "https://cloud2.influxdata.com"; const host = '{{< influxdb/host >}}';
const database = "get-started"; const database = 'get-started';
/** /**
* INFLUX_TOKEN is an environment variable you assigned to your * INFLUX_TOKEN is an environment variable you assigned to your
* API WRITE token value. * API WRITE token value.
@ -969,30 +1044,40 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
The sample code does the following: The sample code does the following:
1. Imports the `InfluxDBClient` class. 1. Imports the `InfluxDBClient` class.
2. Calls the `new InfluxDBClient()` constructor and passes a `ClientOptions` object to instantiate a client configured 2. Calls the `new InfluxDBClient()` constructor and passes a
with InfluxDB credentials. `ClientOptions` object to instantiate a client configured with InfluxDB
credentials.
- **`host`**: your {{% product-name %}} region URL - **`host`**: your {{% product-name %}} region URL
- **`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._ _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. 3. Defines a list of line protocol strings where each string represents a
4. Calls the client's `write()` method for each record, defines the success or failure message to return, and collects the pending promises into the `writePromises` array. data record.
Each call to `write()` passes the following arguments: 4. Calls the client's `write()` method for each record, defines the success
or failure message to return, and collects the pending promises into the
`writePromises` array. Each call to `write()` passes the following
arguments:
- **`record`**: the line protocol record - **`record`**: the line protocol record
- **`database`**: the name of the {{% product-name %}} bucket to write to - **`database`**: the name of the {{% product-name %}} bucket to write to
- **`{precision}`**: a `WriteOptions` object that sets the `precision` value. - **`{precision}`**: a `WriteOptions` object that sets the `precision` value.
**Because the timestamps in the sample line protocol are in second **Because the timestamps in the sample line protocol are in second
precision, the example passes `s` as the `precision` value to set the write precision, the example passes `s` as the `precision` value to set the
[timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) to seconds.** write
[timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision)
to seconds.**
5. Calls `Promise.allSettled()` with the promises array to pause execution until the promises have completed, and then assigns the array containing success and failure messages to a `writeResults` constant. 5. Calls `Promise.allSettled()` with the promises array to pause execution
7. Iterates over and prints the messages in `writeResults`. until the promises have completed, and then assigns the array containing
8. Closes the client to release resources. 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. 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()`: 8. Inside of `index.js`, enter the following sample code to import and call
`writeLineProtocol()`:
```js ```js
// index.js // index.js
@ -1018,14 +1103,21 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
``` ```
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
<!---------------------------- END NODE.JS CONTENT ---------------------------> <!---------------------------- END NODE.JS CONTENT --------------------------->
{{% /tab-content %}} {{% /tab-content %}}
{{% tab-content %}} {{% tab-content %}}
<!---------------------------- BEGIN C# CONTENT ---------------------------> <!---------------------------- BEGIN C# CONTENT --------------------------->
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
1. If you haven't already, follow the [Microsoft.com download instructions](https://dotnet.microsoft.com/en-us/download) to install .NET and the `dotnet` CLI. 1. If you haven't already, follow the
2. In your terminal, create an executable C# project using the .NET **console** template. [Microsoft.com download instructions](https://dotnet.microsoft.com/en-us/download)
to install .NET and the `dotnet` CLI.
2. In your terminal, create an executable C# project using the .NET **console**
template.
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
@ -1227,7 +1319,9 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
... ...
</dependencies> </dependencies>
``` ```
5. To validate your `pom.xml`, run Maven's `validate` command--for example, enter the following in your terminal:
5. To check your `pom.xml` for problems, run Maven's `validate` command--for example,
enter the following in your terminal:
<!--pytest.mark.skip--> <!--pytest.mark.skip-->

48
content/influxdb/clustered/get-started/write.md
View File

@ -48,6 +48,8 @@ information, see the
Each line of line protocol contains the following elements: Each line of line protocol contains the following elements:
<!-- vale InfluxDataDocs.v3Schema = NO -->
{{< req type="key" >}} {{< req type="key" >}}
- {{< req "\*" >}} **measurement**: A string that identifies the - {{< req "\*" >}} **measurement**: A string that identifies the
@ -68,15 +70,14 @@ Each line of line protocol contains the following elements:
#### Line protocol element parsing #### Line protocol element parsing
<!-- vale InfluxDataDocs.v3Schema = NO --> - **measurement**: Everything before the _first unescaped comma before the first
whitespace_.
- **measurement**: Everything before the _first unescaped comma before the first whitespace_. - **tag set**: Key-value pairs between the _first unescaped comma_ and the _first
- **tag set**: Key-value pairs between the _first unescaped comma_ and the _first unescaped whitespace_. unescaped whitespace_.
- **field set**: Key-value pairs between the _first and second unescaped whitespaces_. - **field set**: Key-value pairs between the _first and second unescaped whitespaces_.
- **timestamp**: Integer value after the _second unescaped whitespace_. - **timestamp**: Integer value after the _second unescaped whitespace_.
- Lines are separated by the newline character (`\n`). - Lines are separated by the newline character (`\n`).
Line protocol is whitespace sensitive. Line protocol is whitespace sensitive.
<!-- vale InfluxDataDocs.v3Schema = YES -->
--- ---
@ -94,8 +95,6 @@ Consider a use case where you collect data from sensors in your home.
Each sensor collects temperature, humidity, and carbon monoxide readings. Each sensor collects temperature, humidity, and carbon monoxide readings.
To collect this data, use the following schema: To collect this data, use the following schema:
<!-- vale InfluxDataDocs.v3Schema = NO -->
- **measurement**: `home` - **measurement**: `home`
- **tags** - **tags**
- `room`: Living Room or Kitchen - `room`: Living Room or Kitchen
@ -106,9 +105,8 @@ To collect this data, use the following schema:
- **timestamp**: Unix timestamp in _second_ precision - **timestamp**: Unix timestamp in _second_ precision
<!-- vale InfluxDataDocs.v3Schema = YES --> <!-- vale InfluxDataDocs.v3Schema = YES -->
Data is collected hourly beginning at The following line protocol sample represents data collected hourly beginning at
{{% influxdb/custom-timestamps-span %}}**2022-01-01T08:00:00Z (UTC)** until **2022-01-01T20:00:00Z (UTC)**{{% /influxdb/custom-timestamps-span %}}. {{% influxdb/custom-timestamps-span %}}**2022-01-01T08:00:00Z (UTC)** until **2022-01-01T20:00:00Z (UTC)**{{% /influxdb/custom-timestamps-span %}}.
The resulting line protocol would look something like the following:
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
@ -305,7 +303,10 @@ and then write it to {{< product-name >}}.
``` ```
--> -->
- **`output-influxdb_v2` output plugin**: In the `[[outputs.influxdb_v2]]` section, replace the default values with the following configuration for your {{% product-name %}} database: - **`output-influxdb_v2` output plugin**: In the `[[outputs.influxdb_v2]]`
section, replace the default values with the following configuration for your
{{% product-name %}} database:
```toml ```toml
[[outputs.influxdb_v2]] [[outputs.influxdb_v2]]
@ -377,19 +378,23 @@ To learn more, see how to [use Telegraf to write data](/influxdb/clustered/write
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
Write data with your existing workloads that already use the InfluxDB v1 `/write` API endpoint. Write data with your existing workloads that already use the InfluxDB v1 `/write`
API endpoint.
{{% note %}} {{% note %}}
If migrating data from InfluxDB 1.x, see the If migrating data from InfluxDB 1.x, see the
[Migrate data from InfluxDB 1.x to InfluxDB {{% product-name %}}](/influxdb/clustered/guides/migrate-data/migrate-1x-to-clustered/) guide. [Migrate data from InfluxDB 1.x to InfluxDB
{{% product-name %}}](/influxdb/clustered/guides/migrate-data/migrate-1x-to-clustered/)
guide.
{{% /note %}} {{% /note %}}
To write data to InfluxDB using the To write data to InfluxDB using the
[InfluxDB v1 HTTP API](/influxdb/clustered/reference/api/), send a [InfluxDB v1 HTTP API](/influxdb/clustered/reference/api/), send a
request to the request to the
[InfluxDB API `/write` endpoint](/influxdb/clustered/api/#operation/PostLegacyWrite) using the `POST` request method. [InfluxDB API `/write` endpoint](/influxdb/clustered/api/#operation/PostLegacyWrite)
using the `POST` request method.
{{% api-endpoint endpoint="https://{{< influxdb/host >}}/write" method="post" api-ref="/influxdb/clustered/api/#operation/PostLegacyWrite"%}} {{% api-endpoint endpoint="https://{{< influxdb/host >}}/write" method="post" api-ref="/influxdb/clustered/api/#operation/PostLegacyWrite"%}}
@ -405,8 +410,12 @@ Include the following with your request:
- **Request body**: Line protocol as plain text - **Request body**: Line protocol as plain text
{{% note %}} {{% note %}}
With the {{% product-name %}} [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. With the {{% product-name %}}
For more information about HTTP API token schemes, see how to [authenticate API requests](/influxdb/clustered/guides/api-compatibility/v1/). [v1 API `/write` endpoint](/influxdb/cloud-dedicated/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/).
{{% /note %}} {{% /note %}}
The following example uses cURL and the InfluxDB v1 API to write line protocol The following example uses cURL and the InfluxDB v1 API to write line protocol
@ -580,7 +589,8 @@ Replace the following:
a [database token](/influxdb/clustered/admin/tokens/#database-tokens) with a [database token](/influxdb/clustered/admin/tokens/#database-tokens) with
sufficient permissions to the specified database 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 status code and error message.
<!--pytest-codeblocks:expected-output--> <!--pytest-codeblocks:expected-output-->
@ -664,7 +674,7 @@ dependencies to your current project.
# database WRITE token value. # database WRITE token value.
token = os.getenv('INFLUX_TOKEN') token = os.getenv('INFLUX_TOKEN')
# host is the URL without protocol or trailing slash # host is the URL hostname without protocol or trailing slash
client = InfluxDBClient3( client = InfluxDBClient3(
host='{{< influxdb/host >}}', host='{{< influxdb/host >}}',
org='', org='',
@ -985,7 +995,7 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3
/** /**
* Set InfluxDB credentials. * Set InfluxDB credentials.
*/ */
const host = 'https://cluster-id.influxdb.io'; const host = '{{< influxdb/host >}}';
const database = 'get-started'; const database = 'get-started';
/** /**
* INFLUX_TOKEN is an environment variable you assigned to your * INFLUX_TOKEN is an environment variable you assigned to your