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

Improve API compatibility and client library reference docs (#4985) 

* chore(dedicated): add link

* fix(dedicated): Change Flight client reference to link to Arrow Flight Client docs

* fix(serverless): cleanup query tools list

* fix(dedicated): cleanup query tools list

* fix(v3): update client libraries intro

* fix(dedicated): Add Go v3 client library. Update Go v2 library

* fix(dedicated): cleanup javascript v2 client lib

* feature(dedicated): python v3 client library reference

- set a pattern for client library reference documentation

* chore(v3): add python client lib reference, fix syntax

* fix(v3): demote v2 JS client library

* chore(v3): move and revise API primers

- move to API compatibility
- revise
- delete redundant examples and link to other pages

* fix(v3): replace influx with influx3 CLI

* fix(v3): cleanup v2 client library references

* fix(v3): SEO title

* fix(v3): api-compatibility
- retention policy for serverless
- format placeholders

* Update content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/browser.md

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

* Update content/influxdb/cloud-dedicated/reference/client-libraries/v3/_index.md

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

* Update content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/install.md

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

* Update content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/install.md

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

* Update content/influxdb/cloud-serverless/reference/client-libraries/v3/python.md

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

---------

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
pull/4992/head
Jason Stirnaman 2023-06-22 11:27:36 -05:00 committed by GitHub
parent 4df36bacc9
commit 1a20ccf5b3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
41 changed files with 2558 additions and 936 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
content/influxdb/cloud-dedicated/api-compatibility/_index.md Normal file
View File

@ -0,0 +1,26 @@
---
title: Learn to use APIs for your workloads
seo_title: Learn to use APIs for your data workloads in InfluxDB Cloud Dedicated
description: >
Choose the API and tools that fit your workload.
Learn how to authenticate, write, and query using Telegraf, client libraries, and HTTP clients.
weight: 999
menu:
influxdb_cloud_dedicated:
name: API compatibility
influxdb/cloud-dedicated/tags: [api]
aliases:
- /influxdb/cloud-dedicated/primers/
- /influxdb/cloud-dedicated/primers/api/
related:
- /influxdb/cloud-dedicated/query-data/sql/
- /influxdb/cloud-dedicated/query-data/influxql/
- /influxdb/cloud-dedicated/write-data/
- /influxdb/cloud-dedicated/write-data/use-telegraf/configure/
- /influxdb/cloud-dedicated/reference/api/
- /influxdb/cloud-dedicated/reference/client-libraries/
---
Choose the {{% cloud-name %}} API and tools that best fit your workload:
{{< children sort>}}

478
content/influxdb/cloud-dedicated/primers/api/v1/_index.md → content/influxdb/cloud-dedicated/api-compatibility/v1/_index.md
View File

@ -2,25 +2,30 @@
title: Use the InfluxDB v1 API with InfluxDB Cloud Dedicated
list_title: Use the InfluxDB v1 API
description: >
Use InfluxDB v1 API authentication, endpoints, and tools.
Learn how to use InfluxDB Cloud Dedicated v1 `/query`, `/write`, and username/password authentication when bringing existing 1.x workloads.
Use InfluxDB v1 API authentication, endpoints, and tools when bringing existing 1.x workloads to InfluxDB Cloud Dedicated.
weight: 3
menu:
influxdb_cloud_dedicated:
parent: API primers
name: v1 API primer
parent: API compatibility
name: v1 API
aliases:
- /influxdb/cloud-dedicated/primers/api/v1/
influxdb/cloud-dedicated/tags: [write, line protocol]
related:
- /influxdb/cloud-dedicated/query-data/sql/
- /influxdb/cloud-dedicated/query-data/influxql/
- /influxdb/cloud-dedicated/write-data/
- /influxdb/cloud-dedicated/write-data/use-telegraf/configure/
- /influxdb/cloud-dedicated/reference/api/
- /influxdb/cloud-dedicated/reference/client-libraries/
---
Use the InfluxDB v1 API with v1 workloads that you bring to InfluxDB Cloud Dedicated.
InfluxDB Cloud Dedicated v1 `/write` and `/query` endpoints work with username/password authentication and existing InfluxDB 1.x tools and code.
The InfluxDB v1 API `/write` endpoint works with
InfluxDB 1.x client libraries and the [Telegraf v1 Output Plugin](/telegraf/v1.26/plugins/#output-influxdb).
Use the InfluxDB v1 API `/write` and `/query` endpoints with v1 workloads that you bring to {{% cloud-name %}}.
The v1 endpoints work with username/password authentication and existing InfluxDB 1.x tools and code.
The InfluxDB v1 API `/write` endpoint works with InfluxDB 1.x client libraries and the [Telegraf v1 Output Plugin](/telegraf/v1.26/plugins/#output-influxdb).
The InfluxDB v1 API `/query` endpoint supports InfluxQL and third-party integrations like [Grafana](https://grafana.com).
{{% warn %}}
{{% api/cloud/v2-prefer %}}
{{% /warn %}}
Learn how to authenticate requests, adjust request parameters for existing v1 workloads, and find compatible tools for writing and querying data stored in an {{% cloud-name %}} database.
<!-- TOC -->
@ -37,35 +42,30 @@ The InfluxDB v1 API `/query` endpoint supports InfluxQL and third-party integrat
- [Examples](#examples)
- [Responses](#responses)
- [Error examples](#error-examples)
- [Write data with the v1 API](#write-data-with-the-v1-api)
- [Write using Telegraf](#write-using-telegraf)
- [Other Telegraf configuration options](#other-telegraf-configuration-options)
- [Write using client libraries](#write-using-client-libraries)
- [Write using HTTP clients](#write-using-http-clients)
- [Write data](#write-data)
- [v1 API /write parameters](#v1-api-write-parameters)
- [Timestamp precision](#timestamp-precision)
- [Use clients for interactive testing](#use-clients-for-interactive-testing)
- [v1 CLI not supported](#v1-cli-not-supported)
- [Tools for writing to the v1 API](#tools-for-writing-to-the-v1-api)
- [Telegraf](#telegraf)
- [Other Telegraf configuration options](#other-telegraf-configuration-options)
- [Interactive clients](#interactive-clients)
- [v1 CLI not supported](#v1-cli-not-supported)
- [Client libraries](#client-libraries)
- [Query data](#query-data)
- [Query using the v1 API](#query-using-the-v1-api)
- [v1 API /query parameters](#v1-api-query-parameters)
- [v1 API /query parameters](#v1-api-query-parameters)
- [Timestamp precision](#timestamp-precision)
- [Query using HTTP clients](#query-using-http-clients)
- [Query using Flight SQL](#query-using-flight-sql)
- [Query data](#query-data)
- [Tools to execute queries](#tools-to-execute-queries)
- [Database management with InfluxQL not supported](#database-management-with-influxql-not-supported)
<!-- /TOC -->
<!--
<a class="btn" href="/influxdb/cloud-dedicated/api/v1/">View v1 API reference documentation</a>
-->
## Authenticate API requests
InfluxDB requires each write request to be authenticated with a
InfluxDB requires each API request to be authenticated with a
[database token](/influxdb/cloud-dedicated/admin/tokens/).
With the InfluxDB v1 API, you can use database tokens in InfluxDB 1.x username and password
schemes, in the InfluxDB v2 `Authorization: Token` scheme, or in the OAuth `Authorization: Bearer` scheme.
In the InfluxDB Cloud Dedicated HTTP API, `Authorization: Bearer` and `Authorization: Token` are equivalent.
- [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme)
- [Authenticate with a token scheme](#authenticate-with-a-token)
@ -73,11 +73,9 @@ In the InfluxDB Cloud Dedicated HTTP API, `Authorization: Bearer` and `Authoriza
### Authenticate with a username and password scheme
With the InfluxDB v1 API, you can use the InfluxDB 1.x convention of
username and password to authenticate database reads and writes by passing a
[database token](/influxdb/cloud-dedicated/admin/tokens/)
as the `password` credential.
When authenticating requests to the v1 API `/write` and `/query` endpoints, InfluxDB Cloud Dedicated checks that `password` (`p`) is an authorized [database token](/influxdb/cloud-dedicated/admin/tokens/).
InfluxDB Cloud ignores the `username` (`u`) parameter in the request.
username and password to authenticate database reads and writes by passing a [database token](/influxdb/cloud-dedicated/admin/tokens/) as the `password` credential.
When authenticating requests to the v1 API `/write` and `/query` endpoints, {{% cloud-name %}} checks that the `password` (`p`) value is an authorized [database token](/influxdb/cloud-dedicated/admin/tokens/).
{{% cloud-name %}} ignores the `username` (`u`) parameter in the request.
Use one of the following authentication schemes with clients that support Basic authentication or query parameters (that don't support [token authentication](#authenticate-with-a-token)):
@ -87,8 +85,8 @@ Use one of the following authentication schemes with clients that support Basic
#### Basic authentication
Use the `Authorization` header with the `Basic` scheme to authenticate v1 API `/write` and `/query` requests.
When authenticating requests, InfluxDB Cloud Dedicated checks that the `password` part of the decoded credential is an authorized [database token](/influxdb/cloud-dedicated/admin/tokens/).
InfluxDB Cloud Dedicated ignores the `username` part of the decoded credential.
When authenticating requests, {{% cloud-name %}} checks that the `password` part of the decoded credential is an authorized [database token](/influxdb/cloud-dedicated/admin/tokens/).
{{% cloud-name %}} ignores the `username` part of the decoded credential.
##### Syntax
@ -96,11 +94,7 @@ InfluxDB Cloud Dedicated ignores the `username` part of the decoded credential.
Authorization: Basic <base64-encoded [USERNAME]:DATABASE_TOKEN>
```
Replace the following:
- **`[USERNAME]`**: an optional string value (ignored by InfluxDB Cloud Dedicated).
- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/).
- Encode the `[USERNAME]:DATABASE_TOKEN` credential using base64 encoding, and then append the encoded string to the `Authorization: Basic` header.
Encode the `[USERNAME]:DATABASE_TOKEN` credential using base64 encoding, and then append the encoded string to the `Authorization: Basic` header.
{{% api/v1-compat/basic-auth-syntax %}}
@ -108,19 +102,21 @@ Replace the following:
The following example shows how to use cURL with the `Basic` authentication scheme and a [database token](/influxdb/cloud-dedicated/admin/tokens/):
{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}
```sh
{{% get-shared-text "api/cloud-dedicated/basic-auth.sh" %}}
```
{{% /code-placeholders %}}
Replace the following:
- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database
- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database
#### Query string authentication
In the URL, pass the `p` query parameter to authenticate `/write` and `/query` requests.
When authenticating requests, InfluxDB Cloud Dedicated checks that `p` (_password_) is an authorized database token and ignores the `u` (_username_) parameter.
When authenticating requests, {{% cloud-name %}} checks that the `p` (_password_) value is an authorized database token and ignores the `u` (_username_) parameter.
##### Syntax
@ -133,21 +129,23 @@ https://cluster-id.influxdb.io/write/?[u=any]&p=DATABASE_TOKEN
The following example shows how to use cURL with query string authentication and [database token](/influxdb/cloud-dedicated/admin/tokens/).
{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}
```sh
{{% get-shared-text "api/cloud-dedicated/querystring-auth.sh" %}}
```
{{% /code-placeholders %}}
Replace the following:
- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database
- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database
### Authenticate with a token scheme
Use the `Authorization: Bearer` or the `Authorization: Token` scheme to pass a [database token](/influxdb/cloud-dedicated/admin/tokens/) for authenticating
v1 API `/write` and `/query` requests.
`Bearer` and `Token` are equivalent in InfluxDB Cloud Dedicated.
`Bearer` and `Token` are equivalent in {{% cloud-name %}}.
The `Token` scheme is used in the InfluxDB 2.x API.
`Bearer` is defined by the [OAuth 2.0 Framework](https://www.rfc-editor.org/rfc/rfc6750#page-14).
Support for one or the other may vary across InfluxDB API clients.
@ -166,27 +164,31 @@ Authorization: Token DATABASE_TOKEN
Use `Bearer` to authenticate a write request:
{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}
```sh
{{% get-shared-text "api/cloud-dedicated/bearer-auth-v1-write.sh" %}}
```
{{% /code-placeholders %}}
Use `Token` to authenticate a write request:
{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}
```sh
{{% get-shared-text "api/cloud-dedicated/token-auth-v1-write.sh" %}}
```
{{% /code-placeholders %}}
Replace the following:
- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database
- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database
## Responses
InfluxDB API responses use standard HTTP status codes.
For successful writes, InfluxDB responds with a `204 No Content` status code.
Error responses contain a JSON object with `code` and `message` properties that describe the error.
Response body messages may differ across InfluxDB Cloud Dedicated v1 API, v2 API, InfluxDB Cloud, and InfluxDB OSS.
Response body messages may differ across {{% cloud-name %}} v1 API, v2 API, InfluxDB Cloud, and InfluxDB OSS.
### Error examples
@ -197,7 +199,9 @@ Response body messages may differ across InfluxDB Cloud Dedicated v1 API, v2 API
```
```json
{"code":"invalid","message":"namespace name length must be between 1 and 64 characters"}
{ "code":"invalid",
"message":"namespace name length must be between 1 and 64 characters"
}
```
The `?db=` parameter value is missing in the request.
@ -211,144 +215,27 @@ Response body messages may differ across InfluxDB Cloud Dedicated v1 API, v2 API
```
```json
{"code":"invalid","message":"failed to deserialize db/rp/precision in request: unknown variant `u`, expected one of `s`, `ms`, `us`, `ns`"}
{ "code":"invalid",
"message":"failed to deserialize db/rp/precision in request: unknown variant `u`, expected one of `s`, `ms`, `us`, `ns`"
}
```
The `?precision=` parameter contains an unknown value.
Provide a [timestamp precision](#timestamp-precision).
## Write data with the v1 API
## Write data
Write data with your existing workloads that already use the InfluxDB v1 API or v1.x-compatibility API.
Write data with your existing workloads that already use the InfluxDB v1 or v1.x-compatibility `/write` API endpoint.
See how to set parameters and configure the following tools for writing to InfluxDB Cloud Dedicated:
{{% api-endpoint endpoint="https://cluster-id.influxdb.io/write" method="post" %}}
- [Write using Telegraf](#write-using-telegraf)
- [Write using client libraries](#write-using-client-libraries)
- [Write using HTTP clients](#write-using-http-clients)
- [v1 API /write parameters](#v1-api-write-parameters)
- [Use clients for interactive testing](#use-clients-for-interactive-testing)
### Write using Telegraf
If you have existing v1 workloads that use Telegraf,
you can use the [InfluxDB v1.x `influxdb` Telegraf output plugin](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) to write data.
{{% warn %}}
Use [Telegraf and the v2 API](/influxdb/cloud-dedicated/primers/api/v2/) for new workloads that don't use already use the v1 API.
{{% /warn %}}
The following table shows `outputs.influxdb` parameters and values writing
to InfluxDB Cloud Dedicated:
Parameter | Ignored | Value
-------------------------|--------------------------|---------------------------------------------------------------------------------------------------
`database` | Honored | Database name
`retention_policy` | Honored, but discouraged | [Duration](/influxdb/cloud-dedicated/reference/glossary/#duration)
`username` | Ignored | String or empty
`password` | Honored | [Database token](/influxdb/cloud-dedicated/admin/tokens/) with permission to write to the database
`content_encoding` | Honored | `gzip` (compressed data) or `identity` (uncompressed)
`skip_database_creation` | Ignored | N/A (see how to [create a database](/influxdb/cloud-dedicated/admin/databases/create/))
To configure the v1.x output plugin for writing to InfluxDB Cloud Dedicated,
add the following `outputs.influxdb` configuration in your `telegraf.conf` file:
```toml
[[outputs.influxdb]]
urls = ["https://cluster-id.influxdb.io"]
database = "DATABASE_NAME"
skip_database_creation = true
retention_policy = ""
username = "ignored"
password = "DATABASE_TOKEN"
content_encoding = "gzip”
```
Replace the following:
- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database
- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/get-started/setup/#create-a-database-token) with permission to write to the database
#### Other Telegraf configuration options
`influx_uint_support`: supported in InfluxDB IOx.
For more plugin options, see [`influxdb`](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) on GitHub.
### Write using client libraries
Use language-specific [v1 client libraries](/influxdb/v1.8/tools/api_client_libraries/) and your custom code to write data to InfluxDB Cloud Dedicated.
v1 client libraries send data in [line protocol](/influxdb/cloud-dedicated/reference/syntax/line-protocol/) syntax to the v1 API `/write` endpoint.
The following samples show how to configure **v1** client libraries for writing to InfluxDB Cloud Dedicated:
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[Node.js](#nodejs)
[Python](#python)
{{% /code-tabs %}}
{{% code-tab-content %}}
<!-- Start NodeJS -->
Create a v1 API client using the [node-influx](/influxdb/v1.7/tools/api_client_libraries/#javascriptnodejs) JavaScript client library:
```js
const Influx = require('influx')
// Instantiate a client for writing to InfluxDB Cloud Dedicated v1 API
const client = new Influx.InfluxDB({
host: 'cluster-id.influxdb.io',
port: 443,
protocol: 'https'
database: 'DATABASE_NAME',
username: 'ignored',
password: 'DATABASE_TOKEN'
})
```
<!-- End NodeJS -->
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-- Start Python -->
Create a v1 API client using the [influxdb-python](/influxdb/v1.7/tools/api_client_libraries/#python) Python client library:
```py
from influxdb import InfluxDBClient
# Instantiate a client for writing to InfluxDB Cloud Dedicated v1 API
client = InfluxDBClient(
host='cluster-id.influxdb.io',
ssl=True,
database='DATABASE_NAME',
username='',
password='DATABASE_TOKEN'
headers={'Content-Type': 'text/plain; charset=utf-8'}
)
```
<!-- End Python -->
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
Replace the following:
- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database
- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database
### Write using HTTP clients
Use HTTP clients and your custom code to send write requests to the v1 API `/write` endpoint.
{{% api-endpoint endpoint="https://cluster-id.influxdb.io/write" method="post"%}}
Include the following in your request:
- A `db` query string parameter with the name of the database to write to.
- A request body that contains a string of data in [line protocol](/influxdb/cloud-dedicated/reference/syntax/line-protocol/) syntax.
- A [database token](/influxdb/cloud-dedicated/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).
- [`/api/v2/write` parameters](#v1-api-write-parameters)
- [Tools for writing to the v1 API](#tools-for-writing-to-the-v1-api)
#### v1 API /write parameters
For {{% cloud-name %}} v1 API `/write` requests, set parameters as listed in the following table:
Parameter | Allowed in | Ignored | Value
-----------------------|--------------|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`consistency` | Query string | Ignored | N/A
@ -373,49 +260,167 @@ Use one of the following `precision` values in v1 API `/write` requests:
- `m`: minutes
- `h`: hours
#### Use clients for interactive testing
### Tools for writing to the v1 API
To test interactively, use common HTTP clients such as cURL and Postman to send requests to the v1 API `/write` endpoint.
The following tools work with the {{% cloud-name %}} `/write` endpoint:
{{% warn %}}
While the v1 CLI may coincidentally work with InfluxDB Cloud Dedicated, it isn't officially supported.
{{% /warn %}}
- [Telegraf](#telegraf)
- [Interactive clients](#interactive-clients)
- [Client libraries](#client-libraries)
The following example shows how to use the **cURL** command line tool and the InfluxDB Cloud Dedicated v1 API to write line protocol data to a database:
#### Telegraf
If you have existing v1 workloads that use Telegraf,
you can use the [InfluxDB v1.x `influxdb` Telegraf output plugin](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) to write data.
{{% note %}}
See how to [use Telegraf and the v2 API](/influxdb/cloud-dedicated/write-data/use-telegraf/) for new workloads that don't already use the v1 API.
{{% /note %}}
The following table shows `outputs.influxdb` plugin parameters and values for writing to the {{% cloud-name %}} v1 API:
Parameter | Ignored | Value
-------------------------|--------------------------|---------------------------------------------------------------------------------------------------
`database` | Honored | Database name
`retention_policy` | Honored, but discouraged | [Duration](/influxdb/cloud-dedicated/reference/glossary/#duration)
`username` | Ignored | String or empty
`password` | Honored | [Database token](/influxdb/cloud-dedicated/admin/tokens/) with permission to write to the database
`content_encoding` | Honored | `gzip` (compressed data) or `identity` (uncompressed)
`skip_database_creation` | Ignored | N/A (see how to [create a database](/influxdb/cloud-dedicated/admin/databases/create/))
To configure the v1.x output plugin for writing to {{% cloud-name %}}, add the following `outputs.influxdb` configuration in your `telegraf.conf` file:
{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}
```toml
[[outputs.influxdb]]
urls = ["https://cluster-id.influxdb.io"]
database = "DATABASE_NAME"
skip_database_creation = true
retention_policy = ""
username = "ignored"
password = "DATABASE_TOKEN"
content_encoding = "gzip”
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database
##### Other Telegraf configuration options
`influx_uint_support`: supported in InfluxDB IOx.
For more plugin options, see [`influxdb`](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) on GitHub.
#### Interactive clients
To test InfluxDB v1 API writes interactively from the command line, use common HTTP clients such as cURL and Postman.
Include the following in your request:
- A `db` query string parameter with the name of the database to write to.
- A request body that contains a string of data in [line protocol](/influxdb/cloud-dedicated/reference/syntax/line-protocol/) syntax.
- A [database token](/influxdb/cloud-dedicated/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 {{% cloud-name %}} v1 API to write line protocol data to a database:
{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}
```sh
curl -i 'https://cluster-id.influxdb.io/write?db=DATABASE_NAME&precision=s' \
--header 'Authorization: Bearer DATABASE_TOKEN' \
--header "Content-type: text/plain; charset=utf-8"
--data-binary 'home,room=kitchen temp=72 1463683075'
```
{{% /code-placeholders %}}
Replace the following:
- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database
- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database
### v1 CLI (not supported)
##### v1 CLI (not supported)
Don't use the v1 CLI with {{% cloud-name %}}.
While it may coincidentally work, it isn't officially supported.
If you need to test writes interactively, see how to [write using HTTP clients](#write-using-http-clients).
#### Client libraries
Use language-specific [v1 client libraries](/influxdb/v1.8/tools/api_client_libraries/) and your custom code to write data to InfluxDB.
v1 client libraries send data in [line protocol](/influxdb/cloud-dedicated/reference/syntax/line-protocol/) syntax to the v1 API `/write` endpoint.
The following samples show how to configure **v1** client libraries for writing to {{% cloud-name %}}:
{{< tabs-wrapper >}}
{{% tabs %}}
[Node.js](#nodejs)
[Python](#python)
{{% /tabs %}}
{{% tab-content %}}
<!-- Start NodeJS -->
Create a v1 API client using the [node-influx](/influxdb/v1.7/tools/api_client_libraries/#javascriptnodejs) JavaScript client library:
{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}
```js
const Influx = require('influx')
// Instantiate a client for writing to {{% cloud-name %}} v1 API
const client = new Influx.InfluxDB({
host: 'cluster-id.influxdb.io',
port: 443,
protocol: 'https'
database: 'DATABASE_NAME',
username: 'ignored',
password: 'DATABASE_TOKEN'
})
```
{{% /code-placeholders %}}
<!-- End NodeJS -->
{{% /tab-content %}}
{{% tab-content %}}
<!-- Start Python -->
Create a v1 API client using the [influxdb-python](/influxdb/v1.7/tools/api_client_libraries/#python) Python client library:
{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}
```py
from influxdb import InfluxDBClient
# Instantiate a client for writing to {{% cloud-name %}} v1 API
client = InfluxDBClient(
host='cluster-id.influxdb.io',
ssl=True,
database='DATABASE_NAME',
username='',
password='DATABASE_TOKEN'
headers={'Content-Type': 'text/plain; charset=utf-8'}
)
```
{{% /code-placeholders %}}
<!-- End Python -->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database
## Query data
### Query using the v1 API
{{% cloud-name %}} provides the following protocols for executing a query:
Use the v1 API `/query` endpoint and [InfluxQL](/influxdb/cloud-dedicated/reference/glossary/#influxql) with InfluxDB Cloud Dedicated when you
bring InfluxDB 1.x workloads that already use them.
- [Flight+gRPC](https://arrow.apache.org/docs/format/Flight.html) request that contains an SQL or InfluxQL query.
- InfluxDB v1 API `/query` request that contains an InfluxQL query.
InfluxDB Cloud Dedicated
### v1 API /query parameters
{{% note %}}
For new workloads, see how to [query using Flight SQL](#query-using-flight-sql).
{{% /note %}}
#### v1 API /query parameters
For {{% cloud-name %}} v1 API `/query` requests, set parameters as listed in the following table:
Parameter | Allowed in | Ignored | Value
----------|------------|---------|-------------------------------------------------------------------------
@ -428,6 +433,10 @@ Parameter | Allowed in | Ignored | Value
`p` | Query string | Honored | For [query string authentication](#query-string-authentication), a [database token](/influxdb/cloud-dedicated/get-started/setup/#create-a-database-token) with permission to write to the database
`rp` | Query string | Honored, but discouraged | Retention policy
{{% note %}}
When bringing v1 API workloads to {{% cloud-name %}}, you'll need to adjust request parameters in your client configuration or code.
{{% /note %}}
#### Timestamp precision
Use one of the following values for timestamp precision:
@ -439,80 +448,33 @@ Use one of the following values for timestamp precision:
- `m`: minutes
- `h`: hours
#### Query using HTTP clients
## Query data
Use HTTP clients and your custom code to send InfluxQL queries to the v1 API `/query` endpoint.
{{% cloud-name %}} provides the following protocols for executing a query:
{{% api-endpoint endpoint="https://cluster-id.influxdb.io/query" method="get"%}}
- [Flight+gRPC](https://arrow.apache.org/docs/format/Flight.html) request that contains an SQL or InfluxQL query.
- InfluxDB v1 API `/query` request that contains an InfluxQL query.
Include the following in your request:
{{% note %}}
- A `db` query string parameter with the name of the database to write to.
- A [database token](/influxdb/cloud-dedicated/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 `q` query string parameter with the InfluxQL query.
- Optional [parameters](#v1-api-query-parameters).
#### Tools to execute queries
The following examples show how to query using the v1 API `/query` endpoint and InfluxQL:
{{% cloud-name %}} supports many different tools for querying data, including:
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[cURL](#curl)
[Python](#python)
{{% /code-tabs %}}
{{% code-tab-content %}}
<!-- Begin cURL -->
```sh
{{% get-shared-text "api/cloud-dedicated/bearer-auth-v1-query.sh" %}}
```
- [`influx3` data CLI](https://github.com/InfluxCommunity/influxdb3-python-cli)
- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/)
- [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/)
- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/)
- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api)
- [Chronograf](/{{< latest "Chronograf" >}}/)
```sh
{{% get-shared-text "api/cloud-dedicated/token-auth-v1-query.sh" %}}
```
<!-- End cURL -->
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-- Begin python influxdb v1 client library -->
```py
from influxdb import InfluxDBClient
import os
{{% /note %}}
DATABASE_NAME = os.getenv('CLOUD_DEDICATED_DATABASE_NAME')
DATABASE_TOKEN = os.getenv('CLOUD_DEDICATED_DATABASE_TOKEN')
INFLUXDB_URL=os.getenv('CLOUD_DEDICATED_URL')
INFLUXDB_HOST=os.getenv('CLOUD_DEDICATED_HOST')
def influxdb_v1_client(headers=None):
client = InfluxDBClient(
host=INFLUXDB_HOST,
port=443,
ssl=True,
database=DATABASE_NAME,
username='USERNAME',
password=DATABASE_TOKEN,
headers=headers
)
print(vars(client))
return client
def query_influxql():
client = influxdb_v1_client()
response = client.query('SHOW MEASUREMENTS')
print(response)
return response
```
<!-- End python -->
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
The response body contains query results in JSON format.
### Query using Flight SQL
Use Flight SQL clients with gRPC and SQL to query data stored in an InfluxDB Cloud Dedicated database.
### Database management with InfluxQL (not supported)
InfluxDB Cloud Dedicated doesn't allow InfluxQL commands for managing or modifying databases.
{{% cloud-name %}} doesn't allow InfluxQL commands for managing or modifying databases.
You can't use the following InfluxQL commands:
```sql

236
content/influxdb/cloud-dedicated/api-compatibility/v2/_index.md Normal file
View File

@ -0,0 +1,236 @@
---
title: Use the InfluxDB v2 API with InfluxDB Cloud Dedicated
list_title: InfluxDB v2 API compatibility
description: >
Use the InfluxDB v2 API for new write workloads and existing v2 write workloads.
InfluxDB Cloud Dedicated is compatible with the InfluxDB v2 API `/api/v2/write` endpoint and existing InfluxDB 2.x tools and code.
weight: 1
menu:
influxdb_cloud_dedicated:
parent: API compatibility
name: v2 API
influxdb/cloud-dedicated/tags: [write, line protocol]
aliases:
- /influxdb/cloud-dedicated/primers/api/v2/
related:
- /influxdb/cloud-dedicated/query-data/sql/
- /influxdb/cloud-dedicated/query-data/influxql/
- /influxdb/cloud-dedicated/write-data/
- /influxdb/cloud-dedicated/write-data/use-telegraf/configure/
- /influxdb/cloud-dedicated/reference/api/
- /influxdb/cloud-dedicated/reference/client-libraries/
---
Use the InfluxDB v2 API `/api/v2/write` endpoint for new write workloads and existing v2 write workloads that you bring to {{% cloud-name %}}.
Learn how to authenticate requests, adjust request parameters for existing v2 workloads, and find compatible tools for writing and querying data stored in an {{% cloud-name %}} database.
For help finding the best workflow for your situation, [contact Support](mailto:support@influxdata.com).
<!-- TOC -->
- [Authenticate API requests](#authenticate-api-requests)
- [Authenticate with a token](#authenticate-with-a-token)
- [Syntax](#syntax)
- [Examples](#examples)
- [Responses](#responses)
- [Error examples](#error-examples)
- [Write data](#write-data)
- [/api/v2/write parameters](#apiv2write-parameters)
- [Timestamp precision](#timestamp-precision)
- [Tools for writing to the v2 API](#tools-for-writing-to-the-v2-api)
- [Telegraf](#telegraf)
- [Interactive clients](#interactive-clients)
- [influx CLI not supported](#influx-cli-not-supported)
- [Client libraries](#client-libraries)
- [Query data](#query-data)
- [Tools to execute queries](#tools-to-execute-queries)
- [/api/v2/query not supported](#apiv2query-not-supported)
<!-- /TOC -->
## Authenticate API requests
InfluxDB API endpoints require each request to be authenticated with a [database token](/influxdb/cloud-dedicated/admin/tokens/).
### Authenticate with a token
Use the `Authorization: Bearer` scheme or the `Authorization: Token` scheme to pass a [database token](/influxdb/cloud-dedicated/admin/tokens/) that has the necessary permissions for the operation.
`Bearer` and `Token` are equivalent in InfluxDB Cloud Dedicated.
The `Token` scheme is used in the InfluxDB 2.x API.
`Bearer` is defined by the [OAuth 2.0 Framework](https://www.rfc-editor.org/rfc/rfc6750#page-14).
Support for one or the other may vary across InfluxDB API clients.
#### Syntax
```http
Authorization: Bearer DATABASE_TOKEN
```
```http
Authorization: Token DATABASE_TOKEN
```
#### Examples
Use `Bearer` to authenticate a write request:
{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}
```sh
{{% get-shared-text "api/cloud-dedicated/bearer-auth-v2-write.sh" %}}
```
{{% /code-placeholders %}}
Use `Token` to authenticate a write request:
{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}
```sh
{{% get-shared-text "api/cloud-dedicated/token-auth-v2-write.sh" %}}
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database
## Responses
InfluxDB API responses use standard HTTP status codes.
For successful writes, InfluxDB responds with a `204 No Content` status code.
Error responses contain a JSON object with `code` and `message` properties that describe the error.
Response body messages may differ across {{% cloud-name %}} v1 API, v2 API, InfluxDB Cloud, and InfluxDB OSS.
### Error examples
- **Missing bucket value**
```http
400 Bad Request
```
```json
{ "code": "invalid",
"message":"missing bucket value"
}
```
The `?bucket=` parameter value is missing in the request.
Provide the [database](/influxdb/cloud-dedicated/admin/databases/) name.
- **Failed to deserialize org/bucket/precision**
```http
400 Bad Request
```
```json
{ "code":"invalid",
"message":"failed to deserialize org/bucket/precision in request: unknown variant `u`, expected one of `s`, `ms`, `us`, `ns`"
}
```
The `?precision=` parameter contains an unknown value.
Provide a [timestamp precision](#timestamp-precision).
## Write data
We recommend using the InfluxDB v2 API `/api/v2/write` endpoint for new write workloads and existing v2 workloads.
{{% api-endpoint endpoint="https://cluster-id.influxdb.io/api/v2/write" method="post"%}}
- [`/api/v2/write` parameters](#apiv2write-parameters)
- [Tools for writing to the v2 API](#tools-for-writing-to-the-v2-api)
### /api/v2/write parameters
For {{% cloud-name %}} v2 API `/api/v2/write` requests, set parameters as listed in the following table:
Parameter | Allowed in | Ignored | Value
-----------------|--------------|---------|-------------------------
org | Query string | Ignored | Non-zero-length string (ignored, but can't be empty)
orgID | Query string | Ignored | N/A
bucket {{% req " \*" %}} | Query string | Honored | Database name
precision | Query string | Honored | [Timestamp precision](#timestamp-precision)
Accept | Header | Honored | User-defined
`Authorization` {{% req " \*" %}} | Header | Honored | `Bearer DATABASE_TOKEN` or `Token DATABASE_TOKEN`
`Content-Encoding` | Header | Honored | `gzip` (compressed data) or `identity` (uncompressed)
Content-Length | Header | Honored | User-defined
Content-Type | Header | Ignored | N/A (only supports line protocol)
Zap-Trace-Span | Header | Ignored |
{{% caption %}}{{% req " \*" %}} = {{% req "Required" %}}{{% /caption %}}
#### Timestamp precision
Use one of the following `precision` values in v2 API `/api/v2/write` requests:
- `ns`: nanoseconds
- `us`: microseconds
- `ms`: milliseconds
- `s`: seconds
- `m`: minutes
- `h`: hours
### Tools for writing to the v2 API
The following tools work with the {{% cloud-name %}} `/api/v2/write` endpoint:
- [Telegraf](#telegraf)
- [Interactive clients](#interactive-clients)
- [Client libraries](#client-libraries)
#### Telegraf
See how to [configure Telegraf](/influxdb/cloud-dedicated/write-data/use-telegraf/configure/) to write to {{% cloud-name %}}.
#### Interactive clients
To test InfluxDB v2 API writes interactively, use the [`influx3` data CLI](https://github.com/InfluxCommunity/influxdb3-python-cli) or common HTTP clients such as cURL and Postman.
To setup and start using interactive clients, see the [Get started](/influxdb/cloud-dedicated/get-started/) tutorial.
{{% warn %}}
#### influx CLI not supported
Don't use the `influx` CLI with {{% cloud-name %}}.
While it may coincidentally work, it isn't officially supported.
{{% /warn %}}
#### Client libraries
InfluxDB [v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) and [v2 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v2/)
can write data to the InfluxDB v2 API `/api/v2/write` endpoint.
Client libraries are language-specific packages that integrate InfluxDB APIs with your application.
To setup and start using client libraries, see the [Get started](/influxdb/cloud-dedicated/get-started/) tutorial.
## Query data
{{% cloud-name %}} provides the following protocols for executing a query:
- [Flight+gRPC](https://arrow.apache.org/docs/format/Flight.html) request that contains an SQL or InfluxQL query.
- InfluxDB v1 API `/query` request that contains an InfluxQL query.
{{% note %}}
#### Tools to execute queries
{{% cloud-name %}} supports many different tools for querying data, including:
- [`influx3` data CLI](https://github.com/InfluxCommunity/influxdb3-python-cli)
- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/)
- [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/)
- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/)
- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api)
- [Chronograf](/{{< latest "Chronograf" >}}/)
{{% /note %}}
### /api/v2/query not supported
The `/api/v2/query` API endpoint and associated tooling aren't supported in {{% cloud-name %}}.

1
content/influxdb/cloud-dedicated/get-started/query.md
View File

@ -46,6 +46,7 @@ The examples in this section of the tutorial query the
{{< req type="key" text="Covered in this tutorial" color="magenta" >}}
- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/)
- [Flight SQL clients](?t=Go#execute-an-sql-query){{< req "\* " >}}
- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/)
- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/)

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

@ -24,8 +24,8 @@ This tutorial walks you through the fundamental of creating **line protocol** da
InfluxDB provides many different options for ingesting or writing data, including the following:
- InfluxDB HTTP API (v1 and v2)
- `influx` CLI (v1 and v2)
- Telegraf
- `influx3` data CLI
- InfluxDB client libraries
If using tools like Telegraf or InfluxDB client libraries, they can

12
content/influxdb/cloud-dedicated/primers/_index.md
View File

@ -1,12 +0,0 @@
---
title: How existing InfluxDB workloads work
description: >
Learn to use InfluxDB Cloud Dedicated for existing write and query workloads coming from InfluxDB version 1.x.
weight: 3
menu:
influxdb_cloud_dedicated:
name: Primers
influxdb/cloud-dedicated/tags: []
---
{{% children %}}

23
content/influxdb/cloud-dedicated/primers/api/_index.md
View File

@ -1,23 +0,0 @@
---
title: Learn to use APIs for your workloads
seo_title: Learn to use APIs for your data workloads in InfluxDB Cloud Dedicated
description: >
Choose the API and tools that fit your workload.
Learn how to authenticate, write, and query using Telegraf, client libraries, and HTTP clients.
weight: 3
menu:
influxdb_cloud_dedicated:
parent: Primers
name: API primers
influxdb/cloud-dedicated/tags: [api]
# related:
# - /influxdb/cloud/api/#tag/Write, InfluxDB API /write endpoint
# - /influxdb/cloud/reference/syntax/line-protocol
# - /influxdb/cloud/reference/syntax/annotated-csv
# - /influxdb/cloud/reference/cli/influx/write
# - /resources/videos/ingest-data/, How to Ingest Data in InfluxDB (Video)
---
Choose the {{% cloud-name %}} API and tools that best fit your workload:
{{< children sort>}}

358
content/influxdb/cloud-dedicated/primers/api/v2/_index.md
View File

@ -1,358 +0,0 @@
---
title: Use the InfluxDB v2 API with InfluxDB Cloud Dedicated
list_title: Use the InfluxDB v2 API
description: >
Use InfluxDB v2 API authentication, endpoints, and tools.
Learn how to use InfluxDB Cloud Dedicated v2 `/api/v2/write` and authentication
for new and existing workloads.
weight: 1
menu:
influxdb_cloud_dedicated:
parent: API primers
name: v2 API primer
influxdb/cloud-dedicated/tags: [write, line protocol]
---
Use the InfluxDB v2 API for new workloads and existing v2 workloads that you bring to InfluxDB Cloud Dedicated.
The InfluxDB Cloud Dedicated v2 `/api/v2/write` endpoint works with token authentication
and existing InfluxDB 2.x tools and code.
For help finding the best workflow for your situation, [contact Support](mailto:support@influxdata.com).
<!-- v2 SAMPLE CODE -->
<!-- TOC -->
- [Authenticate API requests](#authenticate-api-requests)
- [Authenticate with a token](#authenticate-with-a-token)
- [Syntax](#syntax)
- [Examples](#examples)
- [Responses](#responses)
- [Error examples](#error-examples)
- [Write data](#write-data)
- [Write using Telegraf](#write-using-telegraf)
- [Other Telegraf configuration options](#other-telegraf-configuration-options)
- [Write using client libraries](#write-using-client-libraries)
- [Write using HTTP clients](#write-using-http-clients)
- [v2 API /api/v2/write parameters](#v2-api-apiv2write-parameters)
- [Timestamp precision](#timestamp-precision)
- [Use clients for interactive testing](#use-clients-for-interactive-testing)
- [influx CLI not supported](#influx-cli-not-supported)
- [Query data](#query-data)
- [Query using Flight SQL](#query-using-flight-sql)
- [/api/v2/query not supported](#apiv2query-not-supported)
<!-- /TOC -->
## Authenticate API requests
InfluxDB requires each write request to be authenticated with a
[database token](/influxdb/cloud-dedicated/admin/tokens/).
### Authenticate with a token
Use the `Authorization: Bearer` scheme or the `Authorization: Token` scheme to pass a [database token](/influxdb/cloud-dedicated/admin/tokens/) that has _write_ permission to your database.
`Bearer` and `Token` are equivalent in InfluxDB Cloud Dedicated.
The `Token` scheme is used in the InfluxDB 2.x API.
`Bearer` is defined by the [OAuth 2.0 Framework](https://www.rfc-editor.org/rfc/rfc6750#page-14).
Support for one or the other may vary across InfluxDB API clients.
#### Syntax
```http
Authorization: Bearer DATABASE_TOKEN
```
```http
Authorization: Token DATABASE_TOKEN
```
#### Examples
Use `Bearer` to authenticate a write request:
```sh
{{% get-shared-text "api/cloud-dedicated/bearer-auth-v2-write.sh" %}}
```
Use `Token` to authenticate a write request:
```sh
{{% get-shared-text "api/cloud-dedicated/token-auth-v2-write.sh" %}}
```
Replace the following:
- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database
- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database
## Responses
InfluxDB API responses use standard HTTP status codes.
For successful writes, InfluxDB responds with a `204 No Content` status code.
Error responses contain a JSON object with `code` and `message` properties that describe the error.
Response body messages may differ across InfluxDB Cloud Dedicated v1 API, v2 API, InfluxDB Cloud, and InfluxDB OSS.
### Error examples
- **Missing bucket value**
```http
400 Bad Request
```
```json
HTTP response body: {"code":"invalid","message":"missing bucket value"}
```
The `?bucket=` parameter value is missing in the request.
Provide the [database](/influxdb/cloud-dedicated/admin/databases/) name.
- **Failed to deserialize org/bucket/precision**
```http
400 Bad Request
```
```json
{"code":"invalid","message":"failed to deserialize org/bucket/precision in request: unknown variant `u`, expected one of `s`, `ms`, `us`, `ns`"}
```
The `?precision=` parameter contains an unknown value.
Provide a [timestamp precision](#timestamp-precision).
## Write data
Use the InfluxDB Cloud Dedicated v2 API `/api/v2/write` endpoint to write data to a database.
We recommend using the v2 API `/api/v2/write` endpoint
for new and existing workloads.
See how to set parameters and configure the following tools for writing to InfluxDB Cloud Dedicated:
- [Write using Telegraf](#write-using-telegraf)
- [Write using client libraries](#write-using-client-libraries)
- [Write using HTTP clients](#write-using-http-clients)
- [v2 API /api/v2/write parameters](#v2-api-apiv2write-parameters)
- [Use clients for interactive testing](#use-clients-for-interactive-testing)
### Write using Telegraf
Use the [InfluxDB v2.x `influxdb_v2` Telegraf output plugin](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb_v2/README.md) to write data.
The following table shows `outputs.influxdb` parameters and values for writing
to InfluxDB Cloud Dedicated:
Parameter | Ignored | Value
-------------------------|--------------------------|--------------------------------------------------------------------------------------------------------------------------------|
`token` | Honored | [Database token](/influxdb/cloud-dedicated/admin/tokens/) with permission to write to the database |
`organization` | Ignored | |
`bucket` | Honored | Database name |
`content_encoding` | Honored | `gzip` (compressed data) or `identity` (uncompressed) |
To configure the v2.x output plugin for writing to InfluxDB Cloud Dedicated,
add the following `outputs.influxdb_v2` configuration in your `telegraf.conf` file:
```toml
[[outputs.influxdb_v2]]
urls = ["https://cluster-id.influxdb.io"]
token = "DATABASE_TOKEN"
organization = ""
bucket = "DATABASE_NAME"
content_encoding = "gzip"
influx_uint_support = false
```
Replace the following:
- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database
- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with permission to write to the database
#### Other Telegraf configuration options
`influx_uint_support`: supported in InfluxDB IOx.
For more plugin options, see [`influxdb_v2`](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb_v2/README.md) on GitHub.
### Write using client libraries
Use language-specific [v2 client libraries](/influxdb/cloud/api-guide/client-libraries/) and your custom code to write data to InfluxDB Cloud Dedicated.
v2 client libraries send data in [line protocol](/influxdb/cloud-dedicated/reference/syntax/line-protocol/) syntax to the v2 API `/api/v2/write` endpoint.
The following samples show how to configure **v2** client libraries for writing to InfluxDB Cloud Dedicated:
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[Node.js](#nodejs)
[Python](#python)
{{% /code-tabs %}}
{{% code-tab-content %}}
<!-- Start NodeJS -->
Create a v2 API client using the [`influxdb-client-js`](https://github.com/influxdata/influxdb-client-js) JavaScript client library:
1. Call the `InfluxDB({url, token})` constructor to instantiate an `InfluxDB` client. Provide the InfluxDB **URL** and a [database token](/influxdb/cloud-dedicated/admin/tokens/).
```js
import {InfluxDB, Point} from '@influxdata/influxdb-client'
const influxDB = new InfluxDB({'https://cluster-id.influxdb.io', DATABASE_TOKEN})
```
2. Call the client's [`getWriteApi(org, bucket, precision, writeOptions)` method](https://influxdata.github.io/influxdb-client-js/influxdb-client.influxdb.getwriteapi.html) to instantiate a **write client** for writing data to the `/api/v2/write` endpoint.
Provide the following parameter values:
- `org`: an arbitrary string (the parameter is ignored by InfluxDB Cloud Dedicated, but required by the client)
- `bucket`: InfluxDB Cloud Dedicated database
- `precision`: a [timestamp precision](#timestamp-precision) (`ns`, `u`, `ms`, `s`, `m`, `h`)
```js
const writeApi = influxDB.getWriteApi('', DATABASE_NAME, 'ns')
```
For more information about **write client** features in the InfluxDB 2.x JavaScript client library, see [`influxdb-client-js`](https://github.com/influxdata/influxdb-client-js) and the [`WriteAPI` interface](https://influxdata.github.io/influxdb-client-js/influxdb-client.writeapi.html) on GitHub.
<!-- End NodeJS -->
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-- Start Python -->
Create a v2 API client using the [influxdb-client-python](https://github.com/influxdata/influxdb-client-python) Python client library:
1. Call the `InfluxDBClient(url, token, org)` constructor to instantiate an `InfluxDBClient`.
Provide the following parameter values:
- `url=`: InfluxDB Cloud Dedicated cluster URL
- `token=`: a [database token](/influxdb/cloud-dedicated/admin/tokens/)
- `org`: an arbitrary string (the parameter is ignored by InfluxDB Cloud Dedicated, but required by the client)
```py
influxdb_client = InfluxDBClient(url='https://cluster-id.influxdb.io',
token='DATABASE_TOKEN',
org='ignored')
```
2. Call the `InfluxDBClient.write_api(write_options)` method to instantiate a **write client**.
```py
write_api = influxdb_client.write_api(write_options=SYNCHRONOUS)
```
3. To write data, call the `write_api.write()` method.
Provide the following parameter values:
- `bucket=`: InfluxDB Cloud Dedicated database
- `record=`: the point data to write
The following sample constructs a `Data Point`, calls `write()` to add the point to a line protocol batch,
and then calls `write_api.close()` to write the batch:
```py
write_api.write(bucket='DATABASE_NAME', record="home,room=kitchen temp=72 1463683075")
write_api.close()
```
For more information about the Python client library for the InfluxDB v2 API, see [`influxdb-client-python`](https://github.com/influxdata/influxdb-client-python) on GitHub.
<!-- End Python -->
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
Replace the following:
- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database
- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database
### Write using HTTP clients
Use HTTP clients and your custom code to send write requests to the v2 API `/api/v2/write` endpoint.
{{% api-endpoint endpoint="https://cluster-id.influxdb.io/api/v2/write" method="post"%}}
Include the following in your request:
- A `bucket` query string parameter with the name of the database to write to.
- A request body that contains a string of data in [line protocol](/influxdb/cloud-dedicated/reference/syntax/line-protocol/) syntax.
- A [database token](/influxdb/cloud-dedicated/admin/tokens/) in a [token authentication scheme](#authenticate-with-a-token).
- Optional [parameters](#v2-api-apiv2write-parameters).
#### v2 API /api/v2/write parameters
Parameter | Allowed in | Ignored | Value
-----------------|--------------|---------|-------------------------
org | Query string | Ignored | Non-zero-length string (ignored, but can't be empty)
orgID | Query string | Ignored | N/A
bucket {{% req " \*" %}} | Query string | Honored | Database name
precision | Query string | Honored | [Timestamp precision](#timestamp-precision)
Accept | Header | Honored | User-defined
`Authorization` {{% req " \*" %}} | Header | Honored | `Bearer DATABASE_TOKEN` or `Token DATABASE_TOKEN`
`Content-Encoding` | Header | Honored | `gzip` (compressed data) or `identity` (uncompressed)
Content-Length | Header | Honored | User-defined
Content-Type | Header | Ignored | N/A (only supports line protocol)
Zap-Trace-Span | Header | Ignored |
{{% caption %}}{{% req " \*" %}} = {{% req "Required" %}}{{% /caption %}}
#### Timestamp precision
Use one of the following `precision` values in v2 API `/api/v2/write` requests:
- `ns`: nanoseconds
- `us`: microseconds
- `ms`: milliseconds
- `s`: seconds
- `m`: minutes
- `h`: hours
#### Use clients for interactive testing
To test interactively, use common HTTP clients such as cURL and Postman to send requests to the v2 API `/api/v2/write` endpoint.
{{% warn %}}
While the `influx` CLI may coincidentally work with InfluxDB Cloud Dedicated, it isn't officially supported.
{{% /warn %}}
The following example shows how to use the **cURL** command line tool and the InfluxDB Cloud Dedicated v2 API to write line protocol data to a database:
```sh
curl --request POST \
"https://cluster-id.influxdb.io/api/v2/write?bucket=DATABASE_NAME&precision=ns" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--header "Content-Type: text/plain; charset=utf-8" \
--header "Accept: application/json" \
--data-binary '
airSensors,sensor_id=TLM0201 temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 1630424257000000000
airSensors,sensor_id=TLM0202 temperature=75.30007505999716,humidity=35.651929918691714,co=0.5141876544505826 1630424257000000000'
```
Replace the following:
- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database
- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database
### influx CLI not supported
Don't use the `influx` CLI with {{% cloud-name %}}.
While it may coincidentally work, it isn't officially supported.
If you need to test writes interactively, see how to [write using HTTP clients](#write-using-http-clients).
## Query data
Use Flight SQL clients with gRPC and SQL to query data stored in an InfluxDB Cloud Dedicated database.
### Query using Flight SQL
Choose from the following tools to query InfluxDB Cloud Dedicated:
- [Flight SQL plugin](/influxdb/cloud-dedicated/query-data/tools/grafana/) for Grafana
- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/)
- [InfluxDB v3 language-specific client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/)
- [Flight SQL language-specific clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/)
See how to [get started querying with SQL](/influxdb/cloud-dedicated/get-started/query/#sql-query-basics)
### /api/v2/query not supported
The `/api/v2/query` and associated tooling aren't supported in InfluxDB Cloud Dedicated. See how to [query using Flight SQL](#query-using-flight-sql).

34
content/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/_index.md
View File

@ -9,12 +9,36 @@ menu:
name: Flight SQL clients
parent: Client libraries
influxdb/cloud-dedicated/tags: [Golang, Python, client libraries, Flight SQL]
aliases:
- /influxdb/cloud-dedicated/reference/client-libraries/flight-sql/go-flightsql/
- /influxdb/cloud-dedicated/reference/client-libraries/flight-sql/python-flightsql-dbapi/
---
Flight SQL clients are language-specific drivers that can interact with SQL databases using the Arrow in-memory format and the Flight RPC framework.
Clients provide a [`FlightClient`](https://arrow.apache.org/docs/python/generated/pyarrow.flight.FlightClient.html#pyarrow.flight.FlightClient) that can query and retrieve data from InfluxDB v3 using gRPC and Flight SQL.
Some [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3) include Flight SQL clients.
Flight and Flight SQL clients are language-specific drivers that interact with SQL databases using the Arrow in-memory format and the Flight RPC framework.
Clients provide a [`FlightClient`](https://arrow.apache.org/docs/python/generated/pyarrow.flight.FlightClient.html#pyarrow.flight.FlightClient) that can query and retrieve data from InfluxDB v3 using gRPC and Flight.
Flight clients are maintained by Apache Arrow projects or third-parties.
For specifics about a Flight client, see the client's GitHub repository.
{{% note %}}
[InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) use Flight clients
and offer additional convenience for writing, querying, and retrieving data stored in {{% cloud-name %}}.
{{% /note %}}
## C# (csharp)
- [Apache Arrow C# FlightClient](https://github.com/apache/arrow/tree/main/csharp/examples/FlightClientExample)
## Go
- [Apache Arrow Go Flight SQL client](https://pkg.go.dev/github.com/apache/arrow/go/v12/arrow/flight/flightsql#Client)
## Java
- [Apache Arrow Java FlightClient](https://arrow.apache.org/docs/java/reference/org/apache/arrow/flight/FlightClient.html)
## Python
- [Apache Arrow PyArrow FlightClient](https://arrow.apache.org/docs/python/generated/pyarrow.flight.FlightClient.html#pyarrow.flight.FlightClient)
- [InfluxData flightsql-dbapi](https://github.com/influxdata/flightsql-dbapi)
For specifics about a client library, see the library's GitHub repository.
{{< children depth="999" description="true" >}}

7
content/influxdb/cloud-dedicated/reference/client-libraries/v2/_index.md
View File

@ -24,11 +24,12 @@ For specifics about a client library, see the library's GitHub repository.
### Tools to execute queries
InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint.
This endpoint can't query an InfluxDB Cloud Dedicated cluster.
This endpoint can't query an {{% cloud-name %}} cluster.
InfluxDB Cloud Dedicated supports many different tools for querying data, including:
{{% cloud-name %}} supports many different tools for querying data, including:
- [Flight SQL clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/)
- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/)
- [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/)
- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/)
- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api)

43
content/influxdb/cloud-dedicated/reference/client-libraries/v2/go.md
View File

@ -1,21 +1,27 @@
---
title: Go client library
seotitle: Use the InfluxDB Go client library
title: InfluxDB v2 Go client library
list_title: Go
description: >
Use the InfluxDB Go client library to interact with InfluxDB.
The InfluxDB v2 Go client library integrates with Go applications to write data to an InfluxDB Cloud Dedicated database.
menu:
influxdb_cloud_dedicated:
name: Go
parent: v2 client libraries
influxdb/cloud-dedicated/tags: [client libraries, Go]
weight: 201
aliases:
- /influxdb/cloud-dedicated/reference/api/client-libraries/go/
- /influxdb/cloud-dedicated/tools/client-libraries/go/
---
Use the [InfluxDB Go client library](https://github.com/influxdata/influxdb-client-go) to integrate InfluxDB into Go scripts and applications.
Use the [InfluxDB Go client library](https://github.com/influxdata/influxdb-client-go) to write data to an {{% cloud-name %}} database.
{{% note %}}
### Use the InfluxDB v3 client library
InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint.
This endpoint can't query an {{% cloud-name %}} database.
Use the [InfluxDB v3 Go client library](/influxdb/cloud-dedicated/reference/client-libraries/v3/go/)
to write and query data stored in {{% cloud-name %}}.
{{% /note %}}
This guide presumes some familiarity with Go and InfluxDB.
If just getting started, see [Get started with InfluxDB](/influxdb/cloud-dedicated/get-started/).
@ -30,7 +36,7 @@ If just getting started, see [Get started with InfluxDB](/influxdb/cloud-dedicat
go get github.com/influxdata/influxdb-client-go/v2
```
3. Ensure that InfluxDB is running and you can connect to it.
For information about what URL to use to connect to your InfluxDB Cloud Dedicated cluster, contact your InfluxData account representative.
For information about what URL to use to connect to your {{% cloud-name %}} cluster, contact your InfluxData account representative.
## Boilerplate for the InfluxDB Go Client Library
@ -53,9 +59,9 @@ Use the Go library to write and query data from InfluxDB.
2. Define variables for your InfluxDB [database](/influxdb/cloud-dedicated/admin/databases/) (bucket), organization (required, but ignored), and [token](/influxdb/cloud-dedicated/admin/tokens/).
```go
bucket := "example-database"
bucket := "DATABASE_NAME"
org := "ignored"
token := "example-token"
token := "DATABASE_TOKEN"
// Store the URL of your InfluxDB instance
url := "https://cluster-id.influxdb.io"
```
@ -72,12 +78,6 @@ Use the Go library to write and query data from InfluxDB.
writeAPI := client.WriteAPIBlocking(org, bucket)
```
5. To query data, create an InfluxDB **query client** and pass in your InfluxDB `org`.
```go
queryAPI := client.QueryAPI(org)
```
## Write data to InfluxDB with Go
Use the Go library to write data to InfluxDB.
@ -109,9 +109,9 @@ import (
)
func main() {
bucket := "example-database"
bucket := "DATABASE_NAME"
org := "ignored"
token := "example-token"
token := "DATABASE_TOKEN"
// Store the URL of your InfluxDB instance
url := "https://cluster-id.influxdb.io"
// Create new client with default option for server url authenticate by token
@ -129,10 +129,3 @@ func main() {
client.Close()
}
```
## Query data from InfluxDB with Go
The InfluxDB v2 Go client can't query InfluxDB Cloud Dedicated.
To query your dedicated instance, use the [Go Flight SQL client](https://pkg.go.dev/github.com/apache/arrow/go/v12/arrow/flight/flightsql).
For an example, see [Get started querying data](/influxdb/cloud-dedicated/get-started/query/?t=Go#execute-an-sql-query).
For more information, see the [Go client README on GitHub](https://github.com/influxdata/influxdb-client-go).

30
content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/_index.md
View File

@ -1,10 +1,10 @@
---
title: JavaScript client library for the InfluxDB v2 API
seotitle: Use the InfluxDB v2 JavaScript client library for the InfluxDB v2 API
seotitle: InfluxDB v2 JavaScript client library for the InfluxDB v2 API
list_title: JavaScript
description: >
Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js)
for Node.js and browsers to write data to a InfluxDB Cloud Dedicated cluster.
The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js)
for Node.js and browsers integrates with the InfluxDB v2 API to write data to an InfluxDB Cloud Dedicated cluster.
menu:
influxdb_cloud_dedicated:
name: JavaScript
@ -15,7 +15,25 @@ aliases:
- /influxdb/cloud-dedicated/reference/api/client-libraries/js/
---
Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js)
for Node.js and browsers to write data to a InfluxDB Cloud Dedicated cluster.
The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js)
for Node.js and browsers integrates with the InfluxDB v2 API to write data to an {{% cloud-name %}} cluster.
{{< children type="list">}}
{{% note %}}
### Tools to execute queries
InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint.
This endpoint can't query an {{% cloud-name %}} cluster.
{{% cloud-name %}} supports many different tools for querying data, including:
- [`influx3` data CLI](https://github.com/InfluxCommunity/influxdb3-python-cli)
- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/)
- [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/)
- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/)
- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api)
- [Chronograf](/{{< latest "Chronograf" >}}/)
{{% /note %}}
{{< children depth="999" >}}

35
content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/browser.md
View File

@ -1,9 +1,8 @@
---
title: JavaScript client library for web browsers
seotitle: Use the InfluxDB v2 JavaScript client library for web browsers
title: InfluxDB v2 JavaScript client library for web browsers
list_title: JavaScript for browsers
description: >
Use the InfluxDB v2 JavaScript client library to interact with InfluxDB in web clients.
Use the InfluxDB v2 JavaScript client library in browsers and front-end clients to write data to an InfluxDB Cloud Dedicated database.
menu:
influxdb_cloud_dedicated:
name: Browsers and web clients
@ -19,23 +18,19 @@ related:
- /influxdb/cloud-dedicated/api-guide/client-libraries/nodejs/query/
---
Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) in browsers and front-end clients to write data to an InfluxDB Cloud Dedicated database. This library supports both front-end and server-side environments and provides the following distributions:
* ECMAScript modules (ESM) and CommonJS modules (CJS)
* Bundled ESM
* Bundled UMD
This guide presumes some familiarity with JavaScript, browser environments, and InfluxDB.
If you're just getting started with InfluxDB, see [Get started with InfluxDB](/{{% latest "influxdb" %}}/get-started/).
Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) in browsers and front-end clients to write data to an {{% cloud-name %}} database.
{{% note %}}
### Tools to execute queries
InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint.
This endpoint can't query an InfluxDB Cloud Dedicated cluster.
This endpoint can't query an {{% cloud-name %}} database.
InfluxDB Cloud Dedicated supports many different tools for querying data, including:
{{% cloud-name %}} supports many different tools for querying data, including:
- [Flight SQL clients](?t=Go#execute-an-sql-query)
- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/)
- [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/)
- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/)
- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api)
@ -43,6 +38,16 @@ InfluxDB Cloud Dedicated supports many different tools for querying data, includ
{{% /note %}}
This library supports both front-end and server-side environments and provides the following distributions:
- ECMAScript modules (ESM) and CommonJS modules (CJS)
- Bundled ESM
- Bundled UMD
This guide presumes some familiarity with JavaScript, browser environments, and InfluxDB.
If you're just getting started with InfluxDB, see [Get started with InfluxDB](/{{% latest "influxdb" %}}/get-started/).
{{% warn %}}
### Tokens in production applications
{{% api/browser-token-warning %}}
@ -58,7 +63,7 @@ InfluxDB Cloud Dedicated supports many different tools for querying data, includ
1. Install [Node.js](https://nodejs.org/en/download/package-manager/) to serve your front-end app.
2. Ensure that InfluxDB is running and you can connect to it.
For information about what URL to use to connect to your InfluxDB Cloud Dedicated cluster, contact your InfluxData account representative.
For information about what URL to use to connect to your {{% cloud-name %}} cluster, contact your InfluxData account representative.
## Use with module bundlers
@ -121,7 +126,7 @@ The client library includes an example browser app that writes to your InfluxDB
cd examples
```
3. Update `./env_browser.js` with your InfluxDB Cloud Dedicated cluster URL, your database name as `bucket`, an arbitrary string as `org`, and your database token.
3. Update `./env_browser.js` with your {{% cloud-name %}} cluster URL, your database name as `bucket`, an arbitrary string as `org`, and your database token.
4. Run the following command to start the application at [http://localhost:3001/examples/index.html]()

24
content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/_index.md
View File

@ -1,9 +1,10 @@
---
title: Node.js JavaScript client library
seotitle: Use the InfluxDB v2 JavaScript client library
seotitle: InfluxDB v2 JavaScript client library for Node.js
list_title: Node.js
description: >
Use the InfluxDB v2 JavaScript client library to interact with InfluxDB.
The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js)
for Node.js integrates with the InfluxDB v2 API to write data to an InfluxDB Cloud Dedicated database.
menu:
influxdb_cloud_dedicated:
name: Node.js
@ -14,26 +15,27 @@ aliases:
- /influxdb/cloud-dedicated/reference/api/client-libraries/nodejs/
---
Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js)
to write data from Node.js and browser applications to an InfluxDB Cloud Dedicated cluster.
## Use the client library in a Node.js application
{{< children >}}
The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js)
integrates with the InfluxDB v2 API to write data from Node.js and browser applications to an {{% cloud-name %}} database.
{{% note %}}
### Tools to execute queries
InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint.
This endpoint can't query an InfluxDB Cloud Dedicated cluster.
This endpoint can't query an {{% cloud-name %}} database.
InfluxDB Cloud Dedicated supports many different tools for querying data, including:
{{% cloud-name %}} supports many different tools for querying data, including:
- [Flight SQL clients](?t=Go#execute-an-sql-query)
- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/)
- [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/)
- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/)
- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api)
- [Chronograf](/{{< latest "Chronograf" >}}/)
{{% /note %}}
## Use the client library in a Node.js application
{{< children >}}

59
content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/install.md
View File

@ -1,35 +1,61 @@
---
title: Install the InfluxDB v2 JavaScript client library
seotitle: Install the InfluxDB Node.js JavaScript client library
description: >
Install the Node.js JavaScript client library to interact with the InfluxDB v2 API.
Install the Node.js JavaScript client library to write data to an InfluxDB Cloud Dedicated database.
menu:
influxdb_cloud_dedicated:
name: Install
parent: Node.js
influxdb/cloud-dedicated/tags: [client libraries, JavaScript]
influxdb/cloud-serverless/tags: [client libraries, JavaScript]
weight: 100
aliases:
- /influxdb/cloud-dedicated/reference/api/client-libraries/nodejs/install
- /influxdb/cloud-serverless/reference/api/client-libraries/nodejs/install
---
{{% note %}}
Install the Node.js JavaScript client library to write data to an {{% cloud-name %}} database.
### Tools to execute queries
InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint.
This endpoint can't query an {{% cloud-name %}} database.
{{% cloud-name %}} supports many different tools for querying data, including:
- [InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/)
- [Flight clients](/influxdb/cloud-serverless/reference/client-libraries/flight-sql/)
- [Superset](/influxdb/cloud-serverless/query-data/execute-queries/flight-sql/superset/)
- [Grafana](/influxdb/cloud-serverless/query-data/tools/grafana/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-serverless/primers/api/v1/#query-using-the-v1-api)
- [Chronograf](/{{< latest "Chronograf" >}}/)
{{% /note %}}
## Install Node.js
1. Install [Node.js](https://nodejs.org/en/download/package-manager/).
2. Ensure that InfluxDB is running and you can connect to it.
For information about what URL to use to connect to your InfluxDB Cloud Dedicated cluster, contact your InfluxData account representative.
For information about what URL to use to connect to your {{% cloud-name %}} cluster, contact your InfluxData account representative.
3. Start a new Node.js project.
The `npm` package manager is included with Node.js.
3. In your terminal, create a directory for your Node.js project and change to it.
```sh
npm init -y influx-node-app
```
```sh
mkdir influx-node-app && cd $_
```
4. Enter the following command to generate an npm package for your project.
The `npm` package manager is included with Node.js.
```sh
npm init -y
```
## Install TypeScript
Many of the client library examples use [TypeScript](https://www.typescriptlang.org/). Follow these steps to initialize the TypeScript project.
Many of the client library examples use [TypeScript](https://www.typescriptlang.org/).
Follow these steps to initialize the TypeScript project:
1. Install TypeScript and type definitions for Node.js.
@ -49,14 +75,15 @@ Many of the client library examples use [TypeScript](https://www.typescriptlang.
## Install dependencies
Open a new terminal window and install `@influxdata/influxdb-client`:
Use the `@influxdata/influxdb-client` JavaScript client library to write data in {{% cloud-name %}}.
Open a new terminal window and install the `@influxdata/influxdb-client` package for querying and writing data:
```sh
npm i --save @influxdata/influxdb-client
```
The `@influxdata/influxdb-client-apis` client library package doesn't
work with InfluxDB v3.
The `@influxdata/influxdb-client-apis` client library package won't work with {{% cloud-name %}}.
It only works with InfluxDB v2 management APIs.
## Configure credentials
@ -64,7 +91,7 @@ It only works with InfluxDB v2 management APIs.
The client examples include an [`env`](https://github.com/influxdata/influxdb-client-js/blob/master/examples/env.js) module for accessing your InfluxDB properties from environment variables or from `env.js`.
The examples use these properties to interact with the InfluxDB API.
Set environment variables or update `env.js` with your InfluxDB [database](/influxdb/cloud-dedicated/admin/databases/) (bucket), organization (required, but ignored), [token](/influxdb/cloud-dedicated/admin/tokens/), and cluster URL.
Set environment variables or update `env.js` with your InfluxDB [database](/influxdb/cloud-dedicated/admin/databases/), organization (required, but ignored), [token](/influxdb/cloud-dedicated/admin/tokens/), and cluster URL.
```sh
export INFLUX_URL=https://cluster-id.influxdb.io
@ -79,6 +106,6 @@ Set environment variables or update `env.js` with your InfluxDB [database](/infl
## Next steps
Once you've installed the client library and configured credentials, you're ready to [write data](/influxdb/cloud-dedicated/api-guide/client-libraries/nodejs/write/) to InfluxDB.
Once you've installed the client library and configured credentials, you're ready to [write data](/influxdb/cloud-serverless/api-guide/client-libraries/nodejs/write/) to InfluxDB.
{{< page-nav next="/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/write/" keepTab=true >}}

4
content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/write.md
View File

@ -2,7 +2,7 @@
title: Write data with the InfluxDB v2 JavaScript client library
list_title: Write data
description: >
Use the JavaScript client library to write data with the InfluxDB API in Node.js.
The InfluxDB v2 JavaScript client library integrates with Node.js applications to write data to the InfluxDB v2 API.
menu:
influxdb_cloud_dedicated:
name: Write
@ -29,7 +29,7 @@ The Javascript client library includes the following convenient features for wri
### Write data with the client library
1. Instantiate an `InfluxDB` client. Provide your InfluxDB URL and database token.
1. Instantiate a client by calling the `new InfluxDB()` constructor with your InfluxDB URL and database token (environment variables you already set in the [Install section](/influxdb/cloud-dedicated/api-guide/client-libraries/nodejs/install/)).
```js
import {InfluxDB, Point} from '@influxdata/influxdb-client'

15
content/influxdb/cloud-dedicated/reference/client-libraries/v3/_index.md
View File

@ -13,11 +13,20 @@ influxdb/cloud-dedicated/tags: [client libraries, API, developer tools]
## Client libraries for InfluxDB v3
InfluxDB v3 client libraries use InfluxDB HTTP APIs to write data and use [Flight SQL clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql) to query data stored in an InfluxDB Cloud Dedicated database.
InfluxDB v3 client libraries are language-specific packages that work with
and integrate with your application to write to and query data in {{% cloud-name %}}.
Functionality varies among client libraries.
These client libraries are in active development and may not be feature-complete.
InfluxDB client libraries provide configurable batch writing of data to InfluxDB HTTP APIs.
They can be used to construct line protocol data and transform data from other formats
to line protocol.
InfluxDB v3 client libraries can query InfluxDB v3 using the Arrow Flight protocol with gRPC.
Client libraries use Flight clients to execute SQL and InfluxQL queries, request
database information, and retrieve data stored in {{% cloud-name %}}.
Additional functionality may vary among client libraries and some may not be feature-complete.
For specifics about a client library, see the library's GitHub repository.
InfluxDB v3 client libraries are part of the [Influx Community](https://github.com/InfluxCommunity).
{{< children depth="999" description="true" >}}

24
content/influxdb/cloud-dedicated/reference/client-libraries/v3/go.md Normal file
View File

@ -0,0 +1,24 @@
---
title: Go client library for InfluxDB v3
list_title: Go
description: >
The InfluxDB v3 `influxdb3-go` Go client library integrates with Go scripts and applications to write and query data stored in an InfluxDB Cloud Dedicated database.
external_url: https://github.com/InfluxCommunity/influxdb3-go
menu:
influxdb_cloud_dedicated:
name: Go
parent: v3 client libraries
identifier: influxdb3-go
influxdb/cloud-dedicated/tags: [go, gRPC, SQL, Flight SQL, client libraries]
weight: 201
aliases:
- /influxdb/cloud-dedicated/reference/api/client-libraries/go/
- /influxdb/cloud-dedicated/tools/client-libraries/go/
---
The InfluxDB v3 [`influxdb3-go` Go client library](https://github.com/InfluxCommunity/influxdb3-go) integrates with Go scripts and applications
to write and query data stored in an {{% cloud-name %}} database.
The documentation for this client library is available on GitHub.
<a href="https://github.com/InfluxCommunity/influxdb3-go" target="_blank" class="btn github">InfluxDB v3 Go client library</a>

484
content/influxdb/cloud-dedicated/reference/client-libraries/v3/python.md
View File

@ -7,8 +7,6 @@ menu:
influxdb_cloud_dedicated:
name: Python
parent: v3 client libraries
params:
url: https://github.com/InfluxCommunity/influxdb3-python
identifier: influxdb3-python
influxdb/cloud-dedicated/tags: [python, gRPC, SQL, Flight SQL, client libraries]
weight: 201
@ -16,9 +14,483 @@ aliases:
- /influxdb/cloud-dedicated/reference/client-libraries/v3/pyinflux3/
---
The InfluxDB v3 [`influxdb3-python` Python client library](https://github.com/InfluxCommunity/influxdb3-python) integrates with Python scripts and applications
to write and query data stored in an {{% cloud-name %}} database.
The InfluxDB v3 [`influxdb3-python` Python client library](https://github.com/InfluxCommunity/influxdb3-python)
integrates {{% cloud-name %}} write and query operations with Python scripts and applications.
The documentation for this client library is available on GitHub.
InfluxDB client libraries provide configurable batch writing of data to {{% cloud-name %}}.
Client libraries can be used to construct line protocol data, transform data from other formats
to line protocol, and batch write line protocol data to InfluxDB HTTP APIs.
<a href="https://github.com/InfluxCommunity/influxdb3-python" target="_blank" class="btn github">InfluxDB v3 Python client library</a>
InfluxDB v3 client libraries can query {{% cloud-name %}} using SQL or InfluxQL.
The `influxdb3-python` Python client library wraps the Apache Arrow `pyarrow.flight` client
in a convenient InfluxDB v3 interface for executing SQL and InfluxQL queries, requesting
server metadata, and retrieving data from {{% cloud-name %}} using the Flight protocol with gRPC.
## Installation
Install the client library and dependencies using `pip`:
```bash
pip install influxdb3-python
```
## Importing the module
The `influxdb3-python` client library package provides the `influxdb_client_3`
module.
Import the module:
```py
import influxdb_client_3
```
Import specific class methods from the module:
```py
from influxdb_client_3 import InfluxDBClient3, Point, WriteOptions
```
- [`influxdb_client_3.InfluxDBClient3` class](#class-influxdbclient3): an interface for [initializing
a client](#initialization) and interacting with InfluxDB
- `influxdb_client_3.Point` class: an interface for constructing a time series data
point
- `influxdb_client_3.WriteOptions` class: an interface for configuring
write options `influxdb_client_3.InfluxDBClient3` for the client.
## API reference
The `influxdb_client_3` module includes the following classes and functions.
<!-- TOC -->
- [Classes](#classes)
- [Functions](#functions)
- [Constants](#constants)
- [Exceptions](#exceptions)
## Classes
- [Class InfluxDBClient3](#class-influxdbclient3)
- [InfluxDBClient3.write](#influxdbclient3write)
- [InfluxDBClient3.write_file](#influxdbclient3write_file)
- [InfluxDBClient3.query](#influxdbclient3query)
- [InfluxDBClient3.close](#influxdbclient3close)
- [Class Point](#class-point)
- [Class WriteOptions](#class-writeoptions)
## Class InfluxDBClient3
Provides an interface for interacting with InfluxDB APIs for writing and querying data.
### Syntax
```py
__init__(self, host=None, org=None, database=None, token=None,
_write_client_options=None, _flight_client_options=None, **kwargs)
```
Initializes and returns an `InfluxDBClient3` instance with the following:
- A singleton _write client_ configured for writing to the database.
- A singleton _Flight client_ configured for querying the database.
### Attributes
- **org** (str): The organization name (for {{% cloud-name %}}, set this to an empty string (`""`)).
- **database** (str): The database to use for writing and querying.
- **_write_client_options** (dict): Options to use when writing to InfluxDB.
If `None`, writes are [synchronous](#synchronous-writing).
- **_flight_client_options** (dict): Options to use when querying InfluxDB.
#### Batch writing
In batching mode, the client adds the record or records to a batch, and then schedules the batch for writing to InfluxDB.
The client writes the batch to InfluxDB after reaching `_write_client_options.batch_size` or `_write_client_options.flush_interval`.
If a write fails, the client reschedules the write according to the `_write_client_options` retry options.
To use batching mode, pass an instance of `WriteOptions` for the `InfluxDBClient3._write_client_options` argument--for example:
1. Instantiate `WriteOptions()` with defaults or with
`WriteOptions.write_type=WriteType.batching`.
```py
# Batching with all batch size, flush, and retry defaults
write_options = WriteOptions()
```
2. Call the a `write_client_options` function to create an options object that uses `write_options` from the preceding step.
```py
wco = write_client_options(WriteOptions=write_options)
```
3. Initialize the client, setting the `_write_client_options` argument to the `wco` object from the preceding step.
{{< tabs-wrapper >}}
{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}}
```py
with InfluxDBClient3(token="DATABASE_TOKEN", host="cluster-id.influxdb.io",
org="", database="DATABASE_NAME",
_write_client_options=wco) as client:
client.write(record=points)
```
{{% /code-placeholders %}}
{{< /tabs-wrapper >}}
#### Synchronous writing
In synchronous mode, the client sends write requests immediately (not batched)
and doesn't retry failed writes.
To use synchronous mode, set `_write_client_options=None` or `_write_client_options.write_type=WriteType.synchronous`.
### Examples
##### Initialize a client
The following example initializes a client for writing and querying the database.
Given `_write_client_options=None`, the client will use synchronous mode when writing data.
{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}}
```py
client = InfluxDBClient3(token="DATABASE_TOKEN",
host="cluster-id.influxdb.io",
org="",
database="DATABASE_NAME")
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}:
Your InfluxDB token with READ permissions on the databases you want to query.
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
The name of your InfluxDB database.
##### Initialize a client for batch writing
The following example shows how to initialize a client for writing and querying the database.
When writing data, the client will use batch mode with default options and will
invoke the callback function for the response.
{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}
```py
import influxdb_client_3 as InfluxDBClient3
from influxdb_client_3 import write_client_options, WriteOptions, InfluxDBError
points = [Point("home").tag("room", "Kitchen").field("temp", 25.3),
Point("home").tag("room", "Living Room").field("temp", 18.4)]
# Define callbacks for write responses
def success(self, conf: (str, str, str)):
"""BATCH WRITE SUCCESS."""
print(f"Wrote batch: {conf}")
def error(self, conf: (str, str, str), exception: InfluxDBError):
"""BATCH WRITE FAILURE."""
print(f"Cannot write batch: {conf}, due to: {exception}")
def retry(self, conf: (str, str, str), exception: InfluxDBError):
"""BATCH WRITE RETRY"""
print(f"Retryable error occurs for batch: {conf}, retry: {exception}")
# Instantiate WriteOptions for batching
write_options = WriteOptions()
wco = write_client_options(success_callback=success,
error_callback=error,
retry_callback=retry,
WriteOptions=write_options)
with InfluxDBClient3(token="DATABASE_TOKEN", host="cluster-id.influxdb.io",
org="", database="DATABASE_NAME",
_write_client_options=wco) as client:
client.write(record=points)
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}:
Your InfluxDB token with READ permissions on the databases you want to query.
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
The name of your InfluxDB database.
### Instance methods
<!-- TOC -->
- [InfluxDBClient3.write](#influxdbclient3write)
- [InfluxDBClient3.write_file](#influxdbclient3write_file)
- [InfluxDBClient3.query](#influxdbclient3query)
- [InfluxDBClient3.close](#influxdbclient3close)
### InfluxDBClient3.write
Writes a record or a list of records to InfluxDB.
A record can be a `Point` object, a dict that represents a point, a line protocol string, or a `DataFrame`.
The client can write using [_batching_ mode](#batch-writing) or [_synchronous_ mode](#synchronous-writing).
##### Attributes
- **`write_precision=`**: `"ms"`, `"s"`, `"us"`, `"ns"`. Default is `"ns"`.
#### Syntax
```py
write(self, record=None, **kwargs)
```
#### Examples
##### Write a line protocol string
{{% influxdb/custom-timestamps %}}
{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}
```py
points = "home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000"
client = InfluxDBClient3(token="DATABASE_TOKEN", host="cluster-id.influxdb.io",
database="DATABASE_NAME", org="")
client.write(record=points, write_precision="s")
```
{{% /code-placeholders %}}
{{% /influxdb/custom-timestamps %}}
##### Write data using points
The `influxdb_client_3.Point` class provides an interface for constructing a data
point for a measurement and setting fields, tags, and the timestamp for the point.
The following example shows how to create a `Point` object, and then write the
data to InfluxDB.
```py
point = Point("home").tag("room", "Kitchen").field("temp", 72)
client.write(point)
```
###### Write data using a dict
`InfluxDBClient3` can serialize a dictionary object into line protocol.
If you pass a `dict` to `InfluxDBClient3.write`, the client expects the `dict` to have the
following _point_ data structure:
- **measurement** (str): the measurement name
- **tags** (dict): a dictionary of tag key-value pairs
- **fields** (dict): a dictionary of field key-value pairs
- **time**: the [timestamp](/influxdb/cloud-dedicated/reference/glossary/#timestamp) for the record
The following example shows how to define a `dict` that represents a point, and then write the
data to InfluxDB.
{{% influxdb/custom-timestamps %}}
{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}
```py
# Using point dictionary structure
points = {
"measurement": "home",
"tags": {"room": "Kitchen", "sensor": "K001"},
"fields": {"temp": 72.2, "hum": 36.9, "co": 4},
"time": 1641067200
}
client = InfluxDBClient3(token="DATABASE_TOKEN",
host="cluster-id.influxdb.io",
database="DATABASE_NAME",
org="")
client.write(record=points, write_precision="s")
```
{{% /code-placeholders %}}
{{% /influxdb/custom-timestamps %}}
### InfluxDBClient3.write_file
Writes data from a file to InfluxDB.
The client can write using [_batching_ mode](#batch-writing) or [_synchronous_ mode](#synchronous-writing).
#### Syntax
```py
write_file(self, file, measurement_name=None, tag_columns=[],
timestamp_column='time', **kwargs)
```
##### Attributes
- **`file`**: A file containing records to write to InfluxDB.
The following file formats and file name extensions are supported.
The file name must end with one of the supported extensions.
For more information about encoding and formatting data, see the documentation for each supported format.
| Supported format | File name extension |
|:---------------------------------------------------------------------------|:--------------------|
| [Feather](https://arrow.apache.org/docs/python/feather.html) | `.feather` |
| [Parquet](https://arrow.apache.org/docs/python/parquet.html) | `.parquet` |
| [Comma-separated values](https://arrow.apache.org/docs/python/csv.html) | `.csv` |
| [JSON](https://pandas.pydata.org/docs/reference/api/pandas.read_json.html) | `.json` |
| [ORC](https://arrow.apache.org/docs/python/orc.html) | `.orc` |
- **`measurement_name`**: Defines the measurement name for records in the file.
The specified value takes precedence over `measurement` and `iox::measurement` columns in the file.
If no value is specified for the parameter, and a `measurement` column exists in the file, the `measurement` column value is used for the measurement name.
If no value is specified for the parameter, and no `measurement` column exists, the `iox::measurement` column value is used for the measurement name.
- **`tag_columns`**: A list containing the names of tag columns.
Columns not included in the list and not specified by another parameter are assumed to be fields.
- **`timestamp_column`**: The name of the column that contains timestamps. Default is `'time'`.
#### Examples
##### Write data from a file
The following example shows how to configure write options for batching, retries, and callbacks,
and how to write data from CSV and JSON files to InfluxDB:
{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}
```py
from influxdb_client_3 import InfluxDBClient3, write_client_options,
WritePrecision, WriteOptions, InfluxDBError
class BatchingCallback(object):
# Define callbacks for write responses
def success(self, conf: (str, str, str)):
"""BATCH WRITE SUCCESS."""
print(f"Wrote batch: {conf}")
def error(self, conf: (str, str, str), exception: InfluxDBError):
"""BATCH WRITE FAILURE."""
print(f"Cannot write batch: {conf}, due to: {exception}")
def retry(self, conf: (str, str, str), exception: InfluxDBError):
"""BATCH WRITE RETRY"""
print(f"Retryable error occurs for batch: {conf}, retry: {exception}")
# Instantiate the callbacks
callback = BatchingCallback()
write_options = WriteOptions(batch_size=500,
flush_interval=10_000,
jitter_interval=2_000,
retry_interval=5_000,
max_retries=5,
max_retry_delay=30_000,
exponential_base=2)
wco = write_client_options(success_callback=callback.success,
error_callback=callback.error,
retry_callback=callback.retry,
WriteOptions=write_options
)
with InfluxDBClient3(token="DATABASE_TOKEN", host="cluster-id.influxdb.io",
org="", database="DATABASE_NAME",
_write_client_options=wco) as client:
client.write_file(file='./out.csv', timestamp_column='time',
tag_columns=["provider", "machineID"])
client.write_file(file='./out.json', timestamp_column='time',
tag_columns=["provider", "machineID"], date_unit='ns')
```
{{% /code-placeholders %}}
### InfluxDBClient3.query
Sends a Flight request to execute the specified SQL or InfluxQL query.
Returns all data in the query result as an Arrow table.
#### Syntax
```py
query(self, query, language="sql")
```
#### Examples
##### Query using SQL
```py
query = "select * from measurement"
reader = client.query(query=query, language="sql")
table = reader.read_all()
print(table.to_pandas().to_markdown())
```
##### Query using InfluxQL
```py
query = "select * from measurement"
reader = client.query(query=query, language="influxql")
table = reader.read_all()
print(table.to_pandas().to_markdown())
```
### InfluxDBClient3.close
Sends all remaining records from the batch to InfluxDB,
and then closes the underlying write client and Flight client to release resources.
#### Syntax
```py
close(self)
```
#### Examples
```py
client.close()
```
## Class Point
```py
influxdb_client_3.Point
```
A timeseries data point.
## Class WriteOptions
```py
influxdb_client_3.WriteOptions
```
Options for configuring client behavior (batch size, retry, callbacks, etc.) when writing data to InfluxDB.
For client configuration examples, see [Initialize a client](#initialize-a-client).
### Syntax
```py
__init__(self, write_type: WriteType = WriteType.batching,
batch_size=1_000, flush_interval=1_000,
jitter_interval=0,
retry_interval=5_000,
max_retries=5,
max_retry_delay=125_000,
max_retry_time=180_000,
exponential_base=2,
max_close_wait=300_000,
write_scheduler=ThreadPoolScheduler(max_workers=1)) -> None:
```
## Functions
- `influxdb_client_3.write_client_options(**kwargs)`
Returns a dictionary of write client options.
- `influxdb_client_3.flight_client_options(**kwargs)`
Returns a dictionary of flight client options.
## Constants
- `influxdb_client_3.SYNCHRONOUS`: Represents synchronous write mode.
- `influxdb_client_3.WritePrecision`: Enum class representing write precision options.
## Exceptions
- `influxdb_client_3.InfluxDBError`: Exception raised for InfluxDB-related errors.

9
content/influxdb/cloud-dedicated/write-data/use-telegraf/configure/_index.md
View File

@ -1,6 +1,6 @@
---
title: Configure Telegraf for InfluxDB
seotitle: Configure Telegraf to write to InfluxDB
seotitle: Configure Telegraf to write data to InfluxDB
description: >
Telegraf is a plugin-based agent with plugins that are enabled and configured in
your Telegraf configuration file (`telegraf.conf`).
@ -41,6 +41,7 @@ for using Telegraf with {{< cloud-name >}}._
- [organization](#organization)
- [bucket](#bucket)
- [Write to InfluxDB v1.x and {{< cloud-name >}}](#write-to-influxdb-v1x-and--cloud-name-)
- [Other Telegraf configuration options](#other-telegraf-configuration-options)
- [Start Telegraf](#start-telegraf)
<!-- /TOC -->
@ -119,6 +120,12 @@ If a Telegraf agent is already writing to an InfluxDB v1.x database,
enabling the InfluxDB v2 output plugin will write data to both v1.x and your {{< cloud-name >}} cluster.
{{% /note %}}
### Other Telegraf configuration options
`influx_uint_support`: supported in InfluxDB IOx.
For more plugin options, see [`influxdb`](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) on GitHub.
## Start Telegraf
Start the Telegraf service using the `--config` flag to specify the location of your `telegraf.conf`.

18
content/influxdb/cloud-serverless/api-compatibility/_index.md Normal file
View File

@ -0,0 +1,18 @@
---
title: Learn to use APIs for your workloads
seo_title: Learn to use APIs for your data workloads in InfluxDB Cloud Serverless
description: >
Choose the API and tools that fit your workload.
Learn how to authenticate, write, and query using Telegraf, client libraries, and HTTP clients.
weight: 999
menu:
influxdb_cloud_serverless:
name: API compatibility
influxdb/cloud-serverless/tags: [api]
related:
- /influxdb/cloud-serverless/reference/api/
---
Choose the {{% cloud-name %}} API and tools that best fit your workload:
{{< children sort>}}

484
content/influxdb/cloud-serverless/api-compatibility/v1/_index.md Normal file
View File

@ -0,0 +1,484 @@
---
title: Use the InfluxDB v1 API with InfluxDB Cloud Serverless
list_title: Use the InfluxDB v1 API
description: >
Use InfluxDB v1 API authentication, endpoints, and tools when bringing existing 1.x workloads to InfluxDB Cloud Serverless.
weight: 3
menu:
influxdb_cloud_serverless:
parent: API compatibility
name: v1 API
aliases:
- /influxdb/cloud-serverless/primers/api/v1/
influxdb/cloud-serverless/tags: [write, line protocol]
related:
- /influxdb/cloud-serverless/query-data/sql/
- /influxdb/cloud-serverless/query-data/influxql/
- /influxdb/cloud-serverless/write-data/
- /influxdb/cloud-serverless/write-data/use-telegraf/configure/
- /influxdb/cloud-serverless/reference/api/
- /influxdb/cloud-serverless/reference/client-libraries/
---
Use the InfluxDB v1 API `/write` and `/query` endpoints with v1 workloads that you bring to {{% cloud-name %}}.
The v1 endpoints work with username/password authentication and existing InfluxDB 1.x tools and code.
The InfluxDB v1 API `/write` endpoint works with
InfluxDB 1.x client libraries and the [Telegraf v1 Output Plugin](/telegraf/v1.26/plugins/#output-influxdb).
The InfluxDB v1 API `/query` endpoint supports InfluxQL and third-party integrations like [Grafana](https://grafana.com).
Learn how to authenticate requests, adjust request parameters for existing v1 workloads, and find compatible tools for writing and querying data stored in an {{% cloud-name %}} database.
<!-- TOC -->
- [Authenticate API requests](#authenticate-api-requests)
- [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme)
- [Basic authentication](#basic-authentication)
- [Syntax](#syntax)
- [Example](#example)
- [Query string authentication](#query-string-authentication)
- [Syntax](#syntax)
- [Example](#example)
- [Authenticate with a token scheme](#authenticate-with-a-token-scheme)
- [Syntax](#syntax)
- [Examples](#examples)
- [Responses](#responses)
- [Error examples](#error-examples)
- [Write data](#write-data)
- [v1 API /write parameters](#v1-api-write-parameters)
- [Timestamp precision](#timestamp-precision)
- [Tools for writing to the v1 API](#tools-for-writing-to-the-v1-api)
- [Telegraf](#telegraf)
- [Other Telegraf configuration options](#other-telegraf-configuration-options)
- [Interactive clients](#interactive-clients)
- [v1 CLI not supported](#v1-cli-not-supported)
- [Client libraries](#client-libraries)
- [Query data](#query-data)
- [v1 API /query parameters](#v1-api-query-parameters)
- [Timestamp precision](#timestamp-precision)
- [Query data](#query-data)
- [Tools to execute queries](#tools-to-execute-queries)
- [Bucket management with InfluxQL not supported](#bucket-management-with-influxql-not-supported)
<!-- /TOC -->
## Authenticate API requests
InfluxDB requires each API request to be authenticated with a
[API token](/influxdb/cloud-serverless/admin/tokens/).
With the InfluxDB v1 API, you can use API tokens in InfluxDB 1.x username and password
schemes or in the InfluxDB v2 `Authorization: Token` scheme.
- [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme)
- [Authenticate with a token scheme](#authenticate-with-a-token)
### Authenticate with a username and password scheme
With the InfluxDB v1 API, you can use the InfluxDB 1.x convention of
username and password to authenticate bucket reads and writes by passing an [API token](/influxdb/cloud-serverless/admin/tokens/) as the `password` credential.
When authenticating requests to the v1 API `/write` and `/query` endpoints, {{% cloud-name %}} checks that the `password` (`p`) value is an authorized [API token](/influxdb/cloud-serverless/admin/tokens/).
{{% cloud-name %}} ignores the `username` (`u`) parameter in the request.
Use one of the following authentication schemes with clients that support Basic authentication or query parameters (that don't support [token authentication](#authenticate-with-a-token)):
- [Basic authentication](#basic-authentication)
- [Query string authentication](#query-string-authentication)
#### Basic authentication
Use the `Authorization` header with the `Basic` scheme to authenticate v1 API `/write` and `/query` requests.
When authenticating requests, {{% cloud-name %}} checks that the `password` part of the decoded credential is an authorized [API token](/influxdb/cloud-serverless/admin/tokens/).
{{% cloud-name %}} ignores the `username` part of the decoded credential.
##### Syntax
```http
Authorization: Basic <base64-encoded [USERNAME]:API_TOKEN>
```
Encode the `[USERNAME]:DATABASE_TOKEN` credential using base64 encoding, and then append the encoded string to the `Authorization: Basic` header.
{{% api/v1-compat/basic-auth-syntax %}}
##### Example
The following example shows how to use cURL with the `Basic` authentication scheme and an [API token](/influxdb/cloud-serverless/admin/tokens/):
{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}}
```sh
{{% get-shared-text "api/cloud-serverless/basic-auth.sh" %}}
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: your {{% cloud-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
#### Query string authentication
In the URL, pass the `p` query parameter to authenticate `/write` and `/query` requests.
When authenticating requests, {{% cloud-name %}} checks that the `p` (_password_) value is an authorized API token and ignores the `u` (_username_) parameter.
##### Syntax
```sh
https://cloud2.influxdata.com/query/?[u=any]&p=API_TOKEN
https://cloud2.influxdata.com/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/).
{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}}
```sh
{{% get-shared-text "api/cloud-serverless/querystring-auth.sh" %}}
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: your {{% cloud-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
### Authenticate with a token scheme
Use the `Authorization: Token` scheme to pass an [API token](/influxdb/cloud-serverless/admin/tokens/) for authenticating
v1 API `/write` and `/query` requests.
#### Syntax
```http
Authorization: Token API_TOKEN
```
#### Examples
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" %}}
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: your {{% cloud-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
## Responses
InfluxDB API responses use standard HTTP status codes.
For successful writes, InfluxDB responds with a `204 No Content` status code.
Error responses contain a JSON object with `code` and `message` properties that describe the error.
Response body messages may differ across {{% cloud-name %}} v1 API, v2 API, InfluxDB Cloud, and InfluxDB OSS.
### Error examples
- **Invalid namespace name**:
```http
400 Bad Request
```
```json
{ "code":"invalid",
"message":"namespace name length must be between 1 and 64 characters"
}
```
The `?db=` parameter value is missing in the request.
Provide the [bucket](/influxdb/cloud-serverless/admin/buckets/) name.
- **Failed to deserialize db/rp/precision**
```http
400 Bad Request
```
```json
{ "code": "invalid",
"message": "failed to deserialize db/rp/precision in request: unknown variant `u`, expected one of `s`, `ms`, `us`, `ns`"
}
```
The `?precision=` parameter contains an unknown value.
Provide a [timestamp precision](#timestamp-precision).
## Write data
Write data with your existing workloads that already use the InfluxDB v1 or v1.x-compatibility `/write` API endpoint.
{{% api-endpoint endpoint="https://cloud2.influxdata.com/write" method="post" %}}
- [`/api/v2/write` parameters](#v1-api-write-parameters)
- [Tools for writing to the v1 API](#tools-for-writing-to-the-v1-api)
#### v1 API /write parameters
For {{% cloud-name %}} v1 API `/write` requests, set parameters as listed in the following table:
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
`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
`Content-Encoding` | Header | Honored | `gzip` (compressed data) or `identity` (uncompressed)
`Authorization` | Header | Honored | `Token API_TOKEN`, or `Basic <base64 [USERNAME]:API_TOKEN>`
{{% caption %}}{{% req " \*" %}} = {{% req "Required" %}}{{% /caption %}}
#### Timestamp precision
Use one of the following `precision` values in v1 API `/write` requests:
- `ns`: nanoseconds
- `us`: microseconds
- `ms`: milliseconds
- `s`: seconds
- `m`: minutes
- `h`: hours
### Tools for writing to the v1 API
The following tools work with the {{% cloud-name %}} `/write` endpoint:
- [Telegraf](#telegraf)
- [Interactive clients](#interactive-clients)
- [Client libraries](#client-libraries)
#### Telegraf
If you have existing v1 workloads that use Telegraf,
you can use the [InfluxDB v1.x `influxdb` Telegraf output plugin](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) to write data.
{{% note %}}
See how to [use Telegraf and the v2 API](/influxdb/cloud-serverless/write-data/use-telegraf/) for new workloads that don't already use the v1 API.
{{% /note %}}
The following table shows `outputs.influxdb` plugin parameters and values for writing to the {{% cloud-name %}} v1 API:
Parameter | Ignored | Value
-------------------------|--------------------------|---------------------------------------------------------------------------------------------------
`database` | Honored | Bucket name
`retention_policy` | Honored | [Duration](/influxdb/cloud-serverless/reference/glossary/#duration)
`username` | Ignored | String or empty
`password` | Honored | [API token](/influxdb/cloud-serverless/admin/tokens/) with permission to write to the bucket
`content_encoding` | Honored | `gzip` (compressed data) or `identity` (uncompressed)
`skip_database_creation` | Ignored | N/A (see how to [create a bucket](/influxdb/cloud-serverless/admin/buckets/create/))
To configure the v1.x output plugin for writing to {{% cloud-name %}}, add the following `outputs.influxdb` configuration in your `telegraf.conf` file:
{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}}
```toml
[[outputs.influxdb]]
urls = ["https://cloud2.influxdata.com"]
database = "BUCKET_NAME"
skip_database_creation = true
retention_policy = "RETENTION_POLICY"
username = "ignored"
password = "API_TOKEN"
content_encoding = "gzip”
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: your {{% cloud-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
##### Other Telegraf configuration options
`influx_uint_support`: supported in InfluxDB IOx.
For more plugin options, see [`influxdb`](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) on GitHub.
#### Interactive clients
To test InfluxDB v1 API writes interactively from the command line, use common HTTP clients such as cURL and Postman.
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).
- Optional [parameters](#v1-api-write-parameters).
The following example shows how to use the **cURL** command line tool and the {{% cloud-name %}} v1 API to write line protocol data to a bucket:
{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}}
```sh
curl -i 'https://cloud2.influxdata.com/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 %}}
Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: your {{% cloud-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
##### v1 CLI (not supported)
Don't use the v1 CLI with {{% cloud-name %}}.
While it may coincidentally work, it isn't officially supported.
#### Client libraries
Use language-specific [v1 client libraries](/influxdb/v1.8/tools/api_client_libraries/) and your custom code to write data to InfluxDB.
v1 client libraries send data in [line protocol](/influxdb/cloud-serverless/reference/syntax/line-protocol/) syntax to the v1 API `/write` endpoint.
The following samples show how to configure **v1** client libraries for writing to {{% cloud-name %}}:
{{< tabs-wrapper >}}
{{% tabs %}}
[Node.js](#nodejs)
[Python](#python)
{{% /tabs %}}
{{% tab-content %}}
<!-- Start NodeJS -->
Create a v1 API client using the [node-influx](/influxdb/v1.7/tools/api_client_libraries/#javascriptnodejs) JavaScript client library:
{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}}
```js
const Influx = require('influx')
// Instantiate a client for writing to {{% cloud-name %}} v1 API
const client = new Influx.InfluxDB({
host: 'cloud2.influxdata.com',
port: 443,
protocol: 'https'
database: 'BUCKET_NAME',
username: 'ignored',
password: 'API_TOKEN'
})
// When calling write or query functions, specify the retention policy name in options.
```
{{% /code-placeholders %}}
<!-- End NodeJS -->
{{% /tab-content %}}
{{% tab-content %}}
<!-- Start Python -->
Create a v1 API client using the [influxdb-python](/influxdb/v1.7/tools/api_client_libraries/#python) Python client library:
{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}}
```py
from influxdb import InfluxDBClient
# Instantiate a client for writing to {{% cloud-name %}} v1 API
client = InfluxDBClient(
host='cloud2.influxdata.com',
ssl=True,
database='BUCKET_NAME',
username='',
password='API_TOKEN'
headers={'Content-Type': 'text/plain; charset=utf-8'}
)
# When calling write or query functions, specify the retention policy name in options.
```
{{% /code-placeholders %}}
<!-- End Python -->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} bucket
- {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: your {{% cloud-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
## Query data
{{% cloud-name %}} provides the following protocols for executing a query:
- [Flight+gRPC](https://arrow.apache.org/docs/format/Flight.html) request that contains an SQL or InfluxQL query.
- InfluxDB v1 API `/query` request that contains an InfluxQL query.
Use the v1 API `/query` endpoint and [InfluxQL](/influxdb/cloud-serverless/reference/glossary/#influxql) with {{% cloud-name %}} when you bring InfluxDB 1.x workloads that already use them.
- [v1 API /query parameters](#v1-api-query-parameters)
- [Query using HTTP clients]()
### v1 API /query parameters
Parameter | Allowed in | Ignored | Value
----------|------------|---------|-------------------------------------------------------------------------
`chunked` | | Ignored | N/A _(Note that an unbounded query might return a large amount of data)_
`db` | Query string | Honored | Bucket name |
`epoch` | Query string | Honored | [Timestamp precision](#timestamp-precision) |
`p` | Query string | Honored | API token
`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
`rp` | Query string | Honored | Retention policy
#### Timestamp precision
Use one of the following values for timestamp precision:
- `ns`: nanoseconds
- `us`: microseconds
- `ms`: milliseconds
- `s`: seconds
- `m`: minutes
- `h`: hours
## Query data
{{% cloud-name %}} provides the following protocols for executing a query:
- [Flight+gRPC](https://arrow.apache.org/docs/format/Flight.html) request that contains an SQL or InfluxQL query.
- InfluxDB v1 API `/query` request that contains an InfluxQL query.
{{% note %}}
#### Tools to execute queries
{{% cloud-name %}} supports many different tools for querying data, including:
- [`influx3` data CLI](https://github.com/InfluxCommunity/influxdb3-python-cli)
- [InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/)
- [Flight clients](/influxdb/cloud-serverless/reference/client-libraries/flight-sql/)
- [Superset](/influxdb/cloud-serverless/query-data/execute-queries/flight-sql/superset/)
- [Grafana](/influxdb/cloud-serverless/query-data/tools/grafana/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-serverless/primers/api/v1/#query-using-the-v1-api)
- [Chronograf](/{{< latest "Chronograf" >}}/)
{{% /note %}}
### Bucket management with InfluxQL (not supported)
{{% cloud-name %}} doesn't allow InfluxQL commands for managing or modifying buckets.
You can't use the following InfluxQL commands:
```sql
SELECT INTO
CREATE
DELETE
DROP
GRANT
EXPLAIN
REVOKE
ALTER
SET
KILL
```

207
content/influxdb/cloud-serverless/api-compatibility/v2/_index.md Normal file
View File

@ -0,0 +1,207 @@
---
title: Use the InfluxDB v2 API with InfluxDB Cloud Serverless
list_title: InfluxDB v2 API compatibility
description: >
Use the InfluxDB v2 API for new write workloads and existing v2 write workloads.
InfluxDB Cloud Serverless is compatible with the InfluxDB v2 API `/api/v2/write` endpoint and existing InfluxDB 2.x tools and code.
weight: 1
menu:
influxdb_cloud_serverless:
parent: API compatibility
name: v2 API
influxdb/cloud-serverless/tags: [write, line protocol]
aliases:
- /influxdb/cloud-serverless/primers/api/v2/
---
{{% cloud-name %}} is compatible with the InfluxDB v2 API `/api/v2/write` endpoint and existing InfluxDB 2.x tools and code.
Use the InfluxDB v2 API for new write workloads and existing v2 write workloads that you bring to {{% cloud-name %}}.
InfluxDB v2 API endpoints won't work for managing resources or querying data in {{% cloud-name %}}.
To query data, use the _Flight+gRPC_ protocol or the InfluxDB v1 `/query` HTTP API endpoint and [associated tools](#tools-to-execute-queries).
<!-- TOC -->
- [Authenticate API requests](#authenticate-api-requests)
- [Authenticate with a token](#authenticate-with-a-token)
- [Syntax](#syntax)
- [Examples](#examples)
- [Responses](#responses)
- [Error examples](#error-examples)
- [Write data](#write-data)
- [/api/v2/write parameters](#apiv2write-parameters)
- [Timestamp precision](#timestamp-precision)
- [Tools for writing to the v2 API](#tools-for-writing-to-the-v2-api)
- [Telegraf](#telegraf)
- [Interactive clients](#interactive-clients)
- [Client libraries](#client-libraries)
- [Query data](#query-data)
- [Tools to execute queries](#tools-to-execute-queries)
- [/api/v2/query not supported](#apiv2query-not-supported)
<!-- /TOC -->
## Authenticate API requests
InfluxDB API endpoints require each request to be authenticated with an [API token](/influxdb/cloud-serverless/admin/tokens/).
### Authenticate with a token
Use the `Authorization: Token` scheme to pass an [API token](/influxdb/cloud-serverless/admin/tokens/) that has the necessary permissions for the operation.
The `Token` scheme is used in the InfluxDB 2.x API.
#### Syntax
```http
Authorization: Token API_TOKEN
```
#### Examples
Use `Token` to authenticate a write request:
{{% code-placeholders "BUCKET_NAME|API_TOKEN" %}}
```sh
# Use the Token authentication scheme with /api/v2/write
curl --post "https://cloud2.influxdata.com/api/v2/write?bucket=BUCKET_NAME&precision=s" \
--header "Authorization: Token API_TOKEN" \
--data-binary 'home,room=kitchen temp=72 1463683075'
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: your InfluxDB Cloud Serverless [bucket](/influxdb/cloud-serverless/admin/buckets/)
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: an [API token](/influxdb/cloud-serverless/admin/tokens/) with sufficient permissions to the database
## Responses
InfluxDB API responses use standard HTTP status codes.
For successful writes, InfluxDB responds with a `204 No Content` status code.
Error responses contain a JSON object with `code` and `message` properties that describe the error.
Response body messages may differ across {{% cloud-name %}} v1 API, v2 API, InfluxDB Cloud, and InfluxDB OSS.
### Error examples
- **Missing bucket value**
```http
400 Bad Request
```
```json
{ "code": "invalid",
"message":"missing bucket value"
}
```
The `?bucket=` parameter value is missing in the request.
Provide the [bucket](/influxdb/cloud-serverless/admin/buckets/) name.
- **Failed to deserialize org/bucket/precision**
```http
400 Bad Request
```
```json
{ "code": "invalid",
"message":"failed to deserialize org/bucket/precision in request: unknown variant `u`, expected one of `s`, `ms`, `us`, `ns`"
}
```
The `?precision=` parameter contains an unknown value.
Provide a [timestamp precision](#timestamp-precision).
## Write data
We recommend using the InfluxDB v2 API `/api/v2/write` endpoint for new write workloads and existing v2 workloads.
{{% api-endpoint endpoint="https://cloud2.influxdata.com/api/v2/write" method="post"%}}
- [`/api/v2/write` parameters](#apiv2write-parameters)
- [Tools for writing to the v2 API](#tools-for-writing-to-the-v2-api)
### /api/v2/write parameters
For {{% cloud-name %}} v2 API `/api/v2/write` requests, set parameters as listed in the following table:
Parameter | Allowed in | Ignored | Value
-----------------|--------------|---------|-------------------------
org | Query string | Ignored | Non-zero-length string (ignored, but can't be empty)
orgID | Query string | Ignored | N/A
bucket {{% req " \*" %}} | Query string | Honored | Database name
precision | Query string | Honored | [Timestamp precision](#timestamp-precision)
Accept | Header | Honored | User-defined
`Authorization` {{% req " \*" %}} | Header | Honored | `Token API_TOKEN`
`Content-Encoding` | Header | Honored | `gzip` (compressed data) or `identity` (uncompressed)
Content-Length | Header | Honored | User-defined
Content-Type | Header | Ignored | N/A (only supports line protocol)
Zap-Trace-Span | Header | Ignored |
{{% caption %}}{{% req " \*" %}} = {{% req "Required" %}}{{% /caption %}}
#### Timestamp precision
Use one of the following `precision` values in v2 API `/api/v2/write` requests:
- `ns`: nanoseconds
- `us`: microseconds
- `ms`: milliseconds
- `s`: seconds
- `m`: minutes
- `h`: hours
### Tools for writing to the v2 API
The following tools work with the {{% cloud-name %}} `/api/v2/write` endpoint:
- [Telegraf](#telegraf)
- [Interactive clients](#interactive-command-line-clients)
- [Client libraries](#client-libraries)
#### Telegraf
See how to [configure Telegraf](/influxdb/cloud-serverless/write-data/use-telegraf/configure/) to write to {{% cloud-name %}}.
#### Interactive clients
To test InfluxDB v2 API writes interactively from the command line, use the [`influx3` data CLI](https://github.com/InfluxCommunity/influxdb3-python-cli) or common HTTP clients such as cURL and Postman.
To setup and start using interactive clients, see the [Get started](/influxdb/cloud-serverless/get-started/) tutorial.
#### Client libraries
InfluxDB [v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/) and [v2 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v2/) can write data to the InfluxDB v2 API `/api/v2/write` endpoint.
Client libraries are language-specific packages that integrate InfluxDB APIs with your application.
To setup and start using client libraries, see the [Get started](/influxdb/cloud-dedicated/get-started/) tutorial.
## Query data
InfluxDB v3 provides the following protocols for executing a query:
- [Flight+gRPC](https://arrow.apache.org/docs/format/Flight.html) request that contains an SQL or InfluxQL query.
- InfluxDB v1 API `/query` request that contains an InfluxQL query.
{{% note %}}
#### Tools to execute queries
{{% cloud-name %}} supports many different tools for querying data, including:
- [`influx3` data CLI](https://github.com/InfluxCommunity/influxdb3-python-cli)
- [InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/)
- [Flight clients](/influxdb/cloud-serverless/reference/client-libraries/flight-sql/)
- [Superset](/influxdb/cloud-serverless/query-data/execute-queries/flight-sql/superset/)
- [Grafana](/influxdb/cloud-serverless/query-data/tools/grafana/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-serverless/primers/api/v1/#query-using-the-v1-api)
- [Chronograf](/{{< latest "Chronograf" >}}/)
{{% /note %}}
### /api/v2/query not supported
The `/api/v2/query` API endpoint and associated tooling aren't supported in {{% cloud-name %}}.

8
content/influxdb/cloud-serverless/get-started/query.md
View File

@ -49,14 +49,16 @@ The examples in this section of the tutorial query the [**get-started** bucket](
{{< req type="key" text="Covered in this tutorial" >}}
- [Flight SQL clients](?t=Go#execute-an-sql-query){{< req "\* " >}}
- [InfluxDB user interface (UI)](?t=InfluxDB+UI#execute-an-sql-query){{< req "\* " >}}
- [`influx3` data CLI](?t=influx3+CLI#execute-an-sql-query){{< req "\* " >}}
- [InfluxDB HTTP API](?t=InfluxDB+API#execute-an-sql-query){{< req "\* " >}}
- [`influx` CLI](?t=influx+CLI#execute-an-sql-query){{< req "\* " >}}
- [InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/)
- [Flight SQL clients](- [Flight clients](/influxdb/cloud-serverless/reference/client-libraries/flight-sql/)
){{< req "\* " >}}
- [Superset](/influxdb/cloud-serverless/query-data/execute-queries/flight-sql/superset/)
- [Grafana](/influxdb/cloud-serverless/query-data/tools/grafana/)
- [Chronograf](/{{< latest "Chronograf" >}}/)
- [InfluxDB HTTP API](?t=InfluxDB+API#execute-an-sql-query){{< req "\* " >}}
- [`influx` CLI](?t=influx+CLI#execute-an-sql-query){{< req "\* " >}}
## SQL query basics

42
content/influxdb/cloud-serverless/reference/client-libraries/v2/go.md
View File

@ -1,21 +1,28 @@
---
title: Go client library
seotitle: Use the InfluxDB Go client library
title: InfluxDB v2 Go client library
list_title: Go
description: >
Use the InfluxDB Go client library to interact with InfluxDB.
The InfluxDB v2 Go client library integrates with Go applications to write data to an InfluxDB Cloud Serverless bucket.
menu:
influxdb_cloud_serverless:
name: Go
parent: v2 client libraries
influxdb/cloud-serverless/tags: [client libraries, Go]
weight: 201
aliases:
- /influxdb/cloud-serverless/reference/api/client-libraries/go/
- /influxdb/cloud-serverless/tools/client-libraries/go/
---
Use the [InfluxDB Go client library](https://github.com/influxdata/influxdb-client-go) to integrate InfluxDB into Go scripts and applications.
The [InfluxDB Go client library](https://github.com/influxdata/influxdb-client-go)
integrates with Go applications to write data to an {{% cloud-name %}} bucket.
{{% note %}}
### Use the InfluxDB v3 client library
InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint.
This endpoint can't query an {{% cloud-name %}} cluster.
Use the [InfluxDB v3 Go client library](/influxdb/cloud-dedicated/reference/client-libraries/v3/go/)
to write and query data stored in {{% cloud-name %}}.
{{% /note %}}
This guide presumes some familiarity with Go and InfluxDB.
If just getting started, see [Get started with InfluxDB](/influxdb/cloud-serverless/get-started/).
@ -50,12 +57,13 @@ Use the Go library to write and query data from InfluxDB.
)
```
2. Define variables for your InfluxDB [bucket](/influxdb/cloud-serverless/organizations/buckets/), [organization](/influxdb/cloud-serverless/organizations/), and [token](/influxdb/cloud-serverless/security/tokens/).
2. Define variables for your InfluxDB [bucket](/influxdb/cloud-serverless/organizations/buckets/) and [token](/influxdb/cloud-serverless/security/tokens/).
For `org`, pass a non-empty string (this parameter is ignored by InfluxDB, but required by the client).
```go
bucket := "example-bucket"
org := "example-org"
token := "example-token"
bucket := "BUCKET_NAME"
org := "ignored"
token := "API_TOKEN"
// Store the URL of your InfluxDB instance
url := "https://cloud2.influxdata.com"
```
@ -72,12 +80,6 @@ Use the Go library to write and query data from InfluxDB.
writeAPI := client.WriteAPIBlocking(org, bucket)
```
5. To query data, create an InfluxDB **query client** and pass in your InfluxDB `org`.
```go
queryAPI := client.QueryAPI(org)
```
## Write data to InfluxDB with Go
Use the Go library to write data to InfluxDB.
@ -109,9 +111,9 @@ import (
)
func main() {
bucket := "example-bucket"
org := "example-org"
token := "example-token"
bucket := "BUCKET_NAME"
org := "ignored"
token := "API_TOKEN"
// Store the URL of your InfluxDB instance
url := "https://cloud2.influxdata.com"
// Create new client with default option for server url authenticate by token

27
content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/_index.md
View File

@ -1,10 +1,10 @@
---
title: JavaScript client library for the InfluxDB v2 API
seotitle: Use the InfluxDB v2 JavaScript client library for the InfluxDB v2 API
seotitle: InfluxDB v2 JavaScript client library for the InfluxDB v2 API
list_title: JavaScript
description: >
Use the InfluxDB v2 JavaScript client library to integrate with InfluxDB and the InfluxDB v2 API.
external_url: https://github.com/influxdata/influxdb-client-js
The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js)
for Node.js and browsers integrates with the InfluxDB v2 API to write data to an InfluxDB Cloud Serverless bucket.
menu:
influxdb_cloud_serverless:
name: JavaScript
@ -15,6 +15,25 @@ aliases:
- /influxdb/cloud-serverless/reference/api/client-libraries/js/
---
Use the [InfluxDB JavaScript client library](https://github.com/influxdata/influxdb-client-js) to integrate InfluxDB into Node.js and browser applications.
The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js)
for Node.js and browsers integrates with the InfluxDB v2 API to write data to an {{% cloud-name %}} cluster.
{{% note %}}
### Tools to execute queries
InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint.
This endpoint can't query an {{% cloud-name %}} cluster.
{{% cloud-name %}} supports many different tools for querying data, including:
- [`influx3` data CLI](https://github.com/InfluxCommunity/influxdb3-python-cli)
- [InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/)
- [Flight clients](/influxdb/cloud-serverless/reference/client-libraries/flight-sql/)
- [Superset](/influxdb/cloud-serverless/query-data/execute-queries/flight-sql/superset/)
- [Grafana](/influxdb/cloud-serverless/query-data/tools/grafana/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-serverless/primers/api/v1/#query-using-the-v1-api)
- [Chronograf](/{{< latest "Chronograf" >}}/)
{{% /note %}}
{{< children type="list">}}

44
content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/browser.md
View File

@ -1,9 +1,8 @@
---
title: JavaScript client library for web browsers
seotitle: Use the InfluxDB v2 JavaScript client library for web browsers
title: InfluxDB v2 JavaScript client library for web browsers
list_title: JavaScript for browsers
description: >
Use the InfluxDB v2 JavaScript client library to integrate with InfluxDB in web clients.
Use the InfluxDB v2 JavaScript client library in browsers and front-end clients to write data to an InfluxDB Cloud Serverless bucket.
menu:
influxdb_cloud_serverless:
name: Browsers and web clients
@ -19,7 +18,27 @@ related:
- /influxdb/cloud-serverless/api-guide/client-libraries/nodejs/query/
---
Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) to integrate the InfluxDB v2 API in browsers and front-end clients. This library supports both front-end and server-side environments and provides the following distributions:
Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) in browsers and front-end clients to write data to an {{% cloud-name %}} bucket.
{{% note %}}
### Tools to execute queries
InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint.
This endpoint can't query an {{% cloud-name %}} cluster.
{{% cloud-name %}} supports many different tools for querying data, including:
- [InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/)
- [Flight clients](/influxdb/cloud-serverless/reference/client-libraries/flight-sql/)
- [Superset](/influxdb/cloud-serverless/query-data/execute-queries/flight-sql/superset/)
- [Grafana](/influxdb/cloud-serverless/query-data/tools/grafana/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-serverless/primers/api/v1/#query-using-the-v1-api)
- [Chronograf](/{{< latest "Chronograf" >}}/)
{{% /note %}}
This library supports both front-end and server-side environments and provides the following distributions:
* ECMAScript modules (ESM) and CommonJS modules (CJS)
* Bundled ESM
* Bundled UMD
@ -42,12 +61,10 @@ If you're just getting started with InfluxDB, see [Get started with InfluxDB](/{
1. Install [Node.js](https://nodejs.org/en/download/package-manager/) to serve your front-end app.
2. Ensure that InfluxDB is running and you can connect to it.
For information about what URL to use to connect to InfluxDB Cloud, see [InfluxDB URLs](/{{% latest "influxdb" %}}/reference/urls/).
## Use with module bundlers
If you use a module bundler like Webpack or Parcel, install `@influxdata/influxdb-client-browser`.
For more information and examples, see [Node.js](/{{% latest "influxdb" %}}/api-guide/client-libraries/nodejs/).
## Use bundled distributions with browsers and module loaders
@ -56,14 +73,14 @@ For more information and examples, see [Node.js](/{{% latest "influxdb" %}}/api-
```html
<script>
window.INFLUX_ENV = {
url: 'http://localhost:8086',
token: 'INFLUX_READ_WRITE_TOKEN'
url: 'https://cloud2.influxdata.com',
token: 'API_TOKEN'
}
</script>
```
Replace the following:
- **`INFLUX_READ_WRITE_TOKEN`**: An InfluxDB token with _write_ permission to the bucket.
- **`API_TOKEN`**: An InfluxDB token with WRITE permission to the bucket.
2. Import modules from the latest client library browser distribution.
`@influxdata/influxdb-client-browser` exports bundled ESM and UMD syntaxes.
@ -95,20 +112,21 @@ For more information and examples, see [Node.js](/{{% latest "influxdb" %}}/api-
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
After you've imported the client library, you're ready to [write data](/{{% latest "influxdb" %}}/api-guide/client-libraries/nodejs/write/?t=nodejs) to InfluxDB.
After you've imported the client library, you're ready to [get started writing data with the example app](#get-started-with-the-example-app).
## Get started with the example app
This library includes an example browser app that queries from and writes to your InfluxDB instance.
The client library includes an example browser app that writes to your InfluxDB instance.
1. Clone the [influxdb-client-js](https://github.com/influxdata/influxdb-client-js) repo.
2. Navigate to the `examples` directory:
```js
cd examples
```
3. Update `./env_browser.js` with your InfluxDB [url](/{{% latest "influxdb" %}}/reference/urls/), [bucket](/{{% latest "influxdb" %}}/organizations/buckets/), [organization](/{{% latest "influxdb" %}}/organizations/), and [token](/{{% latest "influxdb" %}}/security/tokens/)
3. Update `./env_browser.js` with your {{% cloud-name %}} region URL, your [bucket](/influxdb/cloud-serverless/admin/buckets/), an arbitrary string as `org`, and your [API token](/influxdb/cloud-serverless/admin/tokens/).
4. Run the following command to start the application at [http://localhost:3001/examples/index.html]()
@ -117,3 +135,5 @@ This library includes an example browser app that queries from and writes to you
```
`index.html` loads the `env_browser.js` configuration, the client library ESM modules, and the application in your browser.
For more examples, see how to [write data using the JavaScript client library for Node.js](/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/write/).

33
content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/_index.md
View File

@ -1,10 +1,10 @@
---
title: Node.js JavaScript client library
seotitle: Use the InfluxDB v2 JavaScript client library
seotitle: InfluxDB v2 JavaScript client library for Node.js
list_title: Node.js
description: >
Use the InfluxDB v2 JavaScript client library to integrate with InfluxDB.
external_url: https://github.com/influxdata/influxdb-client-js
The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js)
for Node.js integrates with the InfluxDB v2 API to write data to an InfluxDB Cloud Serverless bucket.
menu:
influxdb_cloud_serverless:
name: Node.js
@ -13,10 +13,33 @@ influxdb/cloud-serverless/tags: [client libraries, JavaScript, NodeJS]
weight: 201
aliases:
- /influxdb/cloud-serverless/reference/api/client-libraries/nodejs/
- /influxdb/cloud-serverless/reference/api/client-libraries/nodejs/query/
---
Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) to integrate InfluxDB into Node.js and browser applications.
The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js)
integrates with the InfluxDB v2 API to write data from Node.js and browser applications to {{% cloud-name %}}.
{{% note %}}
### Tools to execute queries
InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint.
This endpoint can't query an {{% cloud-name %}} cluster.
{{% cloud-name %}} supports many different tools for querying data, including:
- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/)
- [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/)
- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/)
- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api)
- [Chronograf](/{{< latest "Chronograf" >}}/)
{{% /note %}}
## Use the client library in a Node.js application
{{< children type="list">}}
{{< children >}}

30
content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/install.md
View File

@ -1,8 +1,7 @@
---
title: Install the InfluxDB v2 JavaScript client library
seotitle: Install the InfluxDB Node.js JavaScript client library
description: >
Install the Node.js JavaScript client library to integrate with the InfluxDB v2 API.
Install the Node.js JavaScript client library to write data to InfluxDB Cloud Serverless.
menu:
influxdb_cloud_serverless:
name: Install
@ -13,13 +12,32 @@ aliases:
- /influxdb/cloud-serverless/reference/api/client-libraries/nodejs/install
---
{{% note %}}
Install the Node.js JavaScript client library to write data to InfluxDB {{% cloud-name %}}.
### Tools to execute queries
InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint.
This endpoint can't query an {{% cloud-name %}} cluster.
{{% cloud-name %}} supports many different tools for querying data, including:
- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/)
- [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/)
- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/)
- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api)
- [Chronograf](/{{< latest "Chronograf" >}}/)
{{% /note %}}
## Install Node.js
1. Install [Node.js](https://nodejs.org/en/download/package-manager/).
2. Ensure that InfluxDB is running and you can connect to it.
For information about what URL to use to connect to InfluxDB Cloud, see [InfluxDB URLs](/influxdb/cloud-serverless/reference/urls/).
For information about what URL to use to connect to {{% cloud-name %}}, see [InfluxDB URLs](/influxdb/cloud-serverless/reference/urls/).
3. In your terminal, create a directory for your Node.js project and change to it.
@ -57,15 +75,15 @@ Follow these steps to initialize the TypeScript project:
## Install dependencies
Use the `@influxdata/influxdb-client` JavaScript client library to write and query data in {{% cloud-name %}}.
Use the `@influxdata/influxdb-client` JavaScript client library to write data in {{% cloud-name %}}.
Open a new terminal window and install the `@influxdata/influxdb-client` package for querying and writing data:
```sh
npm install --save @influxdata/influxdb-client
npm i --save @influxdata/influxdb-client
```
The `@influxdata/influxdb-client-apis` client library package won't work with InfluxDB v3.
The `@influxdata/influxdb-client-apis` client library package won't work with {{% cloud-name %}}.
It only works with InfluxDB v2 management APIs.
## Configure credentials

120
content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/query.md
View File

@ -1,120 +0,0 @@
---
title: Query data with the InfluxDB v2 JavaScript client library
description: >
Use the InfluxDB v2 JavaScript client library to query data stored in an InfluxDB Cloud Serverless bucket.
Learn how to use Flux with SQL in an InfluxDB v2 client library.
menu:
influxdb_cloud_serverless:
name: Query
parent: Node.js
influxdb/cloud-serverless/tags: [client libraries, JavaScript]
weight: 201
aliases:
- /influxdb/cloud-serverless/reference/api/client-libraries/nodejs/query/
---
Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) in a Node.js environment to query data stored in an InfluxDB Cloud Serverless bucket.
The InfluxDB v2 JavaScript client library uses Flux and the InfluxDB API [`/api/v2/query` endpoint](/influxdb/cloud-serverless/api/#operation/PostQuery) to query data.
{{< api-endpoint endpoint="http://localhost:8086/api/v2/query" method="post" api-ref="/influxdb/cloud-serverless/api/#operation/PostQuery" >}}
The following example sends a Flux-wrapped SQL query to an InfluxDB bucket, and then uses RxJS with an observer to process response data.
## Before you begin
- [Install the client library and other dependencies](/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/install/).
## Query InfluxDB
1. Change to your new project directory and create a file for your query module.
```sh
cd influx-node-app && touch query.js
```
2. In `query.js`:
1. Import `InfluxDB` from `@influxdata/influxdb-client`.
2. Define an [SQL query](/influxdb/cloud-serverless/reference/sql/) as a string. Assign a variable to the query.
3. Define a Flux script as a string that contains the following:
- `import` statement for the `experimental/iox` library.
- `iox.sql(bucket:, query:)` function call with your bucket name and the SQL query from the preceding step.
Assign a variable to the script.
{{% warn %}}
To prevent SQL injection attacks, avoid concatenating unsafe user input with queries.
{{% /warn %}}
4. Call the `new InfluxDB({url, token})` constructor to instantiate an `InfluxDB` API client. Provide your InfluxDB URL and API token (environment variables you already set in the [Install section](/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/install/)).
5. Call the client's `getQueryApi()` method with your InfluxDB organization ID to create a `QueryApi` query client configured for your organization.
6. Define an [RxJS **Observer**](http://reactivex.io/rxjs/manual/overview.html#observer) with a `next()` callback that will process data and table metadata for each row in the result.
7. Call the query client's `queryRows(query, consumer)` method.
Provide the Flux script and the observer as arguments.
The `queryRows` method sends the request, and then subscribes the `observer` to the response data.
### Complete example
```js
import {InfluxDB} from '@influxdata/influxdb-client';
// Define the SQL to query data in your bucket.
const sql=`
SELECT
DATE_BIN(INTERVAL '2 hours', time, '1970-01-01T00:00:00Z'::TIMESTAMP) AS _time,
sensor_id,
AVG(value) AS 'average temp'
FROM temperature
GROUP BY
_time,
sensor_id
ORDER BY sensor_id, _time
`;
// Define a Flux script that uses iox.sql() to execute the SQL against the bucket.
const fluxQuery = `
import "experimental/iox"
iox.sql(
bucket: "${process.env.INFLUX_BUCKET}",
query: "${sql}"
)
`;
// Instantiate a query client permisssioned to query the bucket in your organization.
const queryApi = new InfluxDB({url: process.env.INFLUX_URL,
token: process.env.INFLUX_TOKEN})
.getQueryApi(process.env.INFLUX_ORG);
console.log('*** QueryRows ***');
// Define an RxJS observer that handles notifications and processes your data.
const observer = {
next: (row, tableMeta) => {
// From each row, create an object with column names as keys.
const o = tableMeta.toObject(row)
// Process data--for example, output columns to the console.
console.log(
`${o.time}: sensor: ${o['sensor_id']}, temp: ${o['average temp']}`
)
},
error: (error) => {
console.error(error)
console.log('\nQueryRows ERROR')
},
complete: () => {
console.log('\nQueryRows SUCCESS')
},
};
// Send the request and subscribe the observer to the response data.
queryApi.queryRows(fluxQuery, observer);
```
In your terminal with [environment variables or `env.js` set](/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/install/#configure-credentials), run the following command to execute the JavaScript file:
```sh
node query.js
```
If successful, the observer receives a `next` notification for each row and outputs data to the terminal.
{{< page-nav prev="/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/write/" keepTab=true >}}

4
content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/write.md
View File

@ -2,7 +2,7 @@
title: Write data with the InfluxDB v2 JavaScript client library
list_title: Write data
description: >
Use the JavaScript client library to write data with the InfluxDB API in Node.js.
The JavaScript client library integrates with Node.js applications to write data to an InfluxDB Cloud Serverless bucket.
menu:
influxdb_cloud_serverless:
name: Write
@ -63,7 +63,7 @@ The Javascript client library includes the following convenient features for wri
```js
const point1 = new Point('temperature')
.tag('sensor_id', 'TLM010')
.floatField('value', 24)
.floatField('value', 24.0)
```
5. Use the `writePoint()` method to write the point to your InfluxDB bucket.

15
content/influxdb/cloud-serverless/reference/client-libraries/v3/_index.md
View File

@ -13,11 +13,20 @@ influxdb/cloud-serverless/tags: [client libraries, API, developer tools]
## Client libraries for InfluxDB v3
InfluxDB v3 client libraries use InfluxDB HTTP APIs to write data and use [Flight SQL clients](/influxdb/cloud-serverless/reference/client-libraries/flight-sql) to query data stored in an InfluxDB Cloud Serverless bucket.
InfluxDB v3 client libraries are language-specific packages that work with
and integrate with your application to write to and query data in {{% cloud-name %}}.
Functionality varies among client libraries.
These client libraries are in active development and may not be feature-complete.
InfluxDB client libraries provide configurable batch writing of data to InfluxDB HTTP APIs.
They can be used to construct line protocol data and transform data from other formats
to line protocol.
InfluxDB v3 client libraries can query InfluxDB v3 using the Arrow Flight protocol with gRPC.
Client libraries use Flight clients to execute SQL queries, request
bucket information, and retrieve data stored in {{% cloud-name %}}.
Additional functionality may vary among client libraries and some may not be feature-complete.
For specifics about a client library, see the library's GitHub repository.
InfluxDB v3 client libraries are part of the [Influx Community](https://github.com/InfluxCommunity).
{{< children depth="999" description="true" >}}

23
content/influxdb/cloud-serverless/reference/client-libraries/v3/go.md Normal file
View File

@ -0,0 +1,23 @@
---
title: Go client library for InfluxDB v3
list_title: Go
description: The InfluxDB v3 `influxdb3-go` Go client library integrates with Go scripts and applications to write and query data stored in an {{% cloud-name %}} bucket.
external_url: https://github.com/InfluxCommunity/influxdb3-go
menu:
influxdb_cloud_serverless:
name: Go
parent: v3 client libraries
identifier: influxdb3-go
influxdb/cloud-serverless/tags: [go, gRPC, SQL, Flight SQL, client libraries]
weight: 201
aliases:
- /influxdb/cloud-serverless/reference/api/client-libraries/go/
- /influxdb/cloud-serverless/tools/client-libraries/go/
---
The InfluxDB v3 [`influxdb3-go` Go client library](https://github.com/InfluxCommunity/influxdb3-go) integrates with Go scripts and applications
to write and query data stored in an {{% cloud-name %}} database.
The documentation for this client library is available on GitHub.
<a href="https://github.com/InfluxCommunity/influxdb3-go" target="_blank" class="btn github">InfluxDB v3 Go client library</a>

486
content/influxdb/cloud-serverless/reference/client-libraries/v3/python.md
View File

@ -8,17 +8,491 @@ menu:
name: Python
parent: v3 client libraries
identifier: influxdb3-python
params:
url: https://github.com/InfluxCommunity/influxdb3-python
weight: 201
influxdb/cloud-serverless/tags: [python, gRPC, SQL, Flight SQL, client libraries]
aliases:
- /influxdb/cloud-serverless/reference/client-libraries/v3/pyinflux3/
---
The InfluxDB v3 [`influxdb3-python` Python client library](https://github.com/InfluxCommunity/influxdb3-python) integrates with Python scripts and applications
to write and query data stored in an {{% cloud-name %}} bucket.
The InfluxDB v3 [`influxdb3-python` Python client library](https://github.com/InfluxCommunity/influxdb3-python)
integrates {{% cloud-name %}} write and query operations with Python scripts and applications.
The documentation for this client library is available on GitHub.
InfluxDB client libraries provide configurable batch writing of data to {{% cloud-name %}}.
Client libraries can be used to construct line protocol data, transform data from other formats
to line protocol, and batch write line protocol data to InfluxDB HTTP APIs.
<a href="https://github.com/InfluxCommunity/influxdb3-python" target="_blank" class="btn github">InfluxDB v3 Python client library</a>
InfluxDB v3 client libraries can query {{% cloud-name %}} using SQL.
The `influxdb3-python` Python client library wraps the Apache Arrow `pyarrow.flight` client
in a convenient InfluxDB v3 interface for executing SQL queries, requesting
server metadata, and retrieving data from {{% cloud-name %}} using the Flight protocol with gRPC.
## Installation
Install the client library and dependencies using `pip`:
```bash
pip install influxdb3-python
```
## Importing the module
The `influxdb3-python` client library package provides the `influxdb_client_3`
module.
Import the module:
```py
import influxdb_client_3
```
Import specific class methods from the module:
```py
from influxdb_client_3 import InfluxDBClient3, Point, WriteOptions
```
- [`influxdb_client_3.InfluxDBClient3` class](#class-influxdbclient3): an interface for [initializing
a client](#initialization) and interacting with InfluxDB
- `influxdb_client_3.Point` class: an interface for constructing a time series data
point
- `influxdb_client_3.WriteOptions` class: an interface for configuring
write options `influxdb_client_3.InfluxDBClient3` for the client.
## API reference
The `influxdb_client_3` module includes the following classes and functions.
<!-- TOC -->
- [Classes](#classes)
- [Functions](#functions)
- [Constants](#constants)
- [Exceptions](#exceptions)
## Classes
- [Class InfluxDBClient3](#class-influxdbclient3)
- [InfluxDBClient3.write](#influxdbclient3write)
- [InfluxDBClient3.write_file](#influxdbclient3write_file)
- [InfluxDBClient3.query](#influxdbclient3query)
- [InfluxDBClient3.close](#influxdbclient3close)
- [Class Point](#class-point)
- [Class WriteOptions](#class-writeoptions)
## Class InfluxDBClient3
Provides an interface for interacting with InfluxDB APIs for writing and querying data.
### Syntax
```py
__init__(self, host=None, org=None, database=None, token=None,
_write_client_options=None, _flight_client_options=None, **kwargs)
```
Initializes and returns an `InfluxDBClient3` instance with the following:
- A singleton _write client_ configured for writing to the database.
- A singleton _Flight client_ configured for querying the database.
### Attributes
- **org** (str): The organization name (for {{% cloud-name %}}, set this to an empty string (`""`)).
- **database** (str): The database to use for writing and querying.
- **_write_client_options** (dict): Options to use when writing to InfluxDB.
If `None`, writes are [synchronous](#synchronous-writing).
- **_flight_client_options** (dict): Options to use when querying InfluxDB.
#### Batch writing
In batching mode, the client adds the record or records to a batch, and then schedules the batch for writing to InfluxDB.
The client writes the batch to InfluxDB after reaching `_write_client_options.batch_size` or `_write_client_options.flush_interval`.
If a write fails, the client reschedules the write according to the `_write_client_options` retry options.
To use batching mode, pass an instance of `WriteOptions` for the `InfluxDBClient3._write_client_options` argument--for example:
1. Instantiate `WriteOptions()` with defaults or with
`WriteOptions.write_type=WriteType.batching`.
```py
# Batching with all batch size, flush, and retry defaults
write_options = WriteOptions()
```
2. Call the a `write_client_options` function to create an options object that uses `write_options` from the preceding step.
```py
wco = write_client_options(WriteOptions=write_options)
```
3. Initialize the client, setting the `_write_client_options` argument to the `wco` object from the preceding step.
{{< tabs-wrapper >}}
{{% code-placeholders "BUCKET_(NAME|TOKEN)|API_TOKEN" %}}
```py
with InfluxDBClient3(token="API_TOKEN", host="cloud2.influxdata.com",
org="", database="BUCKET_NAME",
_write_client_options=wco) as client:
client.write(record=points)
```
{{% /code-placeholders %}}
{{< /tabs-wrapper >}}
#### Synchronous writing
In synchronous mode, the client sends write requests immediately (not batched)
and doesn't retry failed writes.
To use synchronous mode, set `_write_client_options=None` or `_write_client_options.write_type=WriteType.synchronous`.
### Examples
##### Initialize a client
The following example initializes a client for writing and querying the bucket.
Given `_write_client_options=None`, the client will use synchronous mode when writing data.
{{% code-placeholders "BUCKET_(NAME|TOKEN)|API_TOKEN" %}}
```py
client = InfluxDBClient3(token="API_TOKEN",
host="cloud2.influxdata.com",
org="",
database="BUCKET_NAME")
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}:
Your InfluxDB token with READ permissions on the databases you want to query.
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}:
The name of your InfluxDB database.
##### Initialize a client for batch writing
The following example shows how to initialize a client for writing and querying the database.
When writing data, the client will use batch mode with default options and will
invoke the callback function for the response.
{{% code-placeholders "BUCKET_NAME|API_TOKEN" %}}
```py
import influxdb_client_3 as InfluxDBClient3
from influxdb_client_3 import write_client_options, WriteOptions, InfluxDBError
points = [Point("home").tag("room", "Kitchen").field("temp", 25.3),
Point("home").tag("room", "Living Room").field("temp", 18.4)]
# Define callbacks for write responses
def success(self, conf: (str, str, str)):
"""BATCH WRITE SUCCESS."""
print(f"Wrote batch: {conf}")
def error(self, conf: (str, str, str), exception: InfluxDBError):
"""BATCH WRITE FAILURE."""
print(f"Cannot write batch: {conf}, due to: {exception}")
def retry(self, conf: (str, str, str), exception: InfluxDBError):
"""BATCH WRITE RETRY"""
print(f"Retryable error occurs for batch: {conf}, retry: {exception}")
# Instantiate WriteOptions for batching
write_options = WriteOptions()
wco = write_client_options(success_callback=success,
error_callback=error,
retry_callback=retry,
WriteOptions=write_options)
with InfluxDBClient3(token="API_TOKEN", host="cloud2.influxdata.com",
org="ignored", database="BUCKET_NAME",
_write_client_options=wco) as client:
client.write(record=points)
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}:
Your InfluxDB token with READ permissions on the databases you want to query.
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}:
The name of your InfluxDB database.
### Instance methods
<!-- TOC -->
- [InfluxDBClient3.write](#influxdbclient3write)
- [InfluxDBClient3.write_file](#influxdbclient3write_file)
- [InfluxDBClient3.query](#influxdbclient3query)
- [InfluxDBClient3.close](#influxdbclient3close)
### InfluxDBClient3.write
Writes a record or a list of records to InfluxDB.
A record can be a `Point` object, a dict that represents a point, a line protocol string, or a `DataFrame`.
The client can write using [_batching_ mode](#batch-writing) or [_synchronous_ mode](#synchronous-writing).
##### Attributes
- **`write_precision=`**: `"ms"`, `"s"`, `"us"`, `"ns"`. Default is `"ns"`.
#### Syntax
```py
write(self, record=None, **kwargs)
```
#### Examples
##### Write a line protocol string
{{% influxdb/custom-timestamps %}}
{{% code-placeholders "BUCKET_NAME|API_TOKEN" %}}
```py
points = "home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000"
client = InfluxDBClient3(token="API_TOKEN", host="cloud2.influxdata.com",
database="BUCKET_NAME", org="ignored")
client.write(record=points, write_precision="s")
```
{{% /code-placeholders %}}
{{% /influxdb/custom-timestamps %}}
##### Write data using points
The `influxdb_client_3.Point` class provides an interface for constructing a data
point for a measurement and setting fields, tags, and the timestamp for the point.
The following example shows how to create a `Point` object, and then write the
data to InfluxDB.
```py
point = Point("home").tag("room", "Kitchen").field("temp", 72)
client.write(point)
```
###### Write data using a dict
`InfluxDBClient3` can serialize a dictionary object into line protocol.
If you pass a `dict` to `InfluxDBClient3.write`, the client expects the `dict` to have the
following _point_ data structure:
- **measurement** (str): the measurement name
- **tags** (dict): a dictionary of tag key-value pairs
- **fields** (dict): a dictionary of field key-value pairs
- **time**: the [timestamp](/influxdb/cloud-dedicated/reference/glossary/#timestamp) for the record
The following example shows how to define a `dict` that represents a point, and then write the
data to InfluxDB.
{{% influxdb/custom-timestamps %}}
{{% code-placeholders "BUCKET_NAME|API_TOKEN" %}}
```py
# Using point dictionary structure
points = {
"measurement": "home",
"tags": {"room": "Kitchen", "sensor": "K001"},
"fields": {"temp": 72.2, "hum": 36.9, "co": 4},
"time": 1641067200
}
client = InfluxDBClient3(token="API_TOKEN",
host="cloud2.influxdata.com",
database="BUCKET_NAME",
org="")
client.write(record=points, write_precision="s")
```
{{% /code-placeholders %}}
{{% /influxdb/custom-timestamps %}}
### InfluxDBClient3.write_file
Writes data from a file to InfluxDB.
The client can write using [_batching_ mode](#batch-writing) or [_synchronous_ mode](#synchronous-writing).
#### Syntax
```py
write_file(self, file, measurement_name=None, tag_columns=[],
timestamp_column='time', **kwargs)
```
##### Attributes
- **`file`**: A file containing records to write to InfluxDB.
The following file formats and file name extensions are supported.
The file name must end with one of the supported extensions.
For more information about encoding and formatting data, see the documentation for each supported format.
| Supported format | File name extension |
|:---------------------------------------------------------------------------|:--------------------|
| [Feather](https://arrow.apache.org/docs/python/feather.html) | `.feather` |
| [Parquet](https://arrow.apache.org/docs/python/parquet.html) | `.parquet` |
| [Comma-separated values](https://arrow.apache.org/docs/python/csv.html) | `.csv` |
| [JSON](https://pandas.pydata.org/docs/reference/api/pandas.read_json.html) | `.json` |
| [ORC](https://arrow.apache.org/docs/python/orc.html) | `.orc` |
- **`measurement_name`**: Defines the measurement name for records in the file.
The specified value takes precedence over `measurement` and `iox::measurement` columns in the file.
If no value is specified for the parameter, and a `measurement` column exists in the file, the `measurement` column value is used for the measurement name.
If no value is specified for the parameter, and no `measurement` column exists, the `iox::measurement` column value is used for the measurement name.
- **`tag_columns`**: A list containing the names of tag columns.
Columns not included in the list and not specified by another parameter are assumed to be fields.
- **`timestamp_column`**: The name of the column that contains timestamps. Default is `'time'`.
#### Examples
##### Write data from a file
The following example shows how to configure write options for batching, retries, and callbacks,
and how to write data from CSV and JSON files to InfluxDB:
{{% code-placeholders "BUCKET_NAME|API_TOKEN" %}}
```py
from influxdb_client_3 import InfluxDBClient3, write_client_options,
WritePrecision, WriteOptions, InfluxDBError
class BatchingCallback(object):
# Define callbacks for write responses
def success(self, conf: (str, str, str)):
"""BATCH WRITE SUCCESS."""
print(f"Wrote batch: {conf}")
def error(self, conf: (str, str, str), exception: InfluxDBError):
"""BATCH WRITE FAILURE."""
print(f"Cannot write batch: {conf}, due to: {exception}")
def retry(self, conf: (str, str, str), exception: InfluxDBError):
"""BATCH WRITE RETRY"""
print(f"Retryable error occurs for batch: {conf}, retry: {exception}")
# Instantiate the callbacks
callback = BatchingCallback()
write_options = WriteOptions(batch_size=500,
flush_interval=10_000,
jitter_interval=2_000,
retry_interval=5_000,
max_retries=5,
max_retry_delay=30_000,
exponential_base=2)
wco = write_client_options(success_callback=callback.success,
error_callback=callback.error,
retry_callback=callback.retry,
WriteOptions=write_options
)
with InfluxDBClient3(token="API_TOKEN", host="cloud2.influxdata.com",
org="", database="BUCKET_NAME",
_write_client_options=wco) as client:
client.write_file(file='./out.csv', timestamp_column='time',
tag_columns=["provider", "machineID"])
client.write_file(file='./out.json', timestamp_column='time',
tag_columns=["provider", "machineID"], date_unit='ns')
```
{{% /code-placeholders %}}
### InfluxDBClient3.query
Sends a Flight request to execute the specified SQL or InfluxQL query.
Returns all data in the query result as an Arrow table.
#### Syntax
```py
query(self, query, language="sql")
```
#### Examples
##### Query using SQL
```py
query = "select * from measurement"
reader = client.query(query=query, language="sql")
table = reader.read_all()
print(table.to_pandas().to_markdown())
```
##### Query using InfluxQL
```py
query = "select * from measurement"
reader = client.query(query=query, language="influxql")
table = reader.read_all()
print(table.to_pandas().to_markdown())
```
### InfluxDBClient3.close
Sends all remaining records from the batch to InfluxDB,
and then closes the underlying write client and Flight client to release resources.
#### Syntax
```py
close(self)
```
#### Examples
```py
client.close()
```
## Class Point
```py
influxdb_client_3.Point
```
A timeseries data point.
## Class WriteOptions
```py
influxdb_client_3.WriteOptions
```
Options for configuring client behavior (batch size, retry, callbacks, etc.) when writing data to InfluxDB.
For client configuration examples, see [Initialize a client](#initialize-a-client).
### Syntax
```py
__init__(self, write_type: WriteType = WriteType.batching,
batch_size=1_000, flush_interval=1_000,
jitter_interval=0,
retry_interval=5_000,
max_retries=5,
max_retry_delay=125_000,
max_retry_time=180_000,
exponential_base=2,
max_close_wait=300_000,
write_scheduler=ThreadPoolScheduler(max_workers=1)) -> None:
```
## Functions
- `influxdb_client_3.write_client_options(**kwargs)`
Returns a dictionary of write client options.
- `influxdb_client_3.flight_client_options(**kwargs)`
Returns a dictionary of flight client options.
## Constants
- `influxdb_client_3.SYNCHRONOUS`: Represents synchronous write mode.
- `influxdb_client_3.WritePrecision`: Enum class representing write precision options.
## Exceptions
- `influxdb_client_3.InfluxDBError`: Exception raised for InfluxDB-related errors.

5
shared/text/api/cloud-dedicated/basic-auth.sh
View File

@ -2,10 +2,9 @@
# Use Basic authentication with a database token
# to query the InfluxDB v1 API
#######################################
# Use the --user option with `--user username:DATABASE_TOKEN` syntax
#######################################
curl --get "http://cluster-id.influxdb.io/query" \
curl --get "https://cluster-id.influxdb.io/query" \
--user "":"DATABASE_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM MEASUREMENT"

2
shared/text/api/cloud-dedicated/bearer-auth-v1-query.sh
View File

@ -1,5 +1,5 @@
########################################################
# Use Token authentication with a database token
# Use the Bearer authorization scheme with a database token
# to query the InfluxDB v1 API
########################################################

6
shared/text/api/cloud-dedicated/bearer-auth-v2-write.sh
View File

@ -1,8 +1,8 @@
########################################################
# Use the Bearer token authentication scheme with /api/v2/write
# Use the Bearer authorization scheme with /api/v2/write
# to write data.
########################################################
curl --post "https://cluster-id.influxdb.io/api/v2/write?bucket=DATABASE_NAME&precision=s" \
--header "Authorization: Bearer DATABASE_TOKEN" \
curl --post 'https://cluster-id.influxdb.io/api/v2/write?bucket=DATABASE_NAME&precision=s' \
--header 'Authorization: Bearer DATABASE_TOKEN' \
--data-binary 'home,room=kitchen temp=72 1463683075'

2
shared/text/api/cloud-dedicated/token-auth-v1-write.sh
View File

@ -1,5 +1,5 @@
########################################################
# Use the Bearer authorization scheme with v1 /write
# Use the Token authorization scheme with v1 /write
# to write data.
########################################################

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

@ -0,0 +1,11 @@
#######################################
# 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 Normal file
View File

@ -0,0 +1,10 @@
#######################################
# 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 Normal file
View File

@ -0,0 +1,9 @@
########################################################
# 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'