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

5156 Writes: add v1 to Serverless get-started (#5233) 

* chore(ci): Install Telegraf to test container

* chore(v3): test telegraf config and startup:

- creates the config file for the test run. TODO: remove the duplication and use the content for test setup.
- fix placeholder name

* fix(v3): make test pass for curl API example

* chore(ci): make tests pass for write. Add dependencies to Dockerfile.

* chore(tests): update test build

- Compose metadata: Add profile to test service. We can decouple services later and apply the profile to each. Rename. Pass the image name to the container.
- Fetch the parse_yaml.sh script during docker build, so we only fetch when necessary. Track the script in git. This is still a little janky, but better.
- test.sh: Use `HEAD` for diff (duh). Go back to using docker compose up so we're rebuilding only as needed and reusing the container - much faster, but the output isn't as pretty as `run`.
- pytest.ini, requirements.txt: Use pytest-dotenv to load env.products variables.

* fix(write): update JS instructions and pass tests.

* chore(ci): Install influx v2 CLI into the Docker test container.

* chore(ci): move .env file loading to pytest and run product tests separately with the proper .env file:

- Moves .env configs to be loaded by the test runner instead of by Docker. I'd prefer to ignore any product divergence and have them run interchangeably, but the pros outweigh the cons for now.
- Add example for passing custom commands in the compose file.

* fix(v3): replace curl example with v1 and v2, simplify JS example, pass tests.

feat(v3): add v1 write, test, update text:

- adds Serverless v1 /write example with note about autogen behavior
- adds link from v1 examples to Migrate guide
- adds description of autogen behavior to v1-compat guide
- updates "powered by..." text
- adapts examples to make them more testable, asserts `/write` status code
- replace "shared" examples (only used once) with inline to make them testable

fix(v3): promote migrate link

* Update content/influxdb/cloud-dedicated/get-started/write.md

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* chore(v3): Write: fix wording for curl success  (#5156)

---------

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
pull/5236/head^2
Jason Stirnaman 2023-11-15 14:41:29 -06:00 committed by GitHub
parent 491dfc50d7
commit 5c74bf4ff6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
22 changed files with 1107 additions and 381 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
Dockerfile
View File

@ -1,47 +0,0 @@
# If you need more help, visit the Dockerfile reference guide at
# https://docs.docker.com/engine/reference/builder/
FROM python:3.12.0-slim-bookworm
RUN apt-get update && apt-get install -y \
curl \
git \
gpg \
wget \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /usr/src/app
ARG SOURCE_DIR
COPY test ./test
COPY data ./test/data
RUN chmod -R 755 .
# Prevents Python from writing pyc files.
ENV PYTHONDONTWRITEBYTECODE=1
# the application crashes without emitting any logs due to buffering.
ENV PYTHONUNBUFFERED=1
WORKDIR /usr/src/app/${SOURCE_DIR}
COPY test/run-tests.sh /usr/local/bin/run-tests.sh
RUN chmod +x /usr/local/bin/run-tests.sh
# Download dependencies as a separate step to take advantage of Docker's caching.
# Leverage a cache mount to /root/.cache/pip to speed up subsequent builds.
# Leverage a bind mount to requirements.txt to avoid having to copy them into
# this layer.
RUN --mount=type=cache,target=/root/.cache/pip \
--mount=type=bind,source=test/requirements.txt,target=./requirements.txt \
python -m pip install -r ./requirements.txt
# RUN --mount=type=cache,target=/root/.cache/node_modules \
# --mount=type=bind,source=package.json,target=package.json \
# npm install
ENV TEMP_DIR=./tmp
ENTRYPOINT [ "run-tests.sh" ]
CMD [""]

10
compose.yaml
View File

@ -4,9 +4,8 @@ services:
test:
image: docs-v2-tests
container_name: docs-v2-tests
env_file:
- ./test/.env.influxdbv2
- ./test/.env.influxdbv3
profiles:
- test
volumes:
- type: bind
source: ./test
@ -16,6 +15,7 @@ services:
target: /usr/src/app/test/data
build:
context: .
dockerfile: Dockerfile
dockerfile: test.Dockerfile
args:
- SOURCE_DIR=test
- SOURCE_DIR=test
- DOCKER_IMAGE=docs-v2-tests

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

@ -103,7 +103,7 @@ The resulting line protocol would look something like the following:
##### Home sensor data line protocol
```sh
```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
@ -161,6 +161,8 @@ credentials (**URL**, **organization**, and **token**) are provided by
{{% /tabs %}}
{{% tab-content %}}
<!------------------------------- BEGIN TELEGRAF CONTENT ------------------------------>
{{% influxdb/custom-timestamps %}}
Use [Telegraf](/telegraf/v1/) to consume line protocol,
and then write it to {{< product-name >}}.
@ -168,6 +170,37 @@ and then write it to {{< product-name >}}.
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
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
home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600
home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600
home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200
home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200
home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800
home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800
home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400
home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400
home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000
home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000
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=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200
home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200
EOF
```
3. Run the following command to generate a Telegraf configuration file (`./telegraf.conf`) that enables the `inputs.file` and `outputs.influxdb_v2` plugins:
```sh
@ -189,12 +222,21 @@ and then write it to {{< product-name >}}.
files = ["home.lp"]
```
<!--test
```bash
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
```
-->
- **`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
[[outputs.influxdb_v2]]
# InfluxDB Cloud Dedicated cluster URL
urls = ["${INFLUX_URL}"]
# InfluxDB cluster URL
urls = ["${INFLUX_HOST}"]
# INFLUX_TOKEN is an environment variable you assigned to your database token
token = "${INFLUX_TOKEN}"
@ -206,9 +248,26 @@ and then write it to {{< product-name >}}.
bucket = "get-started"
```
<!--test
```bash
echo '[[outputs.influxdb_v2]]' >> telegraf.conf
echo ' # InfluxDB cluster URL' >> telegraf.conf
echo ' urls = ["${INFLUX_HOST}"]' >> telegraf.conf
echo '' >> telegraf.conf
echo ' # INFLUX_TOKEN is an environment variable you assigned to your database token' >> telegraf.conf
echo ' token = "${INFLUX_TOKEN}"' >> telegraf.conf
echo '' >> telegraf.conf
echo ' # An empty string (InfluxDB ignores this parameter)' >> telegraf.conf
echo ' organization = ""' >> telegraf.conf
echo '' >> telegraf.conf
echo ' # Database name' >> telegraf.conf
echo ' bucket = "get-started"' >> telegraf.conf
```
-->
The example configuration uses the following InfluxDB credentials:
- **`urls`**: an array containing your **`INFLUX_URL`** environment variable
- **`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
@ -235,12 +294,21 @@ and then write it to {{< product-name >}}.
Telegraf and its plugins provide many options for reading and writing data.
To learn more, see how to [use Telegraf to write data](/influxdb/cloud-dedicated/write-data/use-telegraf/).
{{% /influxdb/custom-timestamps %}}
<!------------------------------- END TELEGRAF CONTENT ------------------------------>
{{% /tab-content %}}
{{% tab-content %}}
<!----------------------------- BEGIN v1 API CONTENT ----------------------------->
{{% influxdb/custom-timestamps %}}
Write data with your existing workloads that already use the InfluxDB v1 `/write` API endpoint.
{{% note %}}
If migrating data from InfluxDB 1.x, see the [Migrate data from InfluxDB 1.x to InfluxDB {{% product-name %}}](/influxdb/cloud-dedicated/guides/migrate-data/migrate-1x-to-cloud-dedicated/) guide.
{{% /note %}}
To write data to InfluxDB using the [InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/reference/api/), send a
request to the [InfluxDB API `/write` endpoint](/influxdb/cloud-dedicated/api/#operation/PostLegacyWrite) using the `POST` request method.
@ -266,13 +334,14 @@ The following example uses cURL and the InfluxDB v1 API to write line protocol
to InfluxDB:
{{% code-placeholders "DATABASE_TOKEN" %}}
{{% influxdb/custom-timestamps %}}
```sh
curl -i 'https://{{< influxdb/host >}}/write?db=get-started&precision=s' \
--header 'Authorization: Bearer DATABASE_TOKEN' \
--header "Content-type: text/plain; charset=utf-8" \
--header "Accept: application/json" \
--data-binary "
curl --silent -w "%{response_code}: %{errormsg}\n" \
"https://{{< influxdb/host >}}/write?db=get-started&precision=s" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--header "Accept: application/json" \
--data-binary "
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
@ -301,15 +370,27 @@ 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
"
```
{{% /influxdb/custom-timestamps %}}
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the specified database
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the specified database
If successful, the output is an HTTP `204 No Content` status code.
<!--pytest-codeblocks:expected-output-->
```
204:
```
{{% /influxdb/custom-timestamps %}}
<!------------------------------ END v1 API CONTENT ------------------------------>
{{% /tab-content %}}
{{% tab-content %}}
<!----------------------------- BEGIN v2 API CONTENT ----------------------------->
{{% influxdb/custom-timestamps %}}
To write data to InfluxDB using the [InfluxDB v2 HTTP API](/influxdb/cloud-dedicated/reference/api/), send a
request to the InfluxDB API `/api/v2/write` endpoint using the `POST` request method.
@ -328,17 +409,17 @@ Include the following with your request:
- **Request body**: Line protocol as plain text
{{% note %}}
With the {{% product-name %}} v2 API `/api/v2/write` endpoint, `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/v2/).
The {{% product-name %}} v2 API `/api/v2/write` endpoint supports `Bearer` and `Token` authorization schemes 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/v2/).
{{% /note %}}
The following example uses cURL and the InfluxDB v2 API to write line protocol
to InfluxDB:
{{% code-placeholders "DATABASE_TOKEN"%}}
{{% influxdb/custom-timestamps %}}
```sh
curl --request POST \
"https://{{< influxdb/host >}}/api/v2/write?bucket=get-started&precision=s" \
curl --silent -w "%{response_code}: %{errormsg}\n" \
"https://{{< influxdb/host >}}/api/v2/write?bucket=get-started&precision=s" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--header "Content-Type: text/plain; charset=utf-8" \
--header "Accept: application/json" \
@ -371,8 +452,22 @@ 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
"
```
{{% /influxdb/custom-timestamps %}}
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the specified database
If successful, the output is an HTTP `204 No Content` status code.
<!--pytest-codeblocks:expected-output-->
```
204:
```
{{% /influxdb/custom-timestamps %}}
<!------------------------------ END v2 API CONTENT ------------------------------>
{{% /tab-content %}}
{{% tab-content %}}
@ -386,26 +481,37 @@ dependencies to your current project.
1. Create a module directory and navigate into it--for example:
```sh
mkdir influxdb_py_client && cd $_
<!--
Using bash here is required when running with pytest.
I don't know why, but sh evaluates $_ to /usr/bin/pytest.
-->
```bash
mkdir -p influxdb_py_client && cd influxdb_py_client
```
2. Setup your Python virtual environment.
Inside of your module directory:
```sh
<!--pytest-codeblocks:cont-->
```bash
python -m venv envs/virtual-env
```
3. Activate the virtual environment.
```sh
<!--pytest-codeblocks:cont-->
```bash
source ./envs/virtual-env/bin/activate
```
4. Install the client library package:
```sh
<!--pytest-codeblocks:cont-->
```bash
pip install influxdb3-python
```
@ -413,7 +519,9 @@ dependencies to your current project.
5. In your terminal or editor, create a new file for your code--for example: `write.py`.
```sh
<!--pytest-codeblocks:cont-->
```bash
touch write.py
```
@ -475,7 +583,7 @@ dependencies to your current project.
- **`host`**: {{% product-name omit=" Clustered" %}} cluster hostname (URL without protocol or trailing slash)
- **`org`**: an empty or arbitrary string (InfluxDB ignores this parameter)
- **`token`**: an InfluxDB [database token](/influxdb/cloud-dedicated/admin/tokens/) with write access to the target database.
- **`token`**: a [token](/influxdb/cloud-dedicated/admin/tokens/) with write access to the specified database.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
- **`database`**: the name of the {{% product-name %}} database to write to
@ -484,14 +592,16 @@ dependencies to your current project.
**Because the timestamps in the sample line protocol are in second
precision, the example passes the `write_precision='s'` option
to set the[timestamp precision](/influxdb/cloud-dedicated/reference/glossary/#timestamp-precision) to seconds.**
to set the [timestamp precision](/influxdb/cloud-dedicated/reference/glossary/#timestamp-precision) to seconds.**
6. To execute the module and write line protocol to your {{% product-name %}}
database, enter the following command in your terminal:
```sh
python write.py
```
<!--pytest.mark.skip-->
```bash
python write.py
```
{{% /influxdb/custom-timestamps %}}
@ -506,19 +616,28 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
1. Inside of your project directory, create a new module directory and navigate into it.
```sh
mkdir influxdb_go_client && cd $_
<!--
Using bash here is required when running with pytest.
I don't know why, but sh evaluates $_ to /usr/bin/pytest.
-->
```bash
mkdir -p influxdb_go_client && cd influxdb_go_client
```
2. Initialize a new Go module in the directory.
```sh
<!--pytest-codeblocks:cont-->
```bash
go mod init influxdb_go_client
```
3. In your terminal or editor, create a new file for your code--for example: `write.go`.
```sh
<!--pytest-codeblocks:cont-->
```bash
touch write.go
```
@ -620,7 +739,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
1. To instantiate the client, calls the `influxdb3.New(influxdb3.ClientConfig)` function and passes the following:
- **`Host`**: the {{% product-name omit=" Clustered" %}} cluster URL
- **`Database`**: The name of your {{% product-name %}} database
- **`Token`**: an InfluxDB [database token](/influxdb/cloud-dedicated/admin/tokens/) with _write_ access to the specified database.
- **`Token`**: a [token](/influxdb/cloud-dedicated/admin/tokens/) with _write_ access to the specified database.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
- **`WriteOptions`**: `influxdb3.WriteOptions` options for writing to InfluxDB.
@ -650,6 +769,8 @@ 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:
<!--pytest.mark.skip-->
```sh
go mod tidy && go build && go run influxdb_go_client
```
@ -664,27 +785,41 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
<!---------------------------- 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.
2. In your terminal, enter the following command to create a `influxdb_js_client` project and `package.json` file:
2. In your terminal, enter the following command to create a `influxdb_js_client` directory for your project:
```sh
npm init -y -w influxdb_js_client
```bash
mkdir influxdb_js_client && cd influxdb_js_client
```
3. Change into the `influxdb_js_client` directory.
3. Inside of `influxdb_js_client`, enter the following command to initialize a package.
This example configures the package to use [ECMAScript modules (ESM)](https://nodejs.org/api/packages.html#modules-loaders).
```sh
cd influxdb_js_client
<!--pytest-codeblocks:cont-->
```bash
npm init -y; npm pkg set type="module"
```
4. Install the `@influxdata/influxdb3-client` JavaScript client library as a dependency to your project:
```sh
4. Install the `@influxdata/influxdb3-client` JavaScript client library as a dependency to your project.
<!--pytest-codeblocks:cont-->
```bash
npm install --save @influxdata/influxdb3-client
```
5. In your terminal or editor, create a `write.mjs` file. The `.mjs` extension tells the Node.js interpreter that this is an [ES6 module](https://nodejs.org/api/esm.html#modules-ecmascript-modules).
6. Inside of `write.mjs`, enter the following sample code:
5. In your terminal or editor, create a `write.js` file.
<!--pytest-codeblocks:cont-->
```bash
touch write.js
```
6. Inside of `write.js`, enter the following sample code:
```js
// write.mjs
// write.js
import { InfluxDBClient } from "@influxdata/influxdb3-client";
/**
@ -694,7 +829,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
const database = "get-started";
/**
* INFLUX_TOKEN is an environment variable you assigned to your
* database WRITE token value.
* WRITE token value.
*/
const token = process.env.INFLUX_TOKEN;
@ -767,7 +902,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
with InfluxDB credentials.
- **`host`**: your {{% product-name omit=" Clustered" %}} cluster URL
- **`token`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with _write_ access to the specified database.
- **`token`**: a [token](/influxdb/cloud-dedicated/admin/tokens/) with _write_ access to the specified database.
_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.
@ -785,12 +920,12 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
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.
7. Iterates over and prints the messages in `writeResults`.
8. Closes the client to release resources.
7. In your terminal or editor, create an `index.mjs` file.
8. Inside of `index.mjs`, enter the following sample code to import and call `writeLineProtocol()`:
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()`:
```js
// index.mjs
import { writeLineProtocol } from "./write.mjs";
// index.js
import { writeLineProtocol } from "./write.js";
/**
* Execute the client functions.
@ -803,10 +938,12 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
main();
```
9. In your terminal, execute `index.mjs` to write to {{% product-name %}}:
9. In your terminal, execute `index.js` to write to {{% product-name %}}:
<!--pytest-codeblocks:cont-->
```sh
node index.mjs
node index.js
```
{{% /influxdb/custom-timestamps %}}
@ -818,18 +955,24 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
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.
2. In your terminal, create an executable C# project using the .NET **console** template.
<!--pytest.mark.skip-->
```sh
dotnet new console --name influxdb_csharp_client
```
3. Change into the generated `influxdb_csharp_client` directory.
<!--pytest.mark.skip-->
```sh
cd influxdb_csharp_client
```
4. Run the following command to install the latest version of the InfluxDB v3 C# client library.
<!--pytest.mark.skip-->
```sh
dotnet add package InfluxDB3.Client
```
@ -860,7 +1003,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
/**
* INFLUX_TOKEN is an environment variable you assigned to your
* database WRITE token value.
* WRITE token value.
*/
string? token = System.Environment
.GetEnvironmentVariable("INFLUX_TOKEN");
@ -924,7 +1067,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
- **`host`**: your {{% product-name omit=" Clustered" %}} cluster URL
- **`database`**: the name of the {{% product-name %}} database to write to
- **`token`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with _write_ access to the specified bucket.
- **`token`**: a [token](/influxdb/cloud-dedicated/admin/tokens/) 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._
@ -961,6 +1104,8 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
7. To build and execute the program and write the line protocol to your {{% product-name %}} database, enter the following command in your terminal:
<!--pytest.mark.skip-->
```sh
dotnet run
```
@ -976,7 +1121,7 @@ _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.
2. In your terminal or editor, use Maven to generate a project--for example:
```sh
```bash
mvn org.apache.maven.plugins:maven-archetype-plugin:3.1.2:generate \
-DarchetypeArtifactId="maven-archetype-quickstart" \
-DarchetypeGroupId="org.apache.maven.archetypes" -DarchetypeVersion="1.4" \
@ -989,9 +1134,12 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
3. In your terminal or editor, change into the `./influxdb_java_client` directory--for example:
```sh
<!--pytest-codeblocks:cont-->
```bash
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`.
```pom
@ -1008,7 +1156,9 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
```
5. To validate your `pom.xml`, run Maven's `validate` command--for example, enter the following in your terminal:
```sh
<!--pytest.mark.skip-->
```bash
mvn validate
```
@ -1047,7 +1197,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
/**
* INFLUX_TOKEN is an environment variable you assigned to your
* database WRITE token value.
* WRITE token value.
*/
final char[] token = (System.getenv("INFLUX_TOKEN")).
toCharArray();
@ -1115,7 +1265,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
- **`host`**: your {{% product-name omit=" Clustered" %}} cluster URL
- **`database`**: the name of the {{% product-name %}} database to write to
- **`token`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with _write_ access to the specified database.
- **`token`**: a [token](/influxdb/cloud-dedicated/admin/tokens/) with _write_ access to the specified database.
_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.
@ -1153,12 +1303,16 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
- `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:
```sh
<!--pytest.mark.skip-->
```bash
mvn compile
```
10. In your terminal or editor, execute `App.main()` to write to InfluxDB--for example, using Maven:
<!--pytest.mark.skip-->
```sh
mvn exec:java -Dexec.mainClass="com.influxdbv3.App"
```

4
content/influxdb/cloud-dedicated/guides/migrate-data/_index.md
View File

@ -14,7 +14,7 @@ alt_links:
cloud: /influxdb/cloud/write-data/migrate-data/
---
Migrate data to InfluxDB Cloud Dedicated from other
Migrate data to InfluxDB Cloud Dedicated from other
InfluxDB instances powered by TSM including InfluxDB OSS 1.x, 2.x,
InfluxDB Enterprise, and InfluxDB Cloud (TSM).
@ -52,7 +52,7 @@ series data with SQL. For more information about querying your data with SQL, se
**Yes, you should migrate**. One of the primary goals when designing the InfluxDB
IOx storage engine was to enable performant implementations of both SQL and InfluxQL.
When compared to querying InfluxDB powered by TSM (InfluxDB OSS 1.x, 2.x, and Enterprise),
InfluxQL queries are more performant when querying InfluxDB powered by InfluxDB IOx.
InfluxQL queries are more performant when querying InfluxDB powered by the v3 storage engine.
#### Do you depend on a specific cloud provider or region?

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

@ -103,7 +103,7 @@ The resulting line protocol would look something like the following:
##### Home sensor data line protocol
```sh
```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
@ -153,7 +153,8 @@ credentials (**URL**, **organization**, and **token**) are provided by
[InfluxDB UI](#)
[influx CLI](#)
[Telegraf](#)
[cURL](#)
[v1 API](#)
[v2 API](#)
[Python](#)
[Go](#)
[Node.js](#)
@ -180,7 +181,7 @@ credentials (**URL**, **organization**, and **token**) are provided by
into the line protocol text field.
7. Click **{{< caps >}}Write Data{{< /caps >}}**.
The UI will confirm that the data has been written successfully.
The UI confirms that the data has been written successfully.
<!------------------------------- END UI CONTENT ------------------------------>
{{% /tab-content %}}
@ -189,7 +190,7 @@ The UI will confirm that the data has been written successfully.
1. If you haven't already, [download, install, and configure the `influx` CLI](/influxdb/cloud-serverless/get-started/setup/?t=influx+CLI#download-install-and-configure-the-influx-cli).
2. Use the [`influx write` command](/influxdb/cloud-serverless/reference/cli/influx/write/)
to write the [line protocol above](#home-sensor-data-line-protocol) to InfluxDB.
to write the [preceding line protocol](#home-sensor-data-line-protocol) to InfluxDB.
**Provide the following**:
@ -198,7 +199,7 @@ The UI will confirm that the data has been written successfully.
- String-encoded line protocol.
- [Connection and authentication credentials](/influxdb/cloud-serverless/get-started/setup/?t=influx+CLI#configure-authentication-credentials)
{{% influxdb/custom-timestamps %}}
{{< influxdb/custom-timestamps >}}
```sh
influx write \
@ -232,19 +233,53 @@ 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
"
```
{{% /influxdb/custom-timestamps %}}
{{< /influxdb/custom-timestamps >}}
<!------------------------------ END CLI CONTENT ------------------------------>
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------- BEGIN TELEGRAF CONTENT ------------------------------>
Use [Telegraf](/telegraf/v1/) to consume line protocol,
and then write it to {{< product-name >}}.
{{< influxdb/custom-timestamps >}}
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/).
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
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
home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600
home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600
home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200
home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200
home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800
home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800
home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400
home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400
home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000
home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000
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=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200
home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200
EOF
```
3. Run the following command to generate a Telegraf configuration file (`./telegraf.conf`) that enables the `inputs.file` and `outputs.influxdb_v2` plugins:
```sh
@ -266,12 +301,21 @@ and then write it to {{< product-name >}}.
files = ["home.lp"]
```
- **`output-influxdb_v2` output plugin**: In the `[[outputs.influxdb_v2]]` section, replace the default values with the following configuration for your InfluxDB Cloud Serverless bucket:
p
<!--test
```bash
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
```
-->
- **`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
[[outputs.influxdb_v2]]
# InfluxDB Cloud Serverless region URL
urls = ["${INFLUX_URL}"]
# InfluxDB Cloud Serverless URL
urls = ["${INFLUX_HOST}"]
# INFLUX_TOKEN is an environment variable you assigned to your API token
token = "${INFLUX_TOKEN}"
@ -283,9 +327,26 @@ p
bucket = "get-started"
```
<!--test
```bash
echo '[[outputs.influxdb_v2]]' >> telegraf.conf
echo ' # InfluxDB URL' >> telegraf.conf
echo ' urls = ["${INFLUX_HOST}"]' >> 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 '' >> telegraf.conf
echo ' # An empty string (InfluxDB ignores this parameter)' >> telegraf.conf
echo ' organization = ""' >> telegraf.conf
echo '' >> telegraf.conf
echo ' # Database name' >> telegraf.conf
echo ' bucket = "get-started"' >> telegraf.conf
```
-->
The example configuration uses the following InfluxDB credentials:
- **`urls`**: an array containing your **`INFLUX_URL`** environment variable
- **`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 bucket to write to
@ -312,13 +373,106 @@ p
Telegraf and its plugins provide many options for reading and writing data.
To learn more, see how to [use Telegraf to write data](/influxdb/cloud-serverless/write-data/use-telegraf/).
{{< /influxdb/custom-timestamps >}}
<!------------------------------- END TELEGRAF CONTENT ------------------------------>
{{% /tab-content %}}
{{% tab-content %}}
<!----------------------------- BEGIN cURL CONTENT ----------------------------->
<!----------------------------- BEGIN v1 API CONTENT ----------------------------->
{{% influxdb/custom-timestamps %}}
To write data to InfluxDB using the InfluxDB v2 HTTP API, send a request to
the InfluxDB API `/api/v2/write` endpoint using the `POST` request method.
Write data with your existing workloads that already use the InfluxDB v1 `/write` API endpoint.
{{% 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-iox/) guide.
{{% /note %}}
To write data to InfluxDB using 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" %}}
Include the following with your request:
- **Headers**:
- **Authorization**: Token <INFLUX_TOKEN>
- **Content-Type**: text/plain; charset=utf-8
- **Accept**: application/json
- **Query parameters**:
- **db**: InfluxDB bucket name
- **precision**:[timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) (default is `ns`)
- **rp**: [retention policy](/influxdb/cloud-serverless/reference/glossary/#retention-policy-rp) name (default is the default DBRP mapping, if it exists, for the namespace; otherwise, an [auto-generated DBRP mapping](/influxdb/cloud-serverless/guides/api-compatibility/v1/#retention-policy-and-dbrp-mapping)).
- **Request body**: Line protocol as plain text
The following example uses cURL and the InfluxDB v1 API to write line protocol
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.
{{% code-placeholders "API_TOKEN " %}}
```sh
curl --silent -w "%{response_code}: %{errormsg}\n" \
"https://{{< influxdb/host >}}/write?db=get-started&precision=s" \
--header "Authorization: Token API_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--header "Accept: application/json" \
--data-binary "
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
home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600
home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600
home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200
home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200
home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800
home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800
home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400
home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400
home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000
home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000
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=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200
home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200
"
```
{{% /code-placeholders %}}
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.
_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.
<!--pytest-codeblocks:expected-output-->
```
204:
```
{{% /influxdb/custom-timestamps %}}
<!------------------------------ END v1 API CONTENT ------------------------------>
{{% /tab-content %}}
{{% tab-content %}}
<!----------------------------- BEGIN v2 API CONTENT ----------------------------->
{{% influxdb/custom-timestamps %}}
To write data to InfluxDB using the [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" >}}
@ -336,10 +490,10 @@ Include the following with your request:
The following example uses cURL and the InfluxDB v2 API to write line protocol
to InfluxDB:
{{% code-placeholders "API_TOKEN"%}}
{{% influxdb/custom-timestamps %}}
{{% code-placeholders "API_TOKEN" %}}
```sh
curl --request POST \
curl --silent -w "%{response_code}: %{errormsg}\n" \
"https://{{< influxdb/host >}}/api/v2/write?bucket=get-started&precision=s" \
--header "Authorization: Token API_TOKEN" \
--header "Content-Type: text/plain; charset=utf-8" \
@ -373,9 +527,23 @@ 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
"
```
{{% /influxdb/custom-timestamps %}}
{{% /code-placeholders %}}
<!------------------------------ END cURL CONTENT ------------------------------>
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
If successful, the output is an HTTP `204 No Content` status code.
<!--pytest-codeblocks:expected-output-->
```
204:
```
{{% /influxdb/custom-timestamps %}}
<!------------------------------ END v2 API CONTENT ------------------------------>
{{% /tab-content %}}
{{% tab-content %}}
<!---------------------------- BEGIN PYTHON CONTENT --------------------------->
@ -386,28 +554,39 @@ To write data to {{% product-name %}} using Python, use the
The following steps include setting up a Python virtual environment to scope
dependencies to your current project.
1. Create a module directory and navigate into it--for example:
1. Create a module directory and navigate into it--for example:
```sh
mkdir influxdb_py_client && cd $_
<!--
Using bash here is required when running with pytest.
I don't know why, but sh evaluates $_ to /usr/bin/pytest.
-->
```bash
mkdir -p influxdb_py_client && cd influxdb_py_client
```
2. Setup your Python virtual environment.
Inside of your module directory:
```sh
<!--pytest-codeblocks:cont-->
```bash
python -m venv envs/virtual-env
```
3. Activate the virtual environment.
3. Activate the virtual environment.
```sh
<!--pytest-codeblocks:cont-->
```bash
source ./envs/virtual-env/bin/activate
```
4. Install the client library package:
```sh
<!--pytest-codeblocks:cont-->
```bash
pip install influxdb3-python
```
@ -415,58 +594,60 @@ dependencies to your current project.
5. In your terminal or editor, create a new file for your code--for example: `write.py`.
```sh
<!--pytest-codeblocks:cont-->
```bash
touch write.py
```
5. Inside of `write.py`, enter the following sample code:
6. Inside of `write.py`, enter the following sample code:
```py
from influxdb_client_3 import InfluxDBClient3
import os
```py
from influxdb_client_3 import InfluxDBClient3
import os
# INFLUX_TOKEN is an environment variable you assigned to your
# API WRITE token value.
token = os.getenv('INFLUX_TOKEN')
# INFLUX_TOKEN is an environment variable you assigned to your
# API WRITE token value.
token = os.getenv('INFLUX_TOKEN')
# host is the URL without protocol or trailing slash
client = InfluxDBClient3(
host='{{< influxdb/host >}}',
token=token,
database='get-started'
)
# host is the URL without protocol or trailing slash
client = InfluxDBClient3(
host='{{< influxdb/host >}}',
token=token,
database='get-started'
)
lines = [
"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",
"home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600",
"home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600",
"home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200",
"home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200",
"home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800",
"home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800",
"home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400",
"home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400",
"home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000",
"home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000",
"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=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200",
"home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200"
]
lines = [
"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",
"home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600",
"home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600",
"home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200",
"home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200",
"home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800",
"home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800",
"home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400",
"home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400",
"home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000",
"home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000",
"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=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200",
"home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200"
]
client.write(lines,write_precision='s')
```
client.write(lines,write_precision='s')
```
The sample does the following:
@ -475,7 +656,7 @@ dependencies to your current project.
configured with the following credentials:
- **`host`**: {{% product-name %}} region hostname (URL without protocol or trailing slash)
- **`token`**: an InfluxDB [API 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._
- **`database`**: the name of the {{% product-name %}} bucket to write to
@ -489,12 +670,13 @@ dependencies to your current project.
6. To execute the module and write line protocol to your {{% product-name %}}
bucket, enter the following command in your terminal:
```sh
python write.py
```
<!--pytest.mark.skip-->
```bash
python write.py
```
{{% /influxdb/custom-timestamps %}}
<!----------------------------- END PYTHON CONTENT ---------------------------->
{{% /tab-content %}}
{{% tab-content %}}
@ -506,19 +688,28 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
1. Inside of your project directory, create a new module directory and navigate into it.
```sh
mkdir influxdb_go_client && cd $_
<!--
Using bash here is required when running with pytest.
I don't know why, but sh evaluates $_ to /usr/bin/pytest.
-->
```bash
mkdir -p influxdb_go_client && cd influxdb_go_client
```
2. Initialize a new Go module in the directory.
```sh
<!--pytest-codeblocks:cont-->
```bash
go mod init influxdb_go_client
```
3. In your terminal or editor, create a new file for your code--for example: `write.go`.
```sh
<!--pytest-codeblocks:cont-->
```bash
touch write.go
```
@ -619,7 +810,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
1. To instantiate the client, calls the `influxdb3.New(influxdb3.ClientConfig)` function and passes the following:
- **`Host`**: your {{% product-name %}} region URL
- **`Token`**: an InfluxDB [API](/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._
- **`WriteOptions`**: `influxdb3.WriteOptions` options for writing to InfluxDB.
@ -649,6 +840,8 @@ 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:
<!--pytest.mark.skip-->
```sh
go mod tidy && go build && go run influxdb_go_client
```
@ -663,27 +856,41 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
<!---------------------------- 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.
2. In your terminal, enter the following command to create a `influxdb_js_client` project and `package.json` file:
2. In your terminal, enter the following command to create a `influxdb_js_client` directory for your project:
```sh
npm init -y -w influxdb_js_client
```bash
mkdir influxdb_js_client && cd influxdb_js_client
```
3. Change into the `influxdb_js_client` directory.
3. Inside of `influxdb_js_client`, enter the following command to initialize a package.
This example configures the package to use [ECMAScript modules (ESM)](https://nodejs.org/api/packages.html#modules-loaders).
```sh
cd influxdb_js_client
<!--pytest-codeblocks:cont-->
```bash
npm init -y; npm pkg set type="module"
```
4. Install the `@influxdata/influxdb3-client` JavaScript client library as a dependency to your project:
```sh
4. Install the `@influxdata/influxdb3-client` JavaScript client library as a dependency to your project.
<!--pytest-codeblocks:cont-->
```bash
npm install --save @influxdata/influxdb3-client
```
5. In your terminal or editor, create a `write.mjs` file. The `.mjs` extension tells the Node.js interpreter that this is an [ES6 module](https://nodejs.org/api/esm.html#modules-ecmascript-modules).
6. Inside of `write.mjs`, enter the following sample code:
5. In your terminal or editor, create a `write.js` file.
<!--pytest-codeblocks:cont-->
```bash
touch write.js
```
6. Inside of `write.js`, enter the following sample code:
```js
// write.mjs
// write.js
import { InfluxDBClient } from "@influxdata/influxdb3-client";
/**
@ -766,7 +973,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
with InfluxDB credentials.
- **`host`**: your {{% product-name %}} region URL
- **`token`**: an [API 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._
3. Defines a list of line protocol strings where each string represents a data record.
@ -784,12 +991,12 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
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.
7. Iterates over and prints the messages in `writeResults`.
8. Closes the client to release resources.
7. In your terminal or editor, create an `index.mjs` file.
8. Inside of `index.mjs`, enter the following sample code to import and call `writeLineProtocol()`:
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()`:
```js
// index.mjs
import { writeLineProtocol } from "./write.mjs";
// index.js
import { writeLineProtocol } from "./write.js";
/**
* Execute the client functions.
@ -804,8 +1011,10 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
9. In your terminal, execute `index.mjs` to write to {{% product-name %}}:
<!--pytest-codeblocks:cont-->
```sh
node index.mjs
node index.js
```
{{% /influxdb/custom-timestamps %}}
@ -814,21 +1023,28 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
{{% tab-content %}}
<!---------------------------- BEGIN C# CONTENT --------------------------->
{{% 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.
2. In your terminal, create an executable C# project using the .NET **console** template.
<!--pytest.mark.skip-->
```sh
dotnet new console --name influxdb_csharp_client
```
3. Change into the generated `influxdb_csharp_client` directory.
<!--pytest.mark.skip-->
```sh
cd influxdb_csharp_client
```
4. Run the following command to install the latest version of the InfluxDB v3 C# client library.
<!--pytest.mark.skip-->
```sh
dotnet add package InfluxDB3.Client
```
@ -859,7 +1075,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
/**
* INFLUX_TOKEN is an environment variable you assigned to your
* API WRITE token value.
* WRITE token value.
*/
string? token = System.Environment
.GetEnvironmentVariable("INFLUX_TOKEN");
@ -923,7 +1139,7 @@ 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**: an [API 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._
@ -958,15 +1174,14 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
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 commands 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:
```sh
dotnet build
```
<!--pytest.mark.skip-->
```sh
dotnet run
```
<!---------------------------- END C# CONTENT --------------------------->
{{% /influxdb/custom-timestamps %}}
{{% /tab-content %}}
@ -979,7 +1194,7 @@ _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.
2. In your terminal or editor, use Maven to generate a project--for example:
```sh
```bash
mvn org.apache.maven.plugins:maven-archetype-plugin:3.1.2:generate \
-DarchetypeArtifactId="maven-archetype-quickstart" \
-DarchetypeGroupId="org.apache.maven.archetypes" -DarchetypeVersion="1.4" \
@ -992,9 +1207,12 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
3. In your terminal or editor, change into the `./influxdb_java_client` directory--for example:
```sh
<!--pytest-codeblocks:cont-->
```bash
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`.
```pom
@ -1009,9 +1227,11 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
...
</dependencies>
```
5. To check your `pom.xml` for errors, run Maven's `validate` command--for example, enter the following in your terminal:
5. To validate your `pom.xml`, run Maven's `validate` command--for example, enter the following in your terminal:
```sh
<!--pytest.mark.skip-->
```bash
mvn validate
```
@ -1050,7 +1270,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
/**
* INFLUX_TOKEN is an environment variable you assigned to your
* API WRITE token value.
* WRITE token value.
*/
final char[] token = (System.getenv("INFLUX_TOKEN")).
toCharArray();
@ -1118,7 +1338,7 @@ _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`**: an [API 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._
2. Defines a list of line protocol strings where each string represents a data record.
@ -1156,12 +1376,16 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
- `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:
```sh
<!--pytest.mark.skip-->
```bash
mvn compile
```
10. In your terminal or editor, execute `App.main()` to write to InfluxDB--for example, using Maven:
<!--pytest.mark.skip-->
```sh
mvn exec:java -Dexec.mainClass="com.influxdbv3.App"
```

73
content/influxdb/cloud-serverless/guides/api-compatibility/v1/_index.md
View File

@ -99,11 +99,20 @@ Encode the `[USERNAME]:DATABASE_TOKEN` credential using base64 encoding, and the
##### Example
The following example shows how to use cURL with the `Basic` authentication scheme and an [API token](/influxdb/cloud-serverless/admin/tokens/):
The following example shows how to use cURL with the `Basic` authentication scheme and a [token](/influxdb/cloud-serverless/admin/tokens/):
{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}}
```sh
{{% get-shared-text "api/cloud-serverless/basic-auth.sh" %}}
#######################################
# Use Basic authentication with a database token
# to query the InfluxDB v1 API
#######################################
curl --get "https://{{< influxdb/host >}}/query" \
--user "":"API_TOKEN" \
--data-urlencode "db=BUCKET_NAME" \
--data-urlencode "rp=RETENTION_POLICY" \
--data-urlencode "q=SELECT * FROM MEASUREMENT"
```
{{% /code-placeholders %}}
@ -111,7 +120,7 @@ Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: your {{% product-name %}} retention policy
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: an [API token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the bucket
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the specified bucket
#### Query string authentication
@ -127,11 +136,20 @@ https://{{< influxdb/host >}}/write/?[u=any]&p=API_TOKEN
##### Example
The following example shows how to use cURL with query string authentication and [API token](/influxdb/cloud-serverless/admin/tokens/).
The following example shows how to use cURL with query string authentication and a [token](/influxdb/cloud-serverless/admin/tokens/).
{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}}
```sh
{{% get-shared-text "api/cloud-serverless/querystring-auth.sh" %}}
#######################################
# Use an InfluxDB 1.x compatible username and password
# to query the InfluxDB v1 API
#######################################
curl --get "https://{{< influxdb/host >}}/query" \
--data-urlencode "p=API_TOKEN" \
--data-urlencode "db=BUCKET_NAME" \
--data-urlencode "rp=RETENTION_POLICY" \
--data-urlencode "q=SELECT * FROM MEASUREMENT"
```
{{% /code-placeholders %}}
@ -139,11 +157,11 @@ Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: your {{% product-name %}} retention policy
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: an [API token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the bucket
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the specified bucket
### Authenticate with a token scheme
Use the `Authorization: Token` scheme to pass an [API token](/influxdb/cloud-serverless/admin/tokens/) for authenticating
Use the `Authorization: Token` scheme to pass a [token](/influxdb/cloud-serverless/admin/tokens/) for authenticating
v1 API `/write` and `/query` requests.
#### Syntax
@ -158,7 +176,15 @@ Use `Token` to authenticate a write request:
{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}}
```sh
{{% get-shared-text "api/cloud-serverless/token-auth-v1-write.sh" %}}
########################################################
# Use the Token authorization scheme with v1 /write
# to write data.
########################################################
curl -i "https://{{< influxdb/host >}}/write?db=BUCKET_NAME&rp=RETENTION_POLICY&precision=ms" \
--header "Authorization: Token API_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--data-binary 'home,room=kitchen temp=72 1682358973500'
```
{{% /code-placeholders %}}
@ -166,7 +192,7 @@ Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: your {{% product-name %}} retention policy
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: an [API token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the bucket
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the specified bucket
## Responses
@ -226,9 +252,9 @@ Parameter | Allowed in | Ignored | Value
`consistency` | Query string | Ignored | N/A
`db` {{% req " \*" %}} | Query string | Honored | Bucket name
`precision` | Query string | Honored | [Timestamp precision](#timestamp-precision)
`rp` {{% req " \*" %}} | Query string | Honored | Retention policy
`rp` | Query string | Honored | [Retention policy](#retention-policy-and-dbrp-mapping)
`u` | Query string | Ignored | For [query string authentication](#query-string-authentication), any arbitrary string
`p` | Query string | Honored | For [query string authentication](#query-string-authentication), an [API token](/influxdb/cloud-serverless/admin/tokens/) with permission to write to the bucket
`p` | Query string | Honored | For [query string authentication](#query-string-authentication), a [token](/influxdb/cloud-serverless/admin/tokens/) with permission to write to the bucket
`Content-Encoding` | Header | Honored | `gzip` (compressed data) or `identity` (uncompressed)
`Authorization` | Header | Honored | `Token API_TOKEN`, or `Basic <base64 [USERNAME]:API_TOKEN>`
@ -245,6 +271,15 @@ Use one of the following `precision` values in v1 API `/write` requests:
- `m`: minutes
- `h`: hours
#### Retention policy and DBRP mapping
In {{< product-name >}}, databases and retention policies are
combined and replaced by InfluxDB [buckets](/influxdb/cloud-serverless/reference/glossary/#bucket).
Writing data with the InfluxDB v1 `/write` endpoint or querying data using InfluxQL requires first mapping a database retention policy (DBRP) combination to a bucket.
If you specify an existing DBRP in the `rp=` parameter or if a default DBRP exists for the bucket, InfluxDB writes to the specified bucket.
Otherwise, if no DBRP exists for the bucket specified in `db=BUCKET_NAME`, and you use an [All-Access API token](/influxdb/cloud-serverless/admin/tokens/#all-access-api-token) to authorize the write request, InfluxDB auto-generates a new bucket named `BUCKET_NAME/autogen` and a DBRP mapping named `autogen`, and then writes the data to the new bucket.
### Tools for writing to the v1 API
The following tools work with the {{% product-name %}} `/write` endpoint:
@ -292,7 +327,7 @@ Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: your {{% product-name %}} retention policy
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: an [API token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the bucket
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the specified bucket
##### Other Telegraf configuration options
@ -308,16 +343,16 @@ Include the following in your request:
- A `db` query string parameter with the name of the bucket to write to.
- A request body that contains a string of data in [line protocol](/influxdb/cloud-serverless/reference/syntax/line-protocol/) syntax.
- an [API token](/influxdb/cloud-serverless/admin/tokens/) in one of the following authentication schemes: [Basic authentication](#basic-authentication), [query string authentication](#query-string-authentication), or [token authentication](#authenticate-with-a-token).
- a [token](/influxdb/cloud-serverless/admin/tokens/) in one of the following authentication schemes: [Basic authentication](#basic-authentication), [query string authentication](#query-string-authentication), or [token authentication](#authenticate-with-a-token).
- Optional [parameters](#v1-api-write-parameters).
The following example shows how to use the **cURL** command line tool and the {{% product-name %}} v1 API to write line protocol data to a bucket:
{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}}
```sh
curl -i 'https://{{< influxdb/host >}}/write?db=BUCKET_NAME&rp=RETENTION_POLICY&precision=s' \
--header 'Authorization: Token API_TOKEN' \
--header "Content-type: text/plain; charset=utf-8"
curl -i "https://{{< influxdb/host >}}/write?db=BUCKET_NAME&rp=RETENTION_POLICY&precision=s" \
--header "Authorization: Token API_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--data-binary 'home,room=kitchen temp=72 1463683075'
```
{{% /code-placeholders %}}
@ -326,7 +361,7 @@ Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: your {{% product-name %}} retention policy
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: an [API token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the bucket
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the specified bucket
##### v1 CLI (not supported)
@ -401,7 +436,7 @@ Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: your {{% product-name %}} retention policy
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: an [API token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the bucket
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the specified bucket
## Query data
@ -436,7 +471,7 @@ Parameter | Allowed in | Ignored | Value
`epoch` | Query string | Honored | [Timestamp precision](#timestamp-precision)
`pretty` | Query string | Ignored | N/A
`u` | Query string | Ignored | For [query string authentication](#query-string-authentication), any arbitrary string
`p` | Query string | Honored | For [query string authentication](#query-string-authentication), an [API token](/influxdb/cloud-serverless/admin/tokens) with permission to write to the bucket
`p` | Query string | Honored | For [query string authentication](#query-string-authentication), a [token](/influxdb/cloud-serverless/admin/tokens) with permission to write to the bucket
`rp` | Query string | Honored | Retention policy
{{% note %}}

4
content/influxdb/cloud-serverless/guides/migrate-data/_index.md
View File

@ -16,7 +16,7 @@ aliases:
- /influxdb/cloud-serverless/query-data/sql/execute-queries/flux-sql/
---
Migrate data to InfluxDB Cloud Serverless powered by InfluxDB IOx from other
Migrate data to InfluxDB Cloud Serverless powered by the v3 storage engine from other
InfluxDB instances powered by TSM including InfluxDB OSS 1.x, 2.x,
InfluxDB Enterprise, and InfluxDB Cloud (TSM).
@ -54,7 +54,7 @@ series data with SQL. For more information about querying your data with SQL, se
**Yes, you should migrate**. One of the primary goals when designing the InfluxDB
IOx storage engine was to enable performant implementations of both SQL and InfluxQL.
When compared to querying InfluxDB powered by TSM (InfluxDB OSS 1.x, 2.x, and Enterprise),
InfluxQL queries are more performant when querying InfluxDB powered by InfluxDB IOx. -->
InfluxQL queries are more performant when querying InfluxDB powered by the v3 storage engine. -->
#### Do you depend on a specific cloud provider or region?

2
content/influxdb/cloud-serverless/guides/migrate-data/migrate-1x-to-iox.md
View File

@ -14,7 +14,7 @@ aliases:
---
To migrate data from an InfluxDB 1.x OSS or Enterprise instance to InfluxDB Cloud
Serverless powered by InfluxDB IOx, export the data as line protocol and write
Serverless powered by the v3 storage engine, export the data as line protocol and write
the exported data to a bucket in your InfluxDB Cloud Serverless organization.
Because full data migrations will likely exceed your organizations' limits and
adjustable quotas, migrate your data in batches.

6
content/influxdb/cloud-serverless/guides/migrate-data/migrate-tsm-to-iox.md
View File

@ -2,7 +2,7 @@
title: Migrate data from TSM to IOx in InfluxDB Cloud
description: >
To migrate data from a TSM-powered InfluxDB Cloud organization to an InfluxDB
Cloud Serverless organization powered by InfluxDB IOx, query the data in
Cloud Serverless organization powered by the v3 storage engine, query the data in
time-based batches and write the queried data to an IOx bucket in your
InfluxDB Cloud Serverless organization.
menu:
@ -16,8 +16,8 @@ alt_links:
cloud: /influxdb/cloud/write-data/migrate-data/migrate-cloud-to-cloud/
---
To migrate data from an InfluxDB Cloud (TSM) organization to an
InfluxDB Cloud Serverless organization powered by InfluxDB IOx, query the data
To migrate data from an InfluxDB Cloud (TSM) organization to an
InfluxDB Cloud Serverless organization powered by the v3 storage engine, query the data
from your TSM-powered buckets in time-based batches and write the queried data to
a bucket in your InfluxDB Cloud Serverless organization.
Because full data migrations will likely exceed your organizations' limits and

9
content/influxdb/cloud-serverless/write-data/troubleshoot.md
View File

@ -45,15 +45,16 @@ Write requests return the following status codes:
| :-------------------------------| :-----------------------------------------------------------------------| :------------- |
| `204 "Success"` | | If InfluxDB ingested the data |
| `400 "Bad request"` | `message` contains the first malformed line | If request data is malformed |
| `401 "Unauthorized"` | | If the `Authorization` header is missing or malformed or if the [token](/influxdb/cloud-serverless/admin/tokens/) doesn't have [permission](/influxdb/cloud-serverless/admin/tokens/create-token/) to write to the database. See [examples using credentials](/influxdb/cloud-serverless/get-started/write/#write-line-protocol-to-influxdb) in write requests. |
| `404 "Not found"` | requested **resource type** (for example, "organization" or "database"), and **resource name** | If a requested resource (for example, organization or database) wasn't found |
| `401 "Unauthorized"` | | If the `Authorization` header is missing or malformed or if the [token](/influxdb/cloud-serverless/admin/tokens/) doesn't have [permission](/influxdb/cloud-serverless/admin/tokens/create-token/) to write to the bucket. See [examples using credentials](/influxdb/cloud-serverless/get-started/write/#write-line-protocol-to-influxdb) in write requests. |
| `403 "Forbidden"` | `message` contains details about the error | If the data isn't allowed (for example, falls outside of the bucket's retention period).
| `404 "Not found"` | requested **resource type** (for example, "organization" or "bucket"), and **resource name** | If a requested resource (for example, organization or bucket) wasn't found |
| `413 “Request too large”` | cannot read data: points in batch is too large | If a request exceeds the maximum [global limit](/influxdb/cloud-serverless/admin/billing/limits/) |
| `429 “Too many requests”` | `Retry-After` header: xxx (seconds to wait before retrying the request) | If a request exceeds your plan's [adjustable service quotas](/influxdb/cloud-serverless/admin/billing/limits/#adjustable-service-quotas) |
| `500 "Internal server error"` | | Default status for an error |
| `503` "Service unavailable" | | If the server is temporarily unavailable to accept writes. The `Retry-After` header describes when to try the write again.
| `503` `"Service unavailable"` | | If the server is temporarily unavailable to accept writes. The `Retry-After` header describes when to try the write again.
The `message` property of the response body may contain additional details about the error.
If your data did not write to the database, see how to [troubleshoot rejected points](#troubleshoot-rejected-points).
If your data did not write to the bucket, see how to [troubleshoot rejected points](#troubleshoot-rejected-points).
## Troubleshoot failures

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

@ -103,7 +103,7 @@ The resulting line protocol would look something like the following:
##### Home sensor data line protocol
```sh
```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
@ -161,6 +161,8 @@ credentials (**URL**, **organization**, and **token**) are provided by
{{% /tabs %}}
{{% tab-content %}}
<!------------------------------- BEGIN TELEGRAF CONTENT ------------------------------>
{{% influxdb/custom-timestamps %}}
Use [Telegraf](/telegraf/v1/) to consume line protocol,
and then write it to {{< product-name >}}.
@ -168,6 +170,37 @@ and then write it to {{< product-name >}}.
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
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
home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600
home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600
home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200
home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200
home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800
home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800
home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400
home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400
home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000
home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000
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=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200
home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200
EOF
```
3. Run the following command to generate a Telegraf configuration file (`./telegraf.conf`) that enables the `inputs.file` and `outputs.influxdb_v2` plugins:
```sh
@ -189,12 +222,21 @@ and then write it to {{< product-name >}}.
files = ["home.lp"]
```
<!--test
```bash
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
```
-->
- **`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
[[outputs.influxdb_v2]]
# InfluxDB cluster URL
urls = ["${INFLUX_URL}"]
urls = ["${INFLUX_HOST}"]
# INFLUX_TOKEN is an environment variable you assigned to your database token
token = "${INFLUX_TOKEN}"
@ -206,9 +248,26 @@ and then write it to {{< product-name >}}.
bucket = "get-started"
```
<!--test
```bash
echo '[[outputs.influxdb_v2]]' >> telegraf.conf
echo ' # InfluxDB cluster URL' >> telegraf.conf
echo ' urls = ["${INFLUX_HOST}"]' >> telegraf.conf
echo '' >> telegraf.conf
echo ' # INFLUX_TOKEN is an environment variable you assigned to your database token' >> telegraf.conf
echo ' token = "${INFLUX_TOKEN}"' >> telegraf.conf
echo '' >> telegraf.conf
echo ' # An empty string (InfluxDB ignores this parameter)' >> telegraf.conf
echo ' organization = ""' >> telegraf.conf
echo '' >> telegraf.conf
echo ' # Database name' >> telegraf.conf
echo ' bucket = "get-started"' >> telegraf.conf
```
-->
The example configuration uses the following InfluxDB credentials:
- **`urls`**: an array containing your **`INFLUX_URL`** environment variable
- **`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
@ -235,12 +294,21 @@ and then write it to {{< product-name >}}.
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 %}}
<!------------------------------- END TELEGRAF CONTENT ------------------------------>
{{% /tab-content %}}
{{% tab-content %}}
<!----------------------------- BEGIN v1 API CONTENT ----------------------------->
{{% influxdb/custom-timestamps %}}
Write data with your existing workloads that already use the InfluxDB v1 `/write` API endpoint.
{{% note %}}
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.
{{% /note %}}
To write data to InfluxDB using the [InfluxDB v1 HTTP API](/influxdb/clustered/reference/api/), send a
request to the [InfluxDB API `/write` endpoint](/influxdb/clustered/api/#operation/PostLegacyWrite) using the `POST` request method.
@ -266,13 +334,14 @@ The following example uses cURL and the InfluxDB v1 API to write line protocol
to InfluxDB:
{{% code-placeholders "DATABASE_TOKEN" %}}
{{% influxdb/custom-timestamps %}}
```sh
curl -i 'https://{{< influxdb/host >}}/write?db=get-started&precision=s' \
--header 'Authorization: Bearer DATABASE_TOKEN' \
--header "Content-type: text/plain; charset=utf-8" \
--header "Accept: application/json" \
--data-binary "
curl --silent -w "%{response_code}: ${errormsg}\n" \
"https://{{< influxdb/host >}}/write?db=get-started&precision=s" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--header "Accept: application/json" \
--data-binary "
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
@ -301,15 +370,27 @@ 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
"
```
{{% /influxdb/custom-timestamps %}}
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [database token](/influxdb/clustered/admin/tokens/) with sufficient permissions to the specified database
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/clustered/admin/tokens/) with sufficient permissions to the specified database
If successful, the output is an HTTP `204 No Content` status code.
<!--pytest-codeblocks:expected-output-->
```
204:
```
{{% /influxdb/custom-timestamps %}}
<!------------------------------ END v1 API CONTENT ------------------------------>
{{% /tab-content %}}
{{% tab-content %}}
<!----------------------------- BEGIN v2 API CONTENT ----------------------------->
{{% influxdb/custom-timestamps %}}
To write data to InfluxDB using the [InfluxDB v2 HTTP API](/influxdb/clustered/reference/api/), send a
request to the InfluxDB API `/api/v2/write` endpoint using the `POST` request method.
@ -328,17 +409,17 @@ Include the following with your request:
- **Request body**: Line protocol as plain text
{{% note %}}
With the {{% product-name %}} v2 API `/api/v2/write` endpoint, `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/clustered/primers/api/v2/#authenticate-api-requests).
The {{% product-name %}} v2 API `/api/v2/write` endpoint supports `Bearer` and `Token` authorization schemes 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/clustered/guides/api-compatibility/v2/).
{{% /note %}}
The following example uses cURL and the InfluxDB v2 API to write line protocol
to InfluxDB:
{{% code-placeholders "DATABASE_TOKEN"%}}
{{% influxdb/custom-timestamps %}}
```sh
curl --request POST \
"https://{{< influxdb/host >}}/api/v2/write?bucket=get-started&precision=s" \
curl --silent -w "%{response_code}: %{errormsg}\n" \
"https://{{< influxdb/host >}}/api/v2/write?bucket=get-started&precision=s" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--header "Content-Type: text/plain; charset=utf-8" \
--header "Accept: application/json" \
@ -371,8 +452,22 @@ 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
"
```
{{% /influxdb/custom-timestamps %}}
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb/clustered/admin/tokens/) with sufficient permissions to the specified database
If successful, the output is an HTTP `204 No Content` status code.
<!--pytest-codeblocks:expected-output-->
```
204:
```
{{% /influxdb/custom-timestamps %}}
<!------------------------------ END v2 API CONTENT ------------------------------>
{{% /tab-content %}}
{{% tab-content %}}
@ -386,26 +481,37 @@ dependencies to your current project.
1. Create a module directory and navigate into it--for example:
```sh
mkdir influxdb_py_client && cd $_
<!--
Using bash here is required when running with pytest.
I don't know why, but sh evaluates $_ to /usr/bin/pytest.
-->
```bash
mkdir -p influxdb_py_client && cd influxdb_py_client
```
2. Setup your Python virtual environment.
Inside of your module directory:
```sh
<!--pytest-codeblocks:cont-->
```bash
python -m venv envs/virtual-env
```
3. Activate the virtual environment.
```sh
<!--pytest-codeblocks:cont-->
```bash
source ./envs/virtual-env/bin/activate
```
4. Install the client library package:
```sh
<!--pytest-codeblocks:cont-->
```bash
pip install influxdb3-python
```
@ -413,7 +519,9 @@ dependencies to your current project.
5. In your terminal or editor, create a new file for your code--for example: `write.py`.
```sh
<!--pytest-codeblocks:cont-->
```bash
touch write.py
```
@ -475,7 +583,7 @@ dependencies to your current project.
- **`host`**: {{% product-name omit=" Clustered" %}} cluster hostname (URL without protocol or trailing slash)
- **`org`**: an empty or arbitrary string (InfluxDB ignores this parameter)
- **`token`**: an InfluxDB [database token](/influxdb/clustered/admin/tokens/) with write access to the target database.
- **`token`**: a [token](/influxdb/clustered/admin/tokens/) with write access to the specified database.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
- **`database`**: the name of the {{% product-name %}} database to write to
@ -484,14 +592,16 @@ dependencies to your current project.
**Because the timestamps in the sample line protocol are in second
precision, the example passes the `write_precision='s'` option
to set the[timestamp precision](/influxdb/clustered/reference/glossary/#timestamp-precision) to seconds.**
to set the [timestamp precision](/influxdb/clustered/reference/glossary/#timestamp-precision) to seconds.**
6. To execute the module and write line protocol to your {{% product-name %}}
database, enter the following command in your terminal:
```sh
python write.py
```
<!--pytest.mark.skip-->
```bash
python write.py
```
{{% /influxdb/custom-timestamps %}}
@ -506,19 +616,28 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
1. Inside of your project directory, create a new module directory and navigate into it.
```sh
mkdir influxdb_go_client && cd $_
<!--
Using bash here is required when running with pytest.
I don't know why, but sh evaluates $_ to /usr/bin/pytest.
-->
```bash
mkdir -p influxdb_go_client && cd influxdb_go_client
```
2. Initialize a new Go module in the directory.
```sh
<!--pytest-codeblocks:cont-->
```bash
go mod init influxdb_go_client
```
3. In your terminal or editor, create a new file for your code--for example: `write.go`.
```sh
<!--pytest-codeblocks:cont-->
```bash
touch write.go
```
@ -620,7 +739,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
1. To instantiate the client, calls the `influxdb3.New(influxdb3.ClientConfig)` function and passes the following:
- **`Host`**: the {{% product-name omit=" Clustered" %}} cluster URL
- **`Database`**: The name of your {{% product-name %}} database
- **`Token`**: an InfluxDB [database token](/influxdb/clustered/admin/tokens/) with _write_ access to the specified database.
- **`Token`**: a [token](/influxdb/clustered/admin/tokens/) with _write_ access to the specified database.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
- **`WriteOptions`**: `influxdb3.WriteOptions` options for writing to InfluxDB.
@ -650,6 +769,8 @@ 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:
<!--pytest.mark.skip-->
```sh
go mod tidy && go build && go run influxdb_go_client
```
@ -664,27 +785,41 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
<!---------------------------- 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.
2. In your terminal, enter the following command to create a `influxdb_js_client` project and `package.json` file:
2. In your terminal, enter the following command to create a `influxdb_js_client` directory for your project:
```sh
npm init -y -w influxdb_js_client
```bash
mkdir influxdb_js_client && cd influxdb_js_client
```
3. Change into the `influxdb_js_client` directory.
3. Inside of `influxdb_js_client`, enter the following command to initialize a package.
This example configures the package to use [ECMAScript modules (ESM)](https://nodejs.org/api/packages.html#modules-loaders).
```sh
cd influxdb_js_client
<!--pytest-codeblocks:cont-->
```bash
npm init -y; npm pkg set type="module"
```
4. Install the `@influxdata/influxdb3-client` JavaScript client library as a dependency to your project:
```sh
4. Install the `@influxdata/influxdb3-client` JavaScript client library as a dependency to your project.
<!--pytest-codeblocks:cont-->
```bash
npm install --save @influxdata/influxdb3-client
```
5. In your terminal or editor, create a `write.mjs` file. The `.mjs` extension tells the Node.js interpreter that this is an [ES6 module](https://nodejs.org/api/esm.html#modules-ecmascript-modules).
6. Inside of `write.mjs`, enter the following sample code:
5. In your terminal or editor, create a `write.js` file.
<!--pytest-codeblocks:cont-->
```bash
touch write.js
```
6. Inside of `write.js`, enter the following sample code:
```js
// write.mjs
// write.js
import { InfluxDBClient } from "@influxdata/influxdb3-client";
/**
@ -694,7 +829,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
const database = "get-started";
/**
* INFLUX_TOKEN is an environment variable you assigned to your
* database WRITE token value.
* WRITE token value.
*/
const token = process.env.INFLUX_TOKEN;
@ -767,7 +902,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
with InfluxDB credentials.
- **`host`**: your {{% product-name omit=" Clustered" %}} cluster URL
- **`token`**: a [database token](/influxdb/clustered/admin/tokens/) with _write_ access to the specified database.
- **`token`**: a [token](/influxdb/clustered/admin/tokens/) with _write_ access to the specified database.
_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.
@ -785,12 +920,12 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
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.
7. Iterates over and prints the messages in `writeResults`.
8. Closes the client to release resources.
7. In your terminal or editor, create an `index.mjs` file.
8. Inside of `index.mjs`, enter the following sample code to import and call `writeLineProtocol()`:
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()`:
```js
// index.mjs
import { writeLineProtocol } from "./write.mjs";
// index.js
import { writeLineProtocol } from "./write.js";
/**
* Execute the client functions.
@ -803,10 +938,12 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
main();
```
9. In your terminal, execute `index.mjs` to write to {{% product-name %}}:
9. In your terminal, execute `index.js` to write to {{% product-name %}}:
<!--pytest-codeblocks:cont-->
```sh
node index.mjs
node index.js
```
{{% /influxdb/custom-timestamps %}}
@ -818,18 +955,24 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
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.
2. In your terminal, create an executable C# project using the .NET **console** template.
<!--pytest.mark.skip-->
```sh
dotnet new console --name influxdb_csharp_client
```
3. Change into the generated `influxdb_csharp_client` directory.
<!--pytest.mark.skip-->
```sh
cd influxdb_csharp_client
```
4. Run the following command to install the latest version of the InfluxDB v3 C# client library.
<!--pytest.mark.skip-->
```sh
dotnet add package InfluxDB3.Client
```
@ -860,7 +1003,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
/**
* INFLUX_TOKEN is an environment variable you assigned to your
* database WRITE token value.
* WRITE token value.
*/
string? token = System.Environment
.GetEnvironmentVariable("INFLUX_TOKEN");
@ -924,7 +1067,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
- **`host`**: your {{% product-name omit=" Clustered" %}} cluster URL
- **`database`**: the name of the {{% product-name %}} database to write to
- **`token`**: a [database token](/influxdb/clustered/admin/tokens/) with _write_ access to the specified bucket.
- **`token`**: a [token](/influxdb/clustered/admin/tokens/) 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._
@ -961,6 +1104,8 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
7. To build and execute the program and write the line protocol to your {{% product-name %}} database, enter the following command in your terminal:
<!--pytest.mark.skip-->
```sh
dotnet run
```
@ -989,9 +1134,12 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
3. In your terminal or editor, change into the `./influxdb_java_client` directory--for example:
```sh
<!--pytest-codeblocks:cont-->
```bash
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`.
```pom
@ -1006,9 +1154,11 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
...
</dependencies>
```
5. To check your `pom.xml` for errors, run Maven's `validate` command--for example, enter the following in your terminal:
5. To validate your `pom.xml`, run Maven's `validate` command--for example, enter the following in your terminal:
```sh
<!--pytest.mark.skip-->
```bash
mvn validate
```
@ -1047,7 +1197,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
/**
* INFLUX_TOKEN is an environment variable you assigned to your
* database WRITE token value.
* WRITE token value.
*/
final char[] token = (System.getenv("INFLUX_TOKEN")).
toCharArray();
@ -1115,7 +1265,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
- **`host`**: your {{% product-name omit=" Clustered" %}} cluster URL
- **`database`**: the name of the {{% product-name %}} database to write to
- **`token`**: a [database token](/influxdb/clustered/admin/tokens/) with _write_ access to the specified database.
- **`token`**: a [token](/influxdb/clustered/admin/tokens/) with _write_ access to the specified database.
_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.
@ -1153,12 +1303,16 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
- `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:
```sh
<!--pytest.mark.skip-->
```bash
mvn compile
```
10. In your terminal or editor, execute `App.main()` to write to InfluxDB--for example, using Maven:
<!--pytest.mark.skip-->
```sh
mvn exec:java -Dexec.mainClass="com.influxdbv3.App"
```

11
shared/text/api/cloud-serverless/basic-auth.sh
View File

@ -1,11 +0,0 @@
#######################################
# Use Basic authentication with a database token
# to query the InfluxDB v1 API
#######################################
curl --get "https://cloud2.influxdata.com/query" \
--user "":"API_TOKEN" \
--data-urlencode "db=BUCKET_NAME" \
--data-urlencode "rp=RETENTION_POLICY" \
--data-urlencode "q=SELECT * FROM MEASUREMENT"

10
shared/text/api/cloud-serverless/querystring-auth.sh
View File

@ -1,10 +0,0 @@
#######################################
# Use an InfluxDB 1.x compatible username and password
# to query the InfluxDB v1 API
#######################################
curl --get "https://cloud2.influxdata.com/query" \
--data-urlencode "p=API_TOKEN" \
--data-urlencode "db=BUCKET_NAME" \
--data-urlencode "rp=RETENTION_POLICY" \
--data-urlencode "q=SELECT * FROM MEASUREMENT"

9
shared/text/api/cloud-serverless/token-auth-v1-write.sh
View File

@ -1,9 +0,0 @@
########################################################
# Use the Token authorization scheme with v1 /write
# to write data.
########################################################
curl -i "https://cloud2.influxdata.com/write?db=BUCKET_NAME&rp=RETENTION_POLICY&precision=ms" \
--header "Authorization: Token API_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--data-binary 'home,room=kitchen temp=72 1682358973500'

78
test.Dockerfile Normal file
View File

@ -0,0 +1,78 @@
# If you need more help, visit the Dockerfile reference guide at
# https://docs.docker.com/engine/reference/builder/
FROM python:3.12.0-slim-bookworm
RUN apt-get update && apt-get install -y \
curl \
git \
golang \
gpg \
maven \
nodejs \
npm \
wget \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /usr/src/app
ARG SOURCE_DIR
COPY test ./test
COPY data ./test/data
RUN chmod -R 755 .
# Prevents Python from writing pyc files.
ENV PYTHONDONTWRITEBYTECODE=1
# the application crashes without emitting any logs due to buffering.
ENV PYTHONUNBUFFERED=1
WORKDIR /usr/src/app/test
COPY test/run-tests.sh /usr/local/bin/run-tests.sh
RUN chmod +x /usr/local/bin/run-tests.sh
# Download dependencies as a separate step to take advantage of Docker's caching.
# Leverage a cache mount to /root/.cache/pip to speed up subsequent builds.
# Leverage a bind mount to requirements.txt to avoid having to copy them into
# this layer.
RUN --mount=type=cache,target=/root/.cache/pip \
--mount=type=bind,source=test/requirements.txt,target=./requirements.txt \
python -m pip install -r ./requirements.txt
# RUN --mount=type=cache,target=/root/.cache/node_modules \
# --mount=type=bind,source=package.json,target=package.json \
# npm install
# Install parse_yaml.sh and parse YAML config files into dotenv files to be used by tests.
RUN /bin/bash -c 'curl -sO https://raw.githubusercontent.com/mrbaseman/parse_yaml/master/src/parse_yaml.sh'
RUN /bin/bash -c 'source ./parse_yaml.sh && parse_yaml ./data/products.yml > .env.products'
# Install Telegraf for use in tests.
# Follow the install instructions (https://docs.influxdata.com/telegraf/v1/install/?t=curl), except for sudo (which isn't available in Docker).
# influxdata-archive_compat.key GPG Fingerprint: 9D539D90D3328DC7D6C8D3B9D8FF8E1F7DF8B07E
RUN curl -s https://repos.influxdata.com/influxdata-archive_compat.key > influxdata-archive_compat.key \
&& \
echo '393e8779c89ac8d958f81f942f9ad7fb82a25e133faddaf92e15b16e6ac9ce4c influxdata-archive_compat.key' | sha256sum -c && cat influxdata-archive_compat.key | gpg --dearmor | tee /etc/apt/trusted.gpg.d/influxdata-archive_compat.gpg > /dev/null \
&& \
echo 'deb [signed-by=/etc/apt/trusted.gpg.d/influxdata-archive_compat.gpg] https://repos.influxdata.com/debian stable main' | tee /etc/apt/sources.list.d/influxdata.list \
&& \
apt-get update && apt-get install telegraf
# Install influx v2 Cloud CLI for use in tests.
# Follow the install instructions(https://portal.influxdata.com/downloads/), except for sudo (which isn't available in Docker).
# influxdata-archive_compat.key GPG fingerprint:
# 9D53 9D90 D332 8DC7 D6C8 D3B9 D8FF 8E1F 7DF8 B07E
RUN wget -q https://repos.influxdata.com/influxdata-archive_compat.key \
&& \
echo '393e8779c89ac8d958f81f942f9ad7fb82a25e133faddaf92e15b16e6ac9ce4c influxdata-archive_compat.key' | sha256sum -c && cat influxdata-archive_compat.key | gpg --dearmor | tee /etc/apt/trusted.gpg.d/influxdata-archive_compat.gpg > /dev/null \
&& \
echo 'deb [signed-by=/etc/apt/trusted.gpg.d/influxdata-archive_compat.gpg] https://repos.influxdata.com/debian stable main' | tee /etc/apt/sources.list.d/influxdata.list \
&& \
apt-get update && apt-get install influxdb2-cli
ENV TEMP_DIR=/usr/src/app/test/tmp
ENTRYPOINT [ "run-tests.sh" ]
CMD [""]

23
test.sh
View File

@ -30,7 +30,7 @@ rm -rf "$target"/*
# Check if the user provided a path to copy.
if [ -z "$paths" ]; then
echo "No path provided. Running tests for *.md files that have been added or modified in the current branch."
paths=$(git diff --name-only --diff-filter=AM --relative origin/master | \
paths=$(git diff --name-only --diff-filter=AM HEAD | \
grep -E '\.md$')
if [ -z "$paths" ]; then
@ -45,13 +45,22 @@ fi
echo "$paths" >> "$testrun"
echo "$paths" | rsync -arv --files-from=- . "$target"
# Build the test image, run the tests, and then remove the container after it exits.
docker compose run --build --rm test
# Build or rebuild a service if the Dockerfile or build directory have changed, and then run the tests.
docker compose up test
# Troubleshoot tests
# If you want to examine files or run commands for debugging tests,
# start the container and use `exec` to open an interactive shell--for example:
# docker compose start test && docker compose exec -it test /bin/bash
# To build and run a new container and debug test failures, use `docker compose run` which runs a one-off command in a new container. Pass additional flags to be used by the container's entrypoint and the test runners it executes--for example:
# To help debug test failures, run the container and pass additional flags to be used by the container's entrypoint and the test runners it executes--for example:
# docker compose run --rm test -v
# docker compose run --rm test --entrypoint /bin/bash
# If you want to examine files or run commands for debugging tests,
# start the container and use `exec` to open an interactive shell--for example:
# docker start test && docker exec -it test /bin/bash
# Or, pass the flags in the compose file--for example:
# services:
# test:
# build:...
# command: ["-vv"]

1
test/.gitignore vendored
View File

@ -6,4 +6,3 @@ tmp
.env*
.pytest_cache
.test-run.txt
parse_yaml.sh

18
test/package.json
View File

@ -1,18 +0,0 @@
{
"name": "docs-codesamples",
"version": "1.0.0",
"description": "",
"main": "index.js",
"directories": {
"example": "examples"
},
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"dependencies": {
"runmd": "^1.3.9"
}
}

163
test/parse_yaml.sh Normal file
View File

@ -0,0 +1,163 @@
#!/bin/bash
###############################################################################
#
# source: https://github.com/mrbaseman/parse_yaml.git
#
###############################################################################
# Parses a YAML file and outputs variable assigments. Can optionally accept a
# variable name prefix and a variable name separator
#
# Usage:
# parse_yaml file [prefix] [separator]
###############################################################################
function parse_yaml {
unset i
unset fs
local prefix=$2
local separator=${3:-_}
local indexfix=-1
# Detect awk flavor
if awk --version 2>&1 | grep -q "GNU Awk" ; then
# GNU Awk detected
indexfix=-1
elif awk -Wv 2>&1 | grep -q "mawk" ; then
# mawk detected
indexfix=0
fi
local s='[[:space:]]*' sm='[ \t]*' w='[a-zA-Z0-9_]*' fs=${fs:-$(echo @|tr @ '\034')} i=${i:- }
###############################################################################
# cat: read the yaml file into the stream
# awk 1: process multi-line text
# sed 1: remove comments and empty lines
# sed 2: process lists
# sed 3: process dictionaries
# sed 4: rearrange anchors
# sed 5: remove '---'/'...'/quotes, add file separator to create fields for awk 2
# awk 2: convert the formatted data to variable assignments
###############################################################################
cat $1 | \
awk -F$fs "{multi=0;
if(match(\$0,/$sm\|$sm$/)){multi=1; sub(/$sm\|$sm$/,\"\");}
if(match(\$0,/$sm>$sm$/)){multi=2; sub(/$sm>$sm$/,\"\");}
while(multi>0){
str=\$0; gsub(/^$sm/,\"\", str);
indent=index(\$0,str);
indentstr=substr(\$0, 0, indent+$indexfix) \"$i\";
obuf=\$0;
getline;
while(index(\$0,indentstr)){
obuf=obuf substr(\$0, length(indentstr)+1);
if (multi==1){obuf=obuf \"\\\\n\";}
if (multi==2){
if(match(\$0,/^$sm$/))
obuf=obuf \"\\\\n\";
else obuf=obuf \" \";
}
getline;
}
sub(/$sm$/,\"\",obuf);
print obuf;
multi=0;
if(match(\$0,/$sm\|$sm$/)){multi=1; sub(/$sm\|$sm$/,\"\");}
if(match(\$0,/$sm>$sm$/)){multi=2; sub(/$sm>$sm$/,\"\");}
}
print}" | \
sed -e "s|^\($s\)?|\1-|" \
-ne "s|^\($s\)-$s\($w\)$s:$s\(.*\)|\1-\n\1 \2: \3|" \
-ne "s|^$s#.*||;s|$s#[^\"']*$||;s|^\([^\"'#]*\)#.*|\1|;t 1" \
-ne "t" \
-ne ":1" \
-ne "s|^$s\$||;t 2" \
-ne "p" \
-ne ":2" \
-ne "d" | \
sed -ne "s|,$s\]|]|g" \
-e ":1" \
-e "s|^\($s\)\($w\)$s:$s\(&$w\)$s\[$s\(.*\)$s,$s\(.*\)$s\]|\1\2: \3[\4]\n\1$i- \5|;t 1" \
-e "s|^\($s\)\($w\)$s:$s\(&$w\)$s\[$s\(.*\)$s\]|\1\2: \3\n\1$i- \4|;" \
-e ":2" \
-e "s|^\($s\)\($w\)$s:$s\[$s\(.*\)$s,$s\(.*\)$s\]|\1\2: [\3]\n\1$i- \4|;t 2" \
-e "s|^\($s\)\($w\)$s:$s\[$s\(.*\)$s\]|\1\2:\n\1$i- \3|;" \
-e ":3" \
-e "s|^\($s\)-$s\[$s\(.*\)$s,$s\(.*\)$s\]|\1- [\2]\n\1$i- \3|;t 3" \
-e "s|^\($s\)-$s\[$s\(.*\)$s\]|\1-\n\1$i- \2|;p" | \
sed -ne "s|,$s}|}|g" \
-e ":1" \
-e "s|^\($s\)-$s{$s\(.*\)$s,$s\($w\)$s:$s\(.*\)$s}|\1- {\2}\n\1$i\3: \4|;t 1" \
-e "s|^\($s\)-$s{$s\(.*\)$s}|\1-\n\1$i\2|;" \
-e ":2" \
-e "s|^\($s\)\($w\)$s:$s\(&$w\)$s{$s\(.*\)$s,$s\($w\)$s:$s\(.*\)$s}|\1\2: \3 {\4}\n\1$i\5: \6|;t 2" \
-e "s|^\($s\)\($w\)$s:$s\(&$w\)$s{$s\(.*\)$s}|\1\2: \3\n\1$i\4|;" \
-e ":3" \
-e "s|^\($s\)\($w\)$s:$s{$s\(.*\)$s,$s\($w\)$s:$s\(.*\)$s}|\1\2: {\3}\n\1$i\4: \5|;t 3" \
-e "s|^\($s\)\($w\)$s:$s{$s\(.*\)$s}|\1\2:\n\1$i\3|;p" | \
sed -e "s|^\($s\)\($w\)$s:$s\(&$w\)\(.*\)|\1\2:\4\n\3|" \
-e "s|^\($s\)-$s\(&$w\)\(.*\)|\1- \3\n\2|" | \
sed -ne "s|^\($s\):|\1|" \
-e "s|^\($s\)\(---\)\($s\)||" \
-e "s|^\($s\)\(\.\.\.\)\($s\)||" \
-e "s|^\($s\)-$s[\"']\(.*\)[\"']$s\$|\1$fs$fs\2|p;t" \
-e "s|^\($s\)\($w\)$s:$s[\"']\(.*\)[\"']$s\$|\1$fs\2$fs\3|p;t" \
-e "s|^\($s\)-$s\(.*\)$s\$|\1$fs$fs\2|" \
-e "s|^\($s\)\($w\)$s:$s[\"']\?\(.*\)$s\$|\1$fs\2$fs\3|" \
-e "s|^\($s\)[\"']\?\([^&][^$fs]\+\)[\"']$s\$|\1$fs$fs$fs\2|" \
-e "s|^\($s\)[\"']\?\([^&][^$fs]\+\)$s\$|\1$fs$fs$fs\2|" \
-e "s|^\($s\)\($w\)$s:$s[\"']\(.*\)$s\$|\1$fs\2$fs\3|" \
-e "s|^\($s\)[\"']\([^&][^$fs]*\)[\"']$s\$|\1$fs$fs$fs\2|" \
-e "s|^\($s\)[\"']\([^&][^$fs]*\)$s\$|\1$fs$fs$fs\2|" \
-e "s|^\($s\)\($w\)$s:$s\(.*\)$s\$|\1$fs\2$fs\3|" \
-e "s|^\($s\)\([^&][^$fs]*\)[\"']$s\$|\1$fs$fs$fs\2|" \
-e "s|^\($s\)\([^&][^$fs]*\)$s\$|\1$fs$fs$fs\2|" \
-e "s|$s\$||p" | \
awk -F$fs "{
gsub(/\t/,\" \",\$1);
if(NF>3){if(value!=\"\"){value = value \" \";}value = value \$4;}
else {
if(match(\$1,/^&/)){anchor[substr(\$1,2)]=full_vn;getline};
indent = length(\$1)/length(\"$i\");
vname[indent] = \$2;
value= \$3;
for (i in vname) {if (i > indent) {delete vname[i]; idx[i]=0}}
if(length(\$2)== 0){ vname[indent]= ++idx[indent] };
vn=\"\"; for (i=0; i<indent; i++) { vn=(vn)(vname[i])(\"$separator\")}
vn=\"$prefix\" vn;
full_vn=vn vname[indent];
if(vn==\"$prefix\")vn=\"$prefix$separator\";
if(vn==\"_\")vn=\"__\";
}
assignment[full_vn]=value;
if(!match(assignment[vn], full_vn))assignment[vn]=assignment[vn] \" \" full_vn;
if(match(value,/^\*/)){
ref=anchor[substr(value,2)];
if(length(ref)==0){
printf(\"%s=\\\"%s\\\"\n\", full_vn, value);
} else {
for(val in assignment){
if((length(ref)>0)&&index(val, ref)==1){
tmpval=assignment[val];
sub(ref,full_vn,val);
if(match(val,\"$separator\$\")){
gsub(ref,full_vn,tmpval);
} else if (length(tmpval) > 0) {
printf(\"%s=\\\"%s\\\"\n\", val, tmpval);
}
assignment[val]=tmpval;
}
}
}
} else if (length(value) > 0) {
printf(\"%s=\\\"%s\\\"\n\", full_vn, value);
}
}END{
for(val in assignment){
if(match(val,\"$separator\$\"))
printf(\"%s=\\\"%s\\\"\n\", val, assignment[val]);
}
}"
}

3
test/pytest.ini
View File

@ -1,5 +1,8 @@
# pytest configuration file
[pytest]
# .env files to load environment variables from.
env_files =
.env.products
# Collect tests.
# Collect tests from files matching file name pattern.
python_files = *_test.py *_test_sh.py

3
test/requirements.txt
View File

@ -7,4 +7,5 @@ python-dotenv==1.0.0
## Test dependencies
pytest==7.4.1
pytest-cov==2.12.1
pytest-codeblocks==0.16.1
pytest-codeblocks==0.16.1
pytest-dotenv==0.5.2

20
test/run-tests.sh
View File

@ -23,19 +23,12 @@ if [ -z "$TEMP_DIR" ]; then
TEMP_DIR=./tmp
fi
# Parse YAML config files into dotenv files
curl -sO https://raw.githubusercontent.com/mrbaseman/parse_yaml/master/src/parse_yaml.sh
source ./parse_yaml.sh && parse_yaml ./data/products.yml > .env.products
# Load shell environment variables from .env files generated in the build (not provided at build-time.
# To provide .env files available at build-time, set them in the docker compose file).
set -a && source .env.products && set +a
BASE_DIR=$(pwd)
cd $TEMP_DIR
for file in `find . -type f` ; do
if [ -f "$file" ]; then
echo "PROCESSING $file"
echo "PRETEST: substituting values in $file"
# Replaces placeholder values with environment variable references.
@ -52,6 +45,7 @@ for file in `find . -type f` ; do
s/f"BUCKET_NAME"/os.getenv("INFLUX_DATABASE")/g;
s/f"DATABASE_NAME"/os.getenv("INFLUX_DATABASE")/g;
s|f"{{< influxdb/host >}}"|os.getenv("INFLUX_HOSTNAME")|g;
s|f"RETENTION_POLICY"|"autogen"|g;
' $file
# Shell-specific replacements.
@ -62,6 +56,7 @@ for file in `find . -type f` ; do
s/BUCKET_NAME/$INFLUX_DATABASE/g;
s/DATABASE_NAME/$INFLUX_DATABASE/g;
s/get-started/$INFLUX_DATABASE/g;
s/RETENTION_POLICY/autogen/g;
s/CONFIG_NAME/CONFIG_$(shuf -i 0-100 -n1)/g;' \
$file
@ -93,4 +88,9 @@ mkdir -p ~/Downloads && rm -rf ~/Downloads/*
gpg -q --batch --yes --delete-key D8FF8E1F7DF8B07E > /dev/null 2>&1
# Run test commands with options provided in the CMD of the Dockerfile.
pytest --codeblocks . "$@"
# pytest rootdir is the directory where pytest.ini is located (/test).
echo "Running cloud-dedicated tests..."
pytest --codeblocks --envfile $BASE_DIR/.env.dedicated ./content/influxdb/cloud-dedicated/ $@
echo "Running cloud-serverless tests..."
pytest --codeblocks --envfile $BASE_DIR/.env.serverless ./content/influxdb/cloud-serverless/ $@