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
GitHub
parent
4df36bacc9
commit
1a20ccf5b3
|
|
@ -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>}}
|
||||||
|
|
@ -2,25 +2,30 @@
|
||||||
title: Use the InfluxDB v1 API with InfluxDB Cloud Dedicated
|
title: Use the InfluxDB v1 API with InfluxDB Cloud Dedicated
|
||||||
list_title: Use the InfluxDB v1 API
|
list_title: Use the InfluxDB v1 API
|
||||||
description: >
|
description: >
|
||||||
Use InfluxDB v1 API authentication, endpoints, and tools.
|
Use InfluxDB v1 API authentication, endpoints, and tools when bringing existing 1.x workloads to InfluxDB Cloud Dedicated.
|
||||||
Learn how to use InfluxDB Cloud Dedicated v1 `/query`, `/write`, and username/password authentication when bringing existing 1.x workloads.
|
|
||||||
weight: 3
|
weight: 3
|
||||||
menu:
|
menu:
|
||||||
influxdb_cloud_dedicated:
|
influxdb_cloud_dedicated:
|
||||||
parent: API primers
|
parent: API compatibility
|
||||||
name: v1 API primer
|
name: v1 API
|
||||||
|
aliases:
|
||||||
|
- /influxdb/cloud-dedicated/primers/api/v1/
|
||||||
influxdb/cloud-dedicated/tags: [write, line protocol]
|
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.
|
Use the InfluxDB v1 API `/write` and `/query` endpoints with v1 workloads that you bring to {{% cloud-name %}}.
|
||||||
InfluxDB Cloud Dedicated v1 `/write` and `/query` endpoints work with username/password authentication and existing InfluxDB 1.x tools and code.
|
The v1 endpoints work with username/password authentication and existing InfluxDB 1.x tools and code.
|
||||||
The InfluxDB v1 API `/write` endpoint works with
|
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).
|
||||||
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).
|
The InfluxDB v1 API `/query` endpoint supports InfluxQL and third-party integrations like [Grafana](https://grafana.com).
|
||||||
|
|
||||||
{{% 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.
|
||||||
{{% api/cloud/v2-prefer %}}
|
|
||||||
{{% /warn %}}
|
|
||||||
|
|
||||||
<!-- TOC -->
|
<!-- TOC -->
|
||||||
|
|
||||||
|
|
@ -37,35 +42,30 @@ The InfluxDB v1 API `/query` endpoint supports InfluxQL and third-party integrat
|
||||||
- [Examples](#examples)
|
- [Examples](#examples)
|
||||||
- [Responses](#responses)
|
- [Responses](#responses)
|
||||||
- [Error examples](#error-examples)
|
- [Error examples](#error-examples)
|
||||||
- [Write data with the v1 API](#write-data-with-the-v1-api)
|
- [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)
|
|
||||||
- [v1 API /write parameters](#v1-api-write-parameters)
|
- [v1 API /write parameters](#v1-api-write-parameters)
|
||||||
- [Timestamp precision](#timestamp-precision)
|
- [Timestamp precision](#timestamp-precision)
|
||||||
- [Use clients for interactive testing](#use-clients-for-interactive-testing)
|
- [Tools for writing to the v1 API](#tools-for-writing-to-the-v1-api)
|
||||||
- [v1 CLI not supported](#v1-cli-not-supported)
|
- [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 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)
|
- [Timestamp precision](#timestamp-precision)
|
||||||
- [Query using HTTP clients](#query-using-http-clients)
|
- [Query data](#query-data)
|
||||||
- [Query using Flight SQL](#query-using-flight-sql)
|
- [Tools to execute queries](#tools-to-execute-queries)
|
||||||
- [Database management with InfluxQL not supported](#database-management-with-influxql-not-supported)
|
- [Database management with InfluxQL not supported](#database-management-with-influxql-not-supported)
|
||||||
|
|
||||||
<!-- /TOC -->
|
<!-- /TOC -->
|
||||||
<!--
|
|
||||||
<a class="btn" href="/influxdb/cloud-dedicated/api/v1/">View v1 API reference documentation</a>
|
|
||||||
-->
|
|
||||||
|
|
||||||
## Authenticate API requests
|
## 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/).
|
[database token](/influxdb/cloud-dedicated/admin/tokens/).
|
||||||
With the InfluxDB v1 API, you can use database tokens in InfluxDB 1.x username and password
|
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.
|
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 username and password scheme](#authenticate-with-a-username-and-password-scheme)
|
||||||
- [Authenticate with a token scheme](#authenticate-with-a-token)
|
- [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
|
### Authenticate with a username and password scheme
|
||||||
|
|
||||||
With the InfluxDB v1 API, you can use the InfluxDB 1.x convention of
|
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
|
username and password to authenticate database reads and writes by passing a [database token](/influxdb/cloud-dedicated/admin/tokens/) as the `password` credential.
|
||||||
[database token](/influxdb/cloud-dedicated/admin/tokens/)
|
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/).
|
||||||
as the `password` credential.
|
{{% cloud-name %}} ignores the `username` (`u`) parameter in the request.
|
||||||
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.
|
|
||||||
|
|
||||||
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)):
|
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
|
#### Basic authentication
|
||||||
|
|
||||||
Use the `Authorization` header with the `Basic` scheme to authenticate v1 API `/write` and `/query` requests.
|
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/).
|
When authenticating requests, {{% cloud-name %}} 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.
|
{{% cloud-name %}} ignores the `username` part of the decoded credential.
|
||||||
|
|
||||||
##### Syntax
|
##### Syntax
|
||||||
|
|
||||||
|
|
@ -96,11 +94,7 @@ InfluxDB Cloud Dedicated ignores the `username` part of the decoded credential.
|
||||||
Authorization: Basic <base64-encoded [USERNAME]:DATABASE_TOKEN>
|
Authorization: Basic <base64-encoded [USERNAME]:DATABASE_TOKEN>
|
||||||
```
|
```
|
||||||
|
|
||||||
Replace the following:
|
Encode the `[USERNAME]:DATABASE_TOKEN` credential using base64 encoding, and then append the encoded string to the `Authorization: Basic` header.
|
||||||
|
|
||||||
- **`[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.
|
|
||||||
|
|
||||||
{{% api/v1-compat/basic-auth-syntax %}}
|
{{% 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/):
|
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
|
```sh
|
||||||
{{% get-shared-text "api/cloud-dedicated/basic-auth.sh" %}}
|
{{% get-shared-text "api/cloud-dedicated/basic-auth.sh" %}}
|
||||||
```
|
```
|
||||||
|
{{% /code-placeholders %}}
|
||||||
|
|
||||||
Replace the following:
|
Replace the following:
|
||||||
|
|
||||||
- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database
|
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
|
||||||
- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the 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
|
#### Query string authentication
|
||||||
|
|
||||||
In the URL, pass the `p` query parameter to authenticate `/write` and `/query` requests.
|
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
|
##### 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/).
|
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
|
```sh
|
||||||
{{% get-shared-text "api/cloud-dedicated/querystring-auth.sh" %}}
|
{{% get-shared-text "api/cloud-dedicated/querystring-auth.sh" %}}
|
||||||
```
|
```
|
||||||
|
{{% /code-placeholders %}}
|
||||||
|
|
||||||
Replace the following:
|
Replace the following:
|
||||||
|
|
||||||
- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database
|
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
|
||||||
- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the 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
|
### 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
|
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.
|
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.
|
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).
|
`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.
|
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:
|
Use `Bearer` to authenticate a write request:
|
||||||
|
|
||||||
|
{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}
|
||||||
```sh
|
```sh
|
||||||
{{% get-shared-text "api/cloud-dedicated/bearer-auth-v1-write.sh" %}}
|
{{% get-shared-text "api/cloud-dedicated/bearer-auth-v1-write.sh" %}}
|
||||||
```
|
```
|
||||||
|
{{% /code-placeholders %}}
|
||||||
|
|
||||||
Use `Token` to authenticate a write request:
|
Use `Token` to authenticate a write request:
|
||||||
|
|
||||||
|
{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}
|
||||||
```sh
|
```sh
|
||||||
{{% get-shared-text "api/cloud-dedicated/token-auth-v1-write.sh" %}}
|
{{% get-shared-text "api/cloud-dedicated/token-auth-v1-write.sh" %}}
|
||||||
```
|
```
|
||||||
|
{{% /code-placeholders %}}
|
||||||
|
|
||||||
Replace the following:
|
Replace the following:
|
||||||
|
|
||||||
- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database
|
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
|
||||||
- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database
|
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database
|
||||||
|
|
||||||
## Responses
|
## Responses
|
||||||
|
|
||||||
InfluxDB API responses use standard HTTP status codes.
|
InfluxDB API responses use standard HTTP status codes.
|
||||||
For successful writes, InfluxDB responds with a `204 No Content` status code.
|
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.
|
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
|
### Error examples
|
||||||
|
|
||||||
|
|
@ -197,7 +199,9 @@ Response body messages may differ across InfluxDB Cloud Dedicated v1 API, v2 API
|
||||||
```
|
```
|
||||||
|
|
||||||
```json
|
```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.
|
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
|
```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.
|
The `?precision=` parameter contains an unknown value.
|
||||||
Provide a [timestamp precision](#timestamp-precision).
|
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)
|
- [`/api/v2/write` parameters](#v1-api-write-parameters)
|
||||||
- [Write using client libraries](#write-using-client-libraries)
|
- [Tools for writing to the v1 API](#tools-for-writing-to-the-v1-api)
|
||||||
- [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).
|
|
||||||
|
|
||||||
#### v1 API /write parameters
|
#### v1 API /write parameters
|
||||||
|
|
||||||
|
For {{% cloud-name %}} v1 API `/write` requests, set parameters as listed in the following table:
|
||||||
|
|
||||||
Parameter | Allowed in | Ignored | Value
|
Parameter | Allowed in | Ignored | Value
|
||||||
-----------------------|--------------|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
-----------------------|--------------|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
||||||
`consistency` | Query string | Ignored | N/A
|
`consistency` | Query string | Ignored | N/A
|
||||||
|
|
@ -373,49 +260,167 @@ Use one of the following `precision` values in v1 API `/write` requests:
|
||||||
- `m`: minutes
|
- `m`: minutes
|
||||||
- `h`: hours
|
- `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 %}}
|
- [Telegraf](#telegraf)
|
||||||
While the v1 CLI may coincidentally work with InfluxDB Cloud Dedicated, it isn't officially supported.
|
- [Interactive clients](#interactive-clients)
|
||||||
{{% /warn %}}
|
- [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
|
```sh
|
||||||
curl -i 'https://cluster-id.influxdb.io/write?db=DATABASE_NAME&precision=s' \
|
curl -i 'https://cluster-id.influxdb.io/write?db=DATABASE_NAME&precision=s' \
|
||||||
--header 'Authorization: Bearer DATABASE_TOKEN' \
|
--header 'Authorization: Bearer DATABASE_TOKEN' \
|
||||||
--header "Content-type: text/plain; charset=utf-8"
|
--header "Content-type: text/plain; charset=utf-8"
|
||||||
--data-binary 'home,room=kitchen temp=72 1463683075'
|
--data-binary 'home,room=kitchen temp=72 1463683075'
|
||||||
```
|
```
|
||||||
|
{{% /code-placeholders %}}
|
||||||
|
|
||||||
Replace the following:
|
Replace the following:
|
||||||
|
|
||||||
- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database
|
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database
|
||||||
- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the 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 %}}.
|
Don't use the v1 CLI with {{% cloud-name %}}.
|
||||||
While it may coincidentally work, it isn't officially supported.
|
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 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
|
- [Flight+gRPC](https://arrow.apache.org/docs/format/Flight.html) request that contains an SQL or InfluxQL query.
|
||||||
bring InfluxDB 1.x workloads that already use them.
|
- InfluxDB v1 API `/query` request that contains an InfluxQL query.
|
||||||
|
|
||||||
InfluxDB Cloud Dedicated
|
### v1 API /query parameters
|
||||||
|
|
||||||
{{% note %}}
|
For {{% cloud-name %}} v1 API `/query` requests, set parameters as listed in the following table:
|
||||||
For new workloads, see how to [query using Flight SQL](#query-using-flight-sql).
|
|
||||||
{{% /note %}}
|
|
||||||
|
|
||||||
#### v1 API /query parameters
|
|
||||||
|
|
||||||
Parameter | Allowed in | Ignored | Value
|
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
|
`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
|
`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
|
#### Timestamp precision
|
||||||
|
|
||||||
Use one of the following values for 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
|
- `m`: minutes
|
||||||
- `h`: hours
|
- `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.
|
#### Tools to execute queries
|
||||||
- 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).
|
|
||||||
|
|
||||||
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 >}}
|
- [`influx3` data CLI](https://github.com/InfluxCommunity/influxdb3-python-cli)
|
||||||
{{% code-tabs %}}
|
- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/)
|
||||||
[cURL](#curl)
|
- [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/)
|
||||||
[Python](#python)
|
- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/)
|
||||||
{{% /code-tabs %}}
|
- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/)
|
||||||
{{% code-tab-content %}}
|
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api)
|
||||||
<!-- Begin cURL -->
|
- [Chronograf](/{{< latest "Chronograf" >}}/)
|
||||||
```sh
|
|
||||||
{{% get-shared-text "api/cloud-dedicated/bearer-auth-v1-query.sh" %}}
|
|
||||||
```
|
|
||||||
|
|
||||||
```sh
|
{{% /note %}}
|
||||||
{{% 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
|
|
||||||
|
|
||||||
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)
|
### 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:
|
You can't use the following InfluxQL commands:
|
||||||
|
|
||||||
```sql
|
```sql
|
||||||
|
|
@ -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 %}}.
|
||||||
|
|
||||||
|
|
@ -46,6 +46,7 @@ The examples in this section of the tutorial query the
|
||||||
|
|
||||||
{{< req type="key" text="Covered in this tutorial" color="magenta" >}}
|
{{< 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 "\* " >}}
|
- [Flight SQL clients](?t=Go#execute-an-sql-query){{< req "\* " >}}
|
||||||
- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/)
|
- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/)
|
||||||
- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/)
|
- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/)
|
||||||
|
|
|
||||||
|
|
@ -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 provides many different options for ingesting or writing data, including the following:
|
||||||
|
|
||||||
- InfluxDB HTTP API (v1 and v2)
|
- InfluxDB HTTP API (v1 and v2)
|
||||||
- `influx` CLI (v1 and v2)
|
|
||||||
- Telegraf
|
- Telegraf
|
||||||
|
- `influx3` data CLI
|
||||||
- InfluxDB client libraries
|
- InfluxDB client libraries
|
||||||
|
|
||||||
If using tools like Telegraf or InfluxDB client libraries, they can
|
If using tools like Telegraf or InfluxDB client libraries, they can
|
||||||
|
|
|
||||||
|
|
@ -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 %}}
|
|
||||||
|
|
@ -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>}}
|
|
||||||
|
|
@ -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).
|
|
||||||
|
|
@ -9,12 +9,36 @@ menu:
|
||||||
name: Flight SQL clients
|
name: Flight SQL clients
|
||||||
parent: Client libraries
|
parent: Client libraries
|
||||||
influxdb/cloud-dedicated/tags: [Golang, Python, client libraries, Flight SQL]
|
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.
|
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 SQL.
|
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.
|
||||||
Some [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3) include Flight SQL clients.
|
|
||||||
|
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" >}}
|
|
||||||
|
|
|
||||||
|
|
@ -24,11 +24,12 @@ For specifics about a client library, see the library's GitHub repository.
|
||||||
### Tools to execute queries
|
### Tools to execute queries
|
||||||
|
|
||||||
InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint.
|
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/)
|
- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/)
|
||||||
- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/)
|
- [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)
|
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api)
|
||||||
|
|
|
||||||
|
|
@ -1,21 +1,27 @@
|
||||||
---
|
---
|
||||||
title: Go client library
|
title: InfluxDB v2 Go client library
|
||||||
seotitle: Use the InfluxDB Go client library
|
|
||||||
list_title: Go
|
list_title: Go
|
||||||
description: >
|
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:
|
menu:
|
||||||
influxdb_cloud_dedicated:
|
influxdb_cloud_dedicated:
|
||||||
name: Go
|
name: Go
|
||||||
parent: v2 client libraries
|
parent: v2 client libraries
|
||||||
influxdb/cloud-dedicated/tags: [client libraries, Go]
|
influxdb/cloud-dedicated/tags: [client libraries, Go]
|
||||||
weight: 201
|
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.
|
This guide presumes some familiarity with Go and InfluxDB.
|
||||||
If just getting started, see [Get started with InfluxDB](/influxdb/cloud-dedicated/get-started/).
|
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
|
go get github.com/influxdata/influxdb-client-go/v2
|
||||||
```
|
```
|
||||||
3. Ensure that InfluxDB is running and you can connect to it.
|
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
|
## 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/).
|
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
|
```go
|
||||||
bucket := "example-database"
|
bucket := "DATABASE_NAME"
|
||||||
org := "ignored"
|
org := "ignored"
|
||||||
token := "example-token"
|
token := "DATABASE_TOKEN"
|
||||||
// Store the URL of your InfluxDB instance
|
// Store the URL of your InfluxDB instance
|
||||||
url := "https://cluster-id.influxdb.io"
|
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)
|
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
|
## Write data to InfluxDB with Go
|
||||||
|
|
||||||
Use the Go library to write data to InfluxDB.
|
Use the Go library to write data to InfluxDB.
|
||||||
|
|
@ -109,9 +109,9 @@ import (
|
||||||
)
|
)
|
||||||
|
|
||||||
func main() {
|
func main() {
|
||||||
bucket := "example-database"
|
bucket := "DATABASE_NAME"
|
||||||
org := "ignored"
|
org := "ignored"
|
||||||
token := "example-token"
|
token := "DATABASE_TOKEN"
|
||||||
// Store the URL of your InfluxDB instance
|
// Store the URL of your InfluxDB instance
|
||||||
url := "https://cluster-id.influxdb.io"
|
url := "https://cluster-id.influxdb.io"
|
||||||
// Create new client with default option for server url authenticate by token
|
// Create new client with default option for server url authenticate by token
|
||||||
|
|
@ -129,10 +129,3 @@ func main() {
|
||||||
client.Close()
|
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).
|
|
||||||
|
|
|
||||||
|
|
@ -1,10 +1,10 @@
|
||||||
---
|
---
|
||||||
title: JavaScript client library for the InfluxDB v2 API
|
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
|
list_title: JavaScript
|
||||||
description: >
|
description: >
|
||||||
Use the [InfluxDB v2 JavaScript client library](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 to write data to a InfluxDB Cloud Dedicated cluster.
|
for Node.js and browsers integrates with the InfluxDB v2 API to write data to an InfluxDB Cloud Dedicated cluster.
|
||||||
menu:
|
menu:
|
||||||
influxdb_cloud_dedicated:
|
influxdb_cloud_dedicated:
|
||||||
name: JavaScript
|
name: JavaScript
|
||||||
|
|
@ -15,7 +15,25 @@ aliases:
|
||||||
- /influxdb/cloud-dedicated/reference/api/client-libraries/js/
|
- /influxdb/cloud-dedicated/reference/api/client-libraries/js/
|
||||||
---
|
---
|
||||||
|
|
||||||
Use the [InfluxDB v2 JavaScript client library](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 to write data to a InfluxDB Cloud Dedicated cluster.
|
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" >}}
|
||||||
|
|
|
||||||
|
|
@ -1,9 +1,8 @@
|
||||||
---
|
---
|
||||||
title: JavaScript client library for web browsers
|
title: InfluxDB v2 JavaScript client library for web browsers
|
||||||
seotitle: Use the InfluxDB v2 JavaScript client library for web browsers
|
|
||||||
list_title: JavaScript for browsers
|
list_title: JavaScript for browsers
|
||||||
description: >
|
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:
|
menu:
|
||||||
influxdb_cloud_dedicated:
|
influxdb_cloud_dedicated:
|
||||||
name: Browsers and web clients
|
name: Browsers and web clients
|
||||||
|
|
@ -19,23 +18,19 @@ related:
|
||||||
- /influxdb/cloud-dedicated/api-guide/client-libraries/nodejs/query/
|
- /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:
|
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.
|
||||||
* 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/).
|
|
||||||
|
|
||||||
{{% note %}}
|
{{% note %}}
|
||||||
|
|
||||||
### Tools to execute queries
|
### Tools to execute queries
|
||||||
|
|
||||||
InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint.
|
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/)
|
- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/)
|
||||||
- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/)
|
- [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)
|
- [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 %}}
|
{{% /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 %}}
|
{{% warn %}}
|
||||||
### Tokens in production applications
|
### Tokens in production applications
|
||||||
{{% api/browser-token-warning %}}
|
{{% 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.
|
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.
|
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
|
## Use with module bundlers
|
||||||
|
|
||||||
|
|
@ -121,7 +126,7 @@ The client library includes an example browser app that writes to your InfluxDB
|
||||||
cd examples
|
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]()
|
4. Run the following command to start the application at [http://localhost:3001/examples/index.html]()
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,9 +1,10 @@
|
||||||
---
|
---
|
||||||
title: Node.js JavaScript client library
|
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
|
list_title: Node.js
|
||||||
description: >
|
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:
|
menu:
|
||||||
influxdb_cloud_dedicated:
|
influxdb_cloud_dedicated:
|
||||||
name: Node.js
|
name: Node.js
|
||||||
|
|
@ -14,26 +15,27 @@ aliases:
|
||||||
- /influxdb/cloud-dedicated/reference/api/client-libraries/nodejs/
|
- /influxdb/cloud-dedicated/reference/api/client-libraries/nodejs/
|
||||||
---
|
---
|
||||||
|
|
||||||
Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js)
|
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.
|
integrates with the InfluxDB v2 API to write data from Node.js and browser applications to an {{% cloud-name %}} database.
|
||||||
|
|
||||||
## Use the client library in a Node.js application
|
|
||||||
|
|
||||||
{{< children >}}
|
|
||||||
|
|
||||||
{{% note %}}
|
{{% note %}}
|
||||||
|
|
||||||
### Tools to execute queries
|
### Tools to execute queries
|
||||||
|
|
||||||
InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint.
|
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/)
|
- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/)
|
||||||
- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/)
|
- [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)
|
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api)
|
||||||
- [Chronograf](/{{< latest "Chronograf" >}}/)
|
- [Chronograf](/{{< latest "Chronograf" >}}/)
|
||||||
|
|
||||||
{{% /note %}}
|
{{% /note %}}
|
||||||
|
|
||||||
|
## Use the client library in a Node.js application
|
||||||
|
|
||||||
|
{{< children >}}
|
||||||
|
|
|
||||||
|
|
@ -1,35 +1,61 @@
|
||||||
---
|
---
|
||||||
title: Install the InfluxDB v2 JavaScript client library
|
title: Install the InfluxDB v2 JavaScript client library
|
||||||
seotitle: Install the InfluxDB Node.js JavaScript client library
|
|
||||||
description: >
|
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:
|
menu:
|
||||||
influxdb_cloud_dedicated:
|
influxdb_cloud_dedicated:
|
||||||
name: Install
|
name: Install
|
||||||
parent: Node.js
|
parent: Node.js
|
||||||
influxdb/cloud-dedicated/tags: [client libraries, JavaScript]
|
influxdb/cloud-serverless/tags: [client libraries, JavaScript]
|
||||||
weight: 100
|
weight: 100
|
||||||
aliases:
|
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
|
## Install Node.js
|
||||||
|
|
||||||
1. Install [Node.js](https://nodejs.org/en/download/package-manager/).
|
1. Install [Node.js](https://nodejs.org/en/download/package-manager/).
|
||||||
|
|
||||||
2. Ensure that InfluxDB is running and you can connect to it.
|
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.
|
3. In your terminal, create a directory for your Node.js project and change to it.
|
||||||
The `npm` package manager is included with Node.js.
|
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
npm init -y influx-node-app
|
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
|
## 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.
|
1. Install TypeScript and type definitions for Node.js.
|
||||||
|
|
||||||
|
|
@ -49,22 +75,23 @@ Many of the client library examples use [TypeScript](https://www.typescriptlang.
|
||||||
|
|
||||||
## Install dependencies
|
## 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
|
```sh
|
||||||
npm i --save @influxdata/influxdb-client
|
npm i --save @influxdata/influxdb-client
|
||||||
```
|
```
|
||||||
|
|
||||||
The `@influxdata/influxdb-client-apis` client library package doesn't
|
The `@influxdata/influxdb-client-apis` client library package won't work with {{% cloud-name %}}.
|
||||||
work with InfluxDB v3.
|
It only works with InfluxDB v2 management APIs.
|
||||||
It only works with InfluxDB v2 management APIs.
|
|
||||||
|
|
||||||
## Configure credentials
|
## Configure credentials
|
||||||
|
|
||||||
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 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.
|
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
|
```sh
|
||||||
export INFLUX_URL=https://cluster-id.influxdb.io
|
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
|
## 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 >}}
|
{{< page-nav next="/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/write/" keepTab=true >}}
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,7 @@
|
||||||
title: Write data with the InfluxDB v2 JavaScript client library
|
title: Write data with the InfluxDB v2 JavaScript client library
|
||||||
list_title: Write data
|
list_title: Write data
|
||||||
description: >
|
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:
|
menu:
|
||||||
influxdb_cloud_dedicated:
|
influxdb_cloud_dedicated:
|
||||||
name: Write
|
name: Write
|
||||||
|
|
@ -29,7 +29,7 @@ The Javascript client library includes the following convenient features for wri
|
||||||
|
|
||||||
### Write data with the client library
|
### 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
|
```js
|
||||||
import {InfluxDB, Point} from '@influxdata/influxdb-client'
|
import {InfluxDB, Point} from '@influxdata/influxdb-client'
|
||||||
|
|
|
||||||
|
|
@ -13,11 +13,20 @@ influxdb/cloud-dedicated/tags: [client libraries, API, developer tools]
|
||||||
|
|
||||||
## Client libraries for InfluxDB v3
|
## 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.
|
InfluxDB client libraries provide configurable batch writing of data to InfluxDB HTTP APIs.
|
||||||
These client libraries are in active development and may not be feature-complete.
|
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.
|
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" >}}
|
{{< children depth="999" description="true" >}}
|
||||||
|
|
|
||||||
|
|
@ -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>
|
||||||
|
|
@ -7,8 +7,6 @@ menu:
|
||||||
influxdb_cloud_dedicated:
|
influxdb_cloud_dedicated:
|
||||||
name: Python
|
name: Python
|
||||||
parent: v3 client libraries
|
parent: v3 client libraries
|
||||||
params:
|
|
||||||
url: https://github.com/InfluxCommunity/influxdb3-python
|
|
||||||
identifier: influxdb3-python
|
identifier: influxdb3-python
|
||||||
influxdb/cloud-dedicated/tags: [python, gRPC, SQL, Flight SQL, client libraries]
|
influxdb/cloud-dedicated/tags: [python, gRPC, SQL, Flight SQL, client libraries]
|
||||||
weight: 201
|
weight: 201
|
||||||
|
|
@ -16,9 +14,483 @@ aliases:
|
||||||
- /influxdb/cloud-dedicated/reference/client-libraries/v3/pyinflux3/
|
- /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
|
The InfluxDB v3 [`influxdb3-python` Python client library](https://github.com/InfluxCommunity/influxdb3-python)
|
||||||
to write and query data stored in an {{% cloud-name %}} database.
|
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.
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
---
|
---
|
||||||
title: Configure Telegraf for InfluxDB
|
title: Configure Telegraf for InfluxDB
|
||||||
seotitle: Configure Telegraf to write to InfluxDB
|
seotitle: Configure Telegraf to write data to InfluxDB
|
||||||
description: >
|
description: >
|
||||||
Telegraf is a plugin-based agent with plugins that are enabled and configured in
|
Telegraf is a plugin-based agent with plugins that are enabled and configured in
|
||||||
your Telegraf configuration file (`telegraf.conf`).
|
your Telegraf configuration file (`telegraf.conf`).
|
||||||
|
|
@ -41,6 +41,7 @@ for using Telegraf with {{< cloud-name >}}._
|
||||||
- [organization](#organization)
|
- [organization](#organization)
|
||||||
- [bucket](#bucket)
|
- [bucket](#bucket)
|
||||||
- [Write to InfluxDB v1.x and {{< cloud-name >}}](#write-to-influxdb-v1x-and--cloud-name-)
|
- [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)
|
- [Start Telegraf](#start-telegraf)
|
||||||
|
|
||||||
<!-- /TOC -->
|
<!-- /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.
|
enabling the InfluxDB v2 output plugin will write data to both v1.x and your {{< cloud-name >}} cluster.
|
||||||
{{% /note %}}
|
{{% /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 Telegraf
|
||||||
|
|
||||||
Start the Telegraf service using the `--config` flag to specify the location of your `telegraf.conf`.
|
Start the Telegraf service using the `--config` flag to specify the location of your `telegraf.conf`.
|
||||||
|
|
|
||||||
|
|
@ -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>}}
|
||||||
|
|
@ -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
|
||||||
|
```
|
||||||
|
|
@ -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 %}}.
|
||||||
|
|
||||||
|
|
@ -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" >}}
|
{{< 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 "\* " >}}
|
- [InfluxDB user interface (UI)](?t=InfluxDB+UI#execute-an-sql-query){{< req "\* " >}}
|
||||||
- [`influx3` data CLI](?t=influx3+CLI#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 "\* " >}}
|
- [InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/)
|
||||||
- [`influx` CLI](?t=influx+CLI#execute-an-sql-query){{< req "\* " >}}
|
- [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/)
|
- [Superset](/influxdb/cloud-serverless/query-data/execute-queries/flight-sql/superset/)
|
||||||
- [Grafana](/influxdb/cloud-serverless/query-data/tools/grafana/)
|
- [Grafana](/influxdb/cloud-serverless/query-data/tools/grafana/)
|
||||||
- [Chronograf](/{{< latest "Chronograf" >}}/)
|
- [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
|
## SQL query basics
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,21 +1,28 @@
|
||||||
---
|
---
|
||||||
title: Go client library
|
title: InfluxDB v2 Go client library
|
||||||
seotitle: Use the InfluxDB Go client library
|
|
||||||
list_title: Go
|
list_title: Go
|
||||||
description: >
|
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:
|
menu:
|
||||||
influxdb_cloud_serverless:
|
influxdb_cloud_serverless:
|
||||||
name: Go
|
name: Go
|
||||||
parent: v2 client libraries
|
parent: v2 client libraries
|
||||||
influxdb/cloud-serverless/tags: [client libraries, Go]
|
influxdb/cloud-serverless/tags: [client libraries, Go]
|
||||||
weight: 201
|
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.
|
This guide presumes some familiarity with Go and InfluxDB.
|
||||||
If just getting started, see [Get started with InfluxDB](/influxdb/cloud-serverless/get-started/).
|
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
|
```go
|
||||||
bucket := "example-bucket"
|
bucket := "BUCKET_NAME"
|
||||||
org := "example-org"
|
org := "ignored"
|
||||||
token := "example-token"
|
token := "API_TOKEN"
|
||||||
// Store the URL of your InfluxDB instance
|
// Store the URL of your InfluxDB instance
|
||||||
url := "https://cloud2.influxdata.com"
|
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)
|
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
|
## Write data to InfluxDB with Go
|
||||||
|
|
||||||
Use the Go library to write data to InfluxDB.
|
Use the Go library to write data to InfluxDB.
|
||||||
|
|
@ -109,9 +111,9 @@ import (
|
||||||
)
|
)
|
||||||
|
|
||||||
func main() {
|
func main() {
|
||||||
bucket := "example-bucket"
|
bucket := "BUCKET_NAME"
|
||||||
org := "example-org"
|
org := "ignored"
|
||||||
token := "example-token"
|
token := "API_TOKEN"
|
||||||
// Store the URL of your InfluxDB instance
|
// Store the URL of your InfluxDB instance
|
||||||
url := "https://cloud2.influxdata.com"
|
url := "https://cloud2.influxdata.com"
|
||||||
// Create new client with default option for server url authenticate by token
|
// Create new client with default option for server url authenticate by token
|
||||||
|
|
|
||||||
|
|
@ -1,10 +1,10 @@
|
||||||
---
|
---
|
||||||
title: JavaScript client library for the InfluxDB v2 API
|
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
|
list_title: JavaScript
|
||||||
description: >
|
description: >
|
||||||
Use the InfluxDB v2 JavaScript client library to integrate with InfluxDB and the InfluxDB v2 API.
|
The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js)
|
||||||
external_url: 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:
|
menu:
|
||||||
influxdb_cloud_serverless:
|
influxdb_cloud_serverless:
|
||||||
name: JavaScript
|
name: JavaScript
|
||||||
|
|
@ -15,6 +15,25 @@ aliases:
|
||||||
- /influxdb/cloud-serverless/reference/api/client-libraries/js/
|
- /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">}}
|
{{< children type="list">}}
|
||||||
|
|
|
||||||
|
|
@ -1,9 +1,8 @@
|
||||||
---
|
---
|
||||||
title: JavaScript client library for web browsers
|
title: InfluxDB v2 JavaScript client library for web browsers
|
||||||
seotitle: Use the InfluxDB v2 JavaScript client library for web browsers
|
|
||||||
list_title: JavaScript for browsers
|
list_title: JavaScript for browsers
|
||||||
description: >
|
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:
|
menu:
|
||||||
influxdb_cloud_serverless:
|
influxdb_cloud_serverless:
|
||||||
name: Browsers and web clients
|
name: Browsers and web clients
|
||||||
|
|
@ -19,7 +18,27 @@ related:
|
||||||
- /influxdb/cloud-serverless/api-guide/client-libraries/nodejs/query/
|
- /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)
|
* ECMAScript modules (ESM) and CommonJS modules (CJS)
|
||||||
* Bundled ESM
|
* Bundled ESM
|
||||||
* Bundled UMD
|
* 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.
|
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.
|
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
|
## Use with module bundlers
|
||||||
|
|
||||||
If you use a module bundler like Webpack or Parcel, install `@influxdata/influxdb-client-browser`.
|
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
|
## Use bundled distributions with browsers and module loaders
|
||||||
|
|
||||||
|
|
@ -56,14 +73,14 @@ For more information and examples, see [Node.js](/{{% latest "influxdb" %}}/api-
|
||||||
```html
|
```html
|
||||||
<script>
|
<script>
|
||||||
window.INFLUX_ENV = {
|
window.INFLUX_ENV = {
|
||||||
url: 'http://localhost:8086',
|
url: 'https://cloud2.influxdata.com',
|
||||||
token: 'INFLUX_READ_WRITE_TOKEN'
|
token: 'API_TOKEN'
|
||||||
}
|
}
|
||||||
</script>
|
</script>
|
||||||
```
|
```
|
||||||
Replace the following:
|
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.
|
2. Import modules from the latest client library browser distribution.
|
||||||
`@influxdata/influxdb-client-browser` exports bundled ESM and UMD syntaxes.
|
`@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-tab-content %}}
|
||||||
{{< /code-tabs-wrapper >}}
|
{{< /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
|
## 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.
|
1. Clone the [influxdb-client-js](https://github.com/influxdata/influxdb-client-js) repo.
|
||||||
|
|
||||||
2. Navigate to the `examples` directory:
|
2. Navigate to the `examples` directory:
|
||||||
|
|
||||||
```js
|
```js
|
||||||
cd examples
|
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]()
|
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.
|
`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/).
|
||||||
|
|
|
||||||
|
|
@ -1,10 +1,10 @@
|
||||||
---
|
---
|
||||||
title: Node.js JavaScript client library
|
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
|
list_title: Node.js
|
||||||
description: >
|
description: >
|
||||||
Use the InfluxDB v2 JavaScript client library to integrate with InfluxDB.
|
The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js)
|
||||||
external_url: 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:
|
menu:
|
||||||
influxdb_cloud_serverless:
|
influxdb_cloud_serverless:
|
||||||
name: Node.js
|
name: Node.js
|
||||||
|
|
@ -12,11 +12,34 @@ menu:
|
||||||
influxdb/cloud-serverless/tags: [client libraries, JavaScript, NodeJS]
|
influxdb/cloud-serverless/tags: [client libraries, JavaScript, NodeJS]
|
||||||
weight: 201
|
weight: 201
|
||||||
aliases:
|
aliases:
|
||||||
- /influxdb/cloud-serverless/reference/api/client-libraries/nodejs/
|
- /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
|
## Use the client library in a Node.js application
|
||||||
|
|
||||||
{{< children type="list">}}
|
{{< children >}}
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,8 +1,7 @@
|
||||||
---
|
---
|
||||||
title: Install the InfluxDB v2 JavaScript client library
|
title: Install the InfluxDB v2 JavaScript client library
|
||||||
seotitle: Install the InfluxDB Node.js JavaScript client library
|
|
||||||
description: >
|
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:
|
menu:
|
||||||
influxdb_cloud_serverless:
|
influxdb_cloud_serverless:
|
||||||
name: Install
|
name: Install
|
||||||
|
|
@ -13,13 +12,32 @@ aliases:
|
||||||
- /influxdb/cloud-serverless/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 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
|
## Install Node.js
|
||||||
|
|
||||||
1. Install [Node.js](https://nodejs.org/en/download/package-manager/).
|
1. Install [Node.js](https://nodejs.org/en/download/package-manager/).
|
||||||
|
|
||||||
2. Ensure that InfluxDB is running and you can connect to it.
|
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.
|
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
|
## 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:
|
Open a new terminal window and install the `@influxdata/influxdb-client` package for querying and writing data:
|
||||||
|
|
||||||
```sh
|
```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.
|
It only works with InfluxDB v2 management APIs.
|
||||||
|
|
||||||
## Configure credentials
|
## Configure credentials
|
||||||
|
|
|
||||||
|
|
@ -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 >}}
|
|
||||||
|
|
@ -2,7 +2,7 @@
|
||||||
title: Write data with the InfluxDB v2 JavaScript client library
|
title: Write data with the InfluxDB v2 JavaScript client library
|
||||||
list_title: Write data
|
list_title: Write data
|
||||||
description: >
|
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:
|
menu:
|
||||||
influxdb_cloud_serverless:
|
influxdb_cloud_serverless:
|
||||||
name: Write
|
name: Write
|
||||||
|
|
@ -63,7 +63,7 @@ The Javascript client library includes the following convenient features for wri
|
||||||
```js
|
```js
|
||||||
const point1 = new Point('temperature')
|
const point1 = new Point('temperature')
|
||||||
.tag('sensor_id', 'TLM010')
|
.tag('sensor_id', 'TLM010')
|
||||||
.floatField('value', 24)
|
.floatField('value', 24.0)
|
||||||
```
|
```
|
||||||
|
|
||||||
5. Use the `writePoint()` method to write the point to your InfluxDB bucket.
|
5. Use the `writePoint()` method to write the point to your InfluxDB bucket.
|
||||||
|
|
|
||||||
|
|
@ -13,11 +13,20 @@ influxdb/cloud-serverless/tags: [client libraries, API, developer tools]
|
||||||
|
|
||||||
## Client libraries for InfluxDB v3
|
## 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.
|
InfluxDB client libraries provide configurable batch writing of data to InfluxDB HTTP APIs.
|
||||||
These client libraries are in active development and may not be feature-complete.
|
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.
|
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" >}}
|
{{< children depth="999" description="true" >}}
|
||||||
|
|
|
||||||
|
|
@ -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>
|
||||||
|
|
@ -8,17 +8,491 @@ menu:
|
||||||
name: Python
|
name: Python
|
||||||
parent: v3 client libraries
|
parent: v3 client libraries
|
||||||
identifier: influxdb3-python
|
identifier: influxdb3-python
|
||||||
params:
|
|
||||||
url: https://github.com/InfluxCommunity/influxdb3-python
|
|
||||||
weight: 201
|
weight: 201
|
||||||
influxdb/cloud-serverless/tags: [python, gRPC, SQL, Flight SQL, client libraries]
|
influxdb/cloud-serverless/tags: [python, gRPC, SQL, Flight SQL, client libraries]
|
||||||
aliases:
|
aliases:
|
||||||
- /influxdb/cloud-serverless/reference/client-libraries/v3/pyinflux3/
|
- /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
|
The InfluxDB v3 [`influxdb3-python` Python client library](https://github.com/InfluxCommunity/influxdb3-python)
|
||||||
to write and query data stored in an {{% cloud-name %}} bucket.
|
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.
|
||||||
|
|
|
||||||
|
|
@ -2,10 +2,9 @@
|
||||||
# Use Basic authentication with a database token
|
# Use Basic authentication with a database token
|
||||||
# to query the InfluxDB v1 API
|
# 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" \
|
--user "":"DATABASE_TOKEN" \
|
||||||
--data-urlencode "db=DATABASE_NAME" \
|
--data-urlencode "db=DATABASE_NAME" \
|
||||||
--data-urlencode "q=SELECT * FROM MEASUREMENT"
|
--data-urlencode "q=SELECT * FROM MEASUREMENT"
|
||||||
|
|
|
||||||
|
|
@ -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
|
# to query the InfluxDB v1 API
|
||||||
########################################################
|
########################################################
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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.
|
# to write data.
|
||||||
########################################################
|
########################################################
|
||||||
|
|
||||||
curl --post "https://cluster-id.influxdb.io/api/v2/write?bucket=DATABASE_NAME&precision=s" \
|
curl --post 'https://cluster-id.influxdb.io/api/v2/write?bucket=DATABASE_NAME&precision=s' \
|
||||||
--header "Authorization: Bearer DATABASE_TOKEN" \
|
--header 'Authorization: Bearer DATABASE_TOKEN' \
|
||||||
--data-binary 'home,room=kitchen temp=72 1463683075'
|
--data-binary 'home,room=kitchen temp=72 1463683075'
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
########################################################
|
########################################################
|
||||||
# Use the Bearer authorization scheme with v1 /write
|
# Use the Token authorization scheme with v1 /write
|
||||||
# to write data.
|
# to write data.
|
||||||
########################################################
|
########################################################
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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"
|
||||||
|
|
@ -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"
|
||||||
|
|
@ -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'
|
||||||
Loading…
Reference in New Issue