diff --git a/content/influxdb/cloud-dedicated/api-compatibility/_index.md b/content/influxdb/cloud-dedicated/api-compatibility/_index.md new file mode 100644 index 000000000..729233de5 --- /dev/null +++ b/content/influxdb/cloud-dedicated/api-compatibility/_index.md @@ -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>}} \ No newline at end of file diff --git a/content/influxdb/cloud-dedicated/primers/api/v1/_index.md b/content/influxdb/cloud-dedicated/api-compatibility/v1/_index.md similarity index 56% rename from content/influxdb/cloud-dedicated/primers/api/v1/_index.md rename to content/influxdb/cloud-dedicated/api-compatibility/v1/_index.md index a83715b4f..73e51d40c 100644 --- a/content/influxdb/cloud-dedicated/primers/api/v1/_index.md +++ b/content/influxdb/cloud-dedicated/api-compatibility/v1/_index.md @@ -2,25 +2,30 @@ title: Use the InfluxDB v1 API with InfluxDB Cloud Dedicated list_title: Use the InfluxDB v1 API description: > - Use InfluxDB v1 API authentication, endpoints, and tools. - Learn how to use InfluxDB Cloud Dedicated v1 `/query`, `/write`, and username/password authentication when bringing existing 1.x workloads. + Use InfluxDB v1 API authentication, endpoints, and tools when bringing existing 1.x workloads to InfluxDB Cloud Dedicated. weight: 3 menu: influxdb_cloud_dedicated: - parent: API primers - name: v1 API primer + parent: API compatibility + name: v1 API +aliases: + - /influxdb/cloud-dedicated/primers/api/v1/ influxdb/cloud-dedicated/tags: [write, line protocol] +related: + - /influxdb/cloud-dedicated/query-data/sql/ + - /influxdb/cloud-dedicated/query-data/influxql/ + - /influxdb/cloud-dedicated/write-data/ + - /influxdb/cloud-dedicated/write-data/use-telegraf/configure/ + - /influxdb/cloud-dedicated/reference/api/ + - /influxdb/cloud-dedicated/reference/client-libraries/ --- -Use the InfluxDB v1 API with v1 workloads that you bring to InfluxDB Cloud Dedicated. -InfluxDB Cloud Dedicated v1 `/write` and `/query` endpoints work with username/password authentication and existing InfluxDB 1.x tools and code. -The InfluxDB v1 API `/write` endpoint works with -InfluxDB 1.x client libraries and the [Telegraf v1 Output Plugin](/telegraf/v1.26/plugins/#output-influxdb). +Use the InfluxDB v1 API `/write` and `/query` endpoints with v1 workloads that you bring to {{% cloud-name %}}. +The v1 endpoints work with username/password authentication and existing InfluxDB 1.x tools and code. +The InfluxDB v1 API `/write` endpoint works with InfluxDB 1.x client libraries and the [Telegraf v1 Output Plugin](/telegraf/v1.26/plugins/#output-influxdb). The InfluxDB v1 API `/query` endpoint supports InfluxQL and third-party integrations like [Grafana](https://grafana.com). -{{% warn %}} -{{% api/cloud/v2-prefer %}} -{{% /warn %}} +Learn how to authenticate requests, adjust request parameters for existing v1 workloads, and find compatible tools for writing and querying data stored in an {{% cloud-name %}} database. @@ -37,35 +42,30 @@ The InfluxDB v1 API `/query` endpoint supports InfluxQL and third-party integrat - [Examples](#examples) - [Responses](#responses) - [Error examples](#error-examples) -- [Write data with the v1 API](#write-data-with-the-v1-api) - - [Write using Telegraf](#write-using-telegraf) - - [Other Telegraf configuration options](#other-telegraf-configuration-options) - - [Write using client libraries](#write-using-client-libraries) - - [Write using HTTP clients](#write-using-http-clients) +- [Write data](#write-data) - [v1 API /write parameters](#v1-api-write-parameters) - [Timestamp precision](#timestamp-precision) - - [Use clients for interactive testing](#use-clients-for-interactive-testing) - - [v1 CLI not supported](#v1-cli-not-supported) + - [Tools for writing to the v1 API](#tools-for-writing-to-the-v1-api) + - [Telegraf](#telegraf) + - [Other Telegraf configuration options](#other-telegraf-configuration-options) + - [Interactive clients](#interactive-clients) + - [v1 CLI not supported](#v1-cli-not-supported) + - [Client libraries](#client-libraries) - [Query data](#query-data) - - [Query using the v1 API](#query-using-the-v1-api) - - [v1 API /query parameters](#v1-api-query-parameters) + - [v1 API /query parameters](#v1-api-query-parameters) - [Timestamp precision](#timestamp-precision) - - [Query using HTTP clients](#query-using-http-clients) - - [Query using Flight SQL](#query-using-flight-sql) +- [Query data](#query-data) + - [Tools to execute queries](#tools-to-execute-queries) - [Database management with InfluxQL not supported](#database-management-with-influxql-not-supported) - ## Authenticate API requests -InfluxDB requires each write request to be authenticated with a +InfluxDB requires each API request to be authenticated with a [database token](/influxdb/cloud-dedicated/admin/tokens/). With the InfluxDB v1 API, you can use database tokens in InfluxDB 1.x username and password schemes, in the InfluxDB v2 `Authorization: Token` scheme, or in the OAuth `Authorization: Bearer` scheme. -In the InfluxDB Cloud Dedicated HTTP API, `Authorization: Bearer` and `Authorization: Token` are equivalent. - [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme) - [Authenticate with a token scheme](#authenticate-with-a-token) @@ -73,11 +73,9 @@ In the InfluxDB Cloud Dedicated HTTP API, `Authorization: Bearer` and `Authoriza ### Authenticate with a username and password scheme With the InfluxDB v1 API, you can use the InfluxDB 1.x convention of -username and password to authenticate database reads and writes by passing a -[database token](/influxdb/cloud-dedicated/admin/tokens/) -as the `password` credential. -When authenticating requests to the v1 API `/write` and `/query` endpoints, InfluxDB Cloud Dedicated checks that `password` (`p`) is an authorized [database token](/influxdb/cloud-dedicated/admin/tokens/). -InfluxDB Cloud ignores the `username` (`u`) parameter in the request. +username and password to authenticate database reads and writes by passing a [database token](/influxdb/cloud-dedicated/admin/tokens/) as the `password` credential. +When authenticating requests to the v1 API `/write` and `/query` endpoints, {{% cloud-name %}} checks that the `password` (`p`) value is an authorized [database token](/influxdb/cloud-dedicated/admin/tokens/). +{{% cloud-name %}} ignores the `username` (`u`) parameter in the request. Use one of the following authentication schemes with clients that support Basic authentication or query parameters (that don't support [token authentication](#authenticate-with-a-token)): @@ -87,8 +85,8 @@ Use one of the following authentication schemes with clients that support Basic #### Basic authentication Use the `Authorization` header with the `Basic` scheme to authenticate v1 API `/write` and `/query` requests. -When authenticating requests, InfluxDB Cloud Dedicated checks that the `password` part of the decoded credential is an authorized [database token](/influxdb/cloud-dedicated/admin/tokens/). -InfluxDB Cloud Dedicated ignores the `username` part of the decoded credential. +When authenticating requests, {{% cloud-name %}} checks that the `password` part of the decoded credential is an authorized [database token](/influxdb/cloud-dedicated/admin/tokens/). +{{% cloud-name %}} ignores the `username` part of the decoded credential. ##### Syntax @@ -96,11 +94,7 @@ InfluxDB Cloud Dedicated ignores the `username` part of the decoded credential. Authorization: Basic ``` -Replace the following: - -- **`[USERNAME]`**: an optional string value (ignored by InfluxDB Cloud Dedicated). -- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/). -- Encode the `[USERNAME]:DATABASE_TOKEN` credential using base64 encoding, and then append the encoded string to the `Authorization: Basic` header. +Encode the `[USERNAME]:DATABASE_TOKEN` credential using base64 encoding, and then append the encoded string to the `Authorization: Basic` header. {{% api/v1-compat/basic-auth-syntax %}} @@ -108,19 +102,21 @@ Replace the following: The following example shows how to use cURL with the `Basic` authentication scheme and a [database token](/influxdb/cloud-dedicated/admin/tokens/): +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} ```sh {{% get-shared-text "api/cloud-dedicated/basic-auth.sh" %}} ``` +{{% /code-placeholders %}} Replace the following: -- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database -- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database +- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database #### Query string authentication In the URL, pass the `p` query parameter to authenticate `/write` and `/query` requests. -When authenticating requests, InfluxDB Cloud Dedicated checks that `p` (_password_) is an authorized database token and ignores the `u` (_username_) parameter. +When authenticating requests, {{% cloud-name %}} checks that the `p` (_password_) value is an authorized database token and ignores the `u` (_username_) parameter. ##### Syntax @@ -133,21 +129,23 @@ https://cluster-id.influxdb.io/write/?[u=any]&p=DATABASE_TOKEN The following example shows how to use cURL with query string authentication and [database token](/influxdb/cloud-dedicated/admin/tokens/). +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} ```sh {{% get-shared-text "api/cloud-dedicated/querystring-auth.sh" %}} ``` +{{% /code-placeholders %}} Replace the following: -- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database -- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database +- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database ### Authenticate with a token scheme Use the `Authorization: Bearer` or the `Authorization: Token` scheme to pass a [database token](/influxdb/cloud-dedicated/admin/tokens/) for authenticating v1 API `/write` and `/query` requests. -`Bearer` and `Token` are equivalent in InfluxDB Cloud Dedicated. +`Bearer` and `Token` are equivalent in {{% cloud-name %}}. The `Token` scheme is used in the InfluxDB 2.x API. `Bearer` is defined by the [OAuth 2.0 Framework](https://www.rfc-editor.org/rfc/rfc6750#page-14). Support for one or the other may vary across InfluxDB API clients. @@ -166,27 +164,31 @@ Authorization: Token DATABASE_TOKEN Use `Bearer` to authenticate a write request: +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} ```sh {{% get-shared-text "api/cloud-dedicated/bearer-auth-v1-write.sh" %}} ``` +{{% /code-placeholders %}} Use `Token` to authenticate a write request: +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} ```sh {{% get-shared-text "api/cloud-dedicated/token-auth-v1-write.sh" %}} ``` +{{% /code-placeholders %}} Replace the following: -- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database -- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database +- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database ## Responses InfluxDB API responses use standard HTTP status codes. For successful writes, InfluxDB responds with a `204 No Content` status code. Error responses contain a JSON object with `code` and `message` properties that describe the error. -Response body messages may differ across InfluxDB Cloud Dedicated v1 API, v2 API, InfluxDB Cloud, and InfluxDB OSS. +Response body messages may differ across {{% cloud-name %}} v1 API, v2 API, InfluxDB Cloud, and InfluxDB OSS. ### Error examples @@ -197,7 +199,9 @@ Response body messages may differ across InfluxDB Cloud Dedicated v1 API, v2 API ``` ```json - {"code":"invalid","message":"namespace name length must be between 1 and 64 characters"} + { "code":"invalid", + "message":"namespace name length must be between 1 and 64 characters" + } ``` The `?db=` parameter value is missing in the request. @@ -211,144 +215,27 @@ Response body messages may differ across InfluxDB Cloud Dedicated v1 API, v2 API ``` ```json - {"code":"invalid","message":"failed to deserialize db/rp/precision in request: unknown variant `u`, expected one of `s`, `ms`, `us`, `ns`"} + { "code":"invalid", + "message":"failed to deserialize db/rp/precision in request: unknown variant `u`, expected one of `s`, `ms`, `us`, `ns`" + } ``` The `?precision=` parameter contains an unknown value. Provide a [timestamp precision](#timestamp-precision). -## Write data with the v1 API +## Write data -Write data with your existing workloads that already use the InfluxDB v1 API or v1.x-compatibility API. +Write data with your existing workloads that already use the InfluxDB v1 or v1.x-compatibility `/write` API endpoint. -See how to set parameters and configure the following tools for writing to InfluxDB Cloud Dedicated: +{{% api-endpoint endpoint="https://cluster-id.influxdb.io/write" method="post" %}} -- [Write using Telegraf](#write-using-telegraf) -- [Write using client libraries](#write-using-client-libraries) -- [Write using HTTP clients](#write-using-http-clients) - - [v1 API /write parameters](#v1-api-write-parameters) - - [Use clients for interactive testing](#use-clients-for-interactive-testing) - -### Write using Telegraf - -If you have existing v1 workloads that use Telegraf, -you can use the [InfluxDB v1.x `influxdb` Telegraf output plugin](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) to write data. - -{{% warn %}} -Use [Telegraf and the v2 API](/influxdb/cloud-dedicated/primers/api/v2/) for new workloads that don't use already use the v1 API. -{{% /warn %}} - -The following table shows `outputs.influxdb` parameters and values writing -to InfluxDB Cloud Dedicated: - -Parameter | Ignored | Value --------------------------|--------------------------|--------------------------------------------------------------------------------------------------- -`database` | Honored | Database name -`retention_policy` | Honored, but discouraged | [Duration](/influxdb/cloud-dedicated/reference/glossary/#duration) -`username` | Ignored | String or empty -`password` | Honored | [Database token](/influxdb/cloud-dedicated/admin/tokens/) with permission to write to the database -`content_encoding` | Honored | `gzip` (compressed data) or `identity` (uncompressed) -`skip_database_creation` | Ignored | N/A (see how to [create a database](/influxdb/cloud-dedicated/admin/databases/create/)) - -To configure the v1.x output plugin for writing to InfluxDB Cloud Dedicated, -add the following `outputs.influxdb` configuration in your `telegraf.conf` file: - -```toml -[[outputs.influxdb]] - urls = ["https://cluster-id.influxdb.io"] - database = "DATABASE_NAME" - skip_database_creation = true - retention_policy = "" - username = "ignored" - password = "DATABASE_TOKEN" - content_encoding = "gzip” -``` - -Replace the following: - -- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database -- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/get-started/setup/#create-a-database-token) with permission to write to the database - -#### Other Telegraf configuration options - -`influx_uint_support`: supported in InfluxDB IOx. - -For more plugin options, see [`influxdb`](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) on GitHub. - -### Write using client libraries - -Use language-specific [v1 client libraries](/influxdb/v1.8/tools/api_client_libraries/) and your custom code to write data to InfluxDB Cloud Dedicated. -v1 client libraries send data in [line protocol](/influxdb/cloud-dedicated/reference/syntax/line-protocol/) syntax to the v1 API `/write` endpoint. - -The following samples show how to configure **v1** client libraries for writing to InfluxDB Cloud Dedicated: - -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[Node.js](#nodejs) -[Python](#python) -{{% /code-tabs %}} -{{% code-tab-content %}} - - -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' -}) -``` - -{{% /code-tab-content %}} -{{% code-tab-content %}} - - -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'} - ) -``` - -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -Replace the following: - -- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database -- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database - -### Write using HTTP clients - -Use HTTP clients and your custom code to send write requests to the v1 API `/write` endpoint. - -{{% api-endpoint endpoint="https://cluster-id.influxdb.io/write" method="post"%}} - -Include the following in your request: - -- A `db` query string parameter with the name of the database to write to. -- A request body that contains a string of data in [line protocol](/influxdb/cloud-dedicated/reference/syntax/line-protocol/) syntax. -- A [database token](/influxdb/cloud-dedicated/admin/tokens/) in one of the following authentication schemes: [Basic authentication](#basic-authentication), [query string authentication](#query-string-authentication), or [token authentication](#authenticate-with-a-token). -- Optional [parameters](#v1-api-write-parameters). +- [`/api/v2/write` parameters](#v1-api-write-parameters) +- [Tools for writing to the v1 API](#tools-for-writing-to-the-v1-api) #### v1 API /write parameters +For {{% cloud-name %}} v1 API `/write` requests, set parameters as listed in the following table: + Parameter | Allowed in | Ignored | Value -----------------------|--------------|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `consistency` | Query string | Ignored | N/A @@ -373,49 +260,167 @@ Use one of the following `precision` values in v1 API `/write` requests: - `m`: minutes - `h`: hours -#### Use clients for interactive testing +### Tools for writing to the v1 API -To test interactively, use common HTTP clients such as cURL and Postman to send requests to the v1 API `/write` endpoint. +The following tools work with the {{% cloud-name %}} `/write` endpoint: -{{% warn %}} -While the v1 CLI may coincidentally work with InfluxDB Cloud Dedicated, it isn't officially supported. -{{% /warn %}} +- [Telegraf](#telegraf) +- [Interactive clients](#interactive-clients) +- [Client libraries](#client-libraries) -The following example shows how to use the **cURL** command line tool and the InfluxDB Cloud Dedicated v1 API to write line protocol data to a database: +#### Telegraf +If you have existing v1 workloads that use Telegraf, +you can use the [InfluxDB v1.x `influxdb` Telegraf output plugin](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) to write data. + +{{% note %}} +See how to [use Telegraf and the v2 API](/influxdb/cloud-dedicated/write-data/use-telegraf/) for new workloads that don't already use the v1 API. +{{% /note %}} + +The following table shows `outputs.influxdb` plugin parameters and values for writing to the {{% cloud-name %}} v1 API: + +Parameter | Ignored | Value +-------------------------|--------------------------|--------------------------------------------------------------------------------------------------- +`database` | Honored | Database name +`retention_policy` | Honored, but discouraged | [Duration](/influxdb/cloud-dedicated/reference/glossary/#duration) +`username` | Ignored | String or empty +`password` | Honored | [Database token](/influxdb/cloud-dedicated/admin/tokens/) with permission to write to the database +`content_encoding` | Honored | `gzip` (compressed data) or `identity` (uncompressed) +`skip_database_creation` | Ignored | N/A (see how to [create a database](/influxdb/cloud-dedicated/admin/databases/create/)) + +To configure the v1.x output plugin for writing to {{% cloud-name %}}, add the following `outputs.influxdb` configuration in your `telegraf.conf` file: + +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} +```toml +[[outputs.influxdb]] + urls = ["https://cluster-id.influxdb.io"] + database = "DATABASE_NAME" + skip_database_creation = true + retention_policy = "" + username = "ignored" + password = "DATABASE_TOKEN" + content_encoding = "gzip” +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database +- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database + +##### Other Telegraf configuration options + +`influx_uint_support`: supported in InfluxDB IOx. + +For more plugin options, see [`influxdb`](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) on GitHub. + +#### Interactive clients + +To test InfluxDB v1 API writes interactively from the command line, use common HTTP clients such as cURL and Postman. + +Include the following in your request: + +- A `db` query string parameter with the name of the database to write to. +- A request body that contains a string of data in [line protocol](/influxdb/cloud-dedicated/reference/syntax/line-protocol/) syntax. +- A [database token](/influxdb/cloud-dedicated/admin/tokens/) in one of the following authentication schemes: [Basic authentication](#basic-authentication), [query string authentication](#query-string-authentication), or [token authentication](#authenticate-with-a-token). +- Optional [parameters](#v1-api-write-parameters). + +The following example shows how to use the **cURL** command line tool and the {{% cloud-name %}} v1 API to write line protocol data to a database: + +{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} ```sh curl -i 'https://cluster-id.influxdb.io/write?db=DATABASE_NAME&precision=s' \ --header 'Authorization: Bearer DATABASE_TOKEN' \ --header "Content-type: text/plain; charset=utf-8" --data-binary 'home,room=kitchen temp=72 1463683075' ``` +{{% /code-placeholders %}} Replace the following: -- **`DATABASE_NAME`**: your InfluxDB Cloud Dedicated database -- **`DATABASE_TOKEN`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database +- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database -### v1 CLI (not supported) +##### v1 CLI (not supported) Don't use the v1 CLI with {{% cloud-name %}}. While it may coincidentally work, it isn't officially supported. -If you need to test writes interactively, see how to [write using HTTP clients](#write-using-http-clients). +#### Client libraries + +Use language-specific [v1 client libraries](/influxdb/v1.8/tools/api_client_libraries/) and your custom code to write data to InfluxDB. +v1 client libraries send data in [line protocol](/influxdb/cloud-dedicated/reference/syntax/line-protocol/) syntax to the v1 API `/write` endpoint. + +The following samples show how to configure **v1** client libraries for writing to {{% cloud-name %}}: + +{{< tabs-wrapper >}} +{{% tabs %}} +[Node.js](#nodejs) +[Python](#python) +{{% /tabs %}} +{{% tab-content %}} + + +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 %}} + + +{{% /tab-content %}} +{{% tab-content %}} + + +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 %}} + + +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% cloud-name %}} database +- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with sufficient permissions to the database ## Query data -### Query using the v1 API +{{% cloud-name %}} provides the following protocols for executing a query: -Use the v1 API `/query` endpoint and [InfluxQL](/influxdb/cloud-dedicated/reference/glossary/#influxql) with InfluxDB Cloud Dedicated when you -bring InfluxDB 1.x workloads that already use them. +- [Flight+gRPC](https://arrow.apache.org/docs/format/Flight.html) request that contains an SQL or InfluxQL query. +- InfluxDB v1 API `/query` request that contains an InfluxQL query. -InfluxDB Cloud Dedicated +### v1 API /query parameters -{{% note %}} -For new workloads, see how to [query using Flight SQL](#query-using-flight-sql). -{{% /note %}} - -#### v1 API /query parameters +For {{% cloud-name %}} v1 API `/query` requests, set parameters as listed in the following table: Parameter | Allowed in | Ignored | Value ----------|------------|---------|------------------------------------------------------------------------- @@ -428,6 +433,10 @@ Parameter | Allowed in | Ignored | Value `p` | Query string | Honored | For [query string authentication](#query-string-authentication), a [database token](/influxdb/cloud-dedicated/get-started/setup/#create-a-database-token) with permission to write to the database `rp` | Query string | Honored, but discouraged | Retention policy +{{% note %}} +When bringing v1 API workloads to {{% cloud-name %}}, you'll need to adjust request parameters in your client configuration or code. +{{% /note %}} + #### Timestamp precision Use one of the following values for timestamp precision: @@ -439,80 +448,33 @@ Use one of the following values for timestamp precision: - `m`: minutes - `h`: hours -#### Query using HTTP clients +## Query data -Use HTTP clients and your custom code to send InfluxQL queries to the v1 API `/query` endpoint. +{{% cloud-name %}} provides the following protocols for executing a query: -{{% api-endpoint endpoint="https://cluster-id.influxdb.io/query" method="get"%}} +- [Flight+gRPC](https://arrow.apache.org/docs/format/Flight.html) request that contains an SQL or InfluxQL query. +- InfluxDB v1 API `/query` request that contains an InfluxQL query. -Include the following in your request: +{{% note %}} -- A `db` query string parameter with the name of the database to write to. -- A [database token](/influxdb/cloud-dedicated/admin/tokens/) in one of the following authentication schemes: [Basic authentication](#basic-authentication), [query string authentication](#query-string-authentication), or [token authentication](#authenticate-with-a-token). -- A `q` query string parameter with the InfluxQL query. -- Optional [parameters](#v1-api-query-parameters). +#### Tools to execute queries -The following examples show how to query using the v1 API `/query` endpoint and InfluxQL: +{{% cloud-name %}} supports many different tools for querying data, including: -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[cURL](#curl) -[Python](#python) -{{% /code-tabs %}} -{{% code-tab-content %}} - -```sh -{{% get-shared-text "api/cloud-dedicated/bearer-auth-v1-query.sh" %}} -``` +- [`influx3` data CLI](https://github.com/InfluxCommunity/influxdb3-python-cli) +- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) +- [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/) +- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/) +- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/) +- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api) +- [Chronograf](/{{< latest "Chronograf" >}}/) -```sh -{{% get-shared-text "api/cloud-dedicated/token-auth-v1-query.sh" %}} -``` - -{{% /code-tab-content %}} -{{% code-tab-content %}} - -```py -from influxdb import InfluxDBClient -import os +{{% /note %}} -DATABASE_NAME = os.getenv('CLOUD_DEDICATED_DATABASE_NAME') -DATABASE_TOKEN = os.getenv('CLOUD_DEDICATED_DATABASE_TOKEN') -INFLUXDB_URL=os.getenv('CLOUD_DEDICATED_URL') -INFLUXDB_HOST=os.getenv('CLOUD_DEDICATED_HOST') - -def influxdb_v1_client(headers=None): - client = InfluxDBClient( - host=INFLUXDB_HOST, - port=443, - ssl=True, - database=DATABASE_NAME, - username='USERNAME', - password=DATABASE_TOKEN, - headers=headers - ) - print(vars(client)) - return client - -def query_influxql(): - client = influxdb_v1_client() - response = client.query('SHOW MEASUREMENTS') - print(response) - return response -``` - -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -The response body contains query results in JSON format. - -### Query using Flight SQL - -Use Flight SQL clients with gRPC and SQL to query data stored in an InfluxDB Cloud Dedicated database. ### Database management with InfluxQL (not supported) -InfluxDB Cloud Dedicated doesn't allow InfluxQL commands for managing or modifying databases. +{{% cloud-name %}} doesn't allow InfluxQL commands for managing or modifying databases. You can't use the following InfluxQL commands: ```sql diff --git a/content/influxdb/cloud-dedicated/api-compatibility/v2/_index.md b/content/influxdb/cloud-dedicated/api-compatibility/v2/_index.md new file mode 100644 index 000000000..8b37e80ce --- /dev/null +++ b/content/influxdb/cloud-dedicated/api-compatibility/v2/_index.md @@ -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). + + + +- [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) + + + +## 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 %}}. + diff --git a/content/influxdb/cloud-dedicated/get-started/query.md b/content/influxdb/cloud-dedicated/get-started/query.md index 03cf2daa7..e2ca7c1b1 100644 --- a/content/influxdb/cloud-dedicated/get-started/query.md +++ b/content/influxdb/cloud-dedicated/get-started/query.md @@ -46,6 +46,7 @@ The examples in this section of the tutorial query the {{< req type="key" text="Covered in this tutorial" color="magenta" >}} +- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) - [Flight SQL clients](?t=Go#execute-an-sql-query){{< req "\* " >}} - [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/) - [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/) diff --git a/content/influxdb/cloud-dedicated/get-started/write.md b/content/influxdb/cloud-dedicated/get-started/write.md index a6738bb57..6be9df029 100644 --- a/content/influxdb/cloud-dedicated/get-started/write.md +++ b/content/influxdb/cloud-dedicated/get-started/write.md @@ -24,8 +24,8 @@ This tutorial walks you through the fundamental of creating **line protocol** da InfluxDB provides many different options for ingesting or writing data, including the following: - InfluxDB HTTP API (v1 and v2) -- `influx` CLI (v1 and v2) - Telegraf +- `influx3` data CLI - InfluxDB client libraries If using tools like Telegraf or InfluxDB client libraries, they can diff --git a/content/influxdb/cloud-dedicated/primers/_index.md b/content/influxdb/cloud-dedicated/primers/_index.md deleted file mode 100644 index dfdec1beb..000000000 --- a/content/influxdb/cloud-dedicated/primers/_index.md +++ /dev/null @@ -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 %}} \ No newline at end of file diff --git a/content/influxdb/cloud-dedicated/primers/api/_index.md b/content/influxdb/cloud-dedicated/primers/api/_index.md deleted file mode 100644 index 42247b6d3..000000000 --- a/content/influxdb/cloud-dedicated/primers/api/_index.md +++ /dev/null @@ -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>}} \ No newline at end of file diff --git a/content/influxdb/cloud-dedicated/primers/api/v2/_index.md b/content/influxdb/cloud-dedicated/primers/api/v2/_index.md deleted file mode 100644 index 89a56e72a..000000000 --- a/content/influxdb/cloud-dedicated/primers/api/v2/_index.md +++ /dev/null @@ -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). - - - - - -- [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) - - - -## 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 %}} - - -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. - - -{{% /code-tab-content %}} -{{% code-tab-content %}} - - -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. - -{{% /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). diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/_index.md b/content/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/_index.md index 477f5eae1..88b72efc3 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/_index.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/_index.md @@ -9,12 +9,36 @@ menu: name: Flight SQL clients parent: Client libraries influxdb/cloud-dedicated/tags: [Golang, Python, client libraries, Flight SQL] +aliases: + - /influxdb/cloud-dedicated/reference/client-libraries/flight-sql/go-flightsql/ + - /influxdb/cloud-dedicated/reference/client-libraries/flight-sql/python-flightsql-dbapi/ --- -Flight SQL clients are language-specific drivers that can interact with SQL databases using the Arrow in-memory format and the Flight RPC framework. -Clients provide a [`FlightClient`](https://arrow.apache.org/docs/python/generated/pyarrow.flight.FlightClient.html#pyarrow.flight.FlightClient) that can query and retrieve data from InfluxDB v3 using gRPC and Flight SQL. -Some [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3) include Flight SQL clients. +Flight and Flight SQL clients are language-specific drivers that interact with SQL databases using the Arrow in-memory format and the Flight RPC framework. +Clients provide a [`FlightClient`](https://arrow.apache.org/docs/python/generated/pyarrow.flight.FlightClient.html#pyarrow.flight.FlightClient) that can query and retrieve data from InfluxDB v3 using gRPC and Flight. + +Flight clients are maintained by Apache Arrow projects or third-parties. +For specifics about a Flight client, see the client's GitHub repository. + +{{% note %}} +[InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) use Flight clients +and offer additional convenience for writing, querying, and retrieving data stored in {{% cloud-name %}}. +{{% /note %}} + +## C# (csharp) + +- [Apache Arrow C# FlightClient](https://github.com/apache/arrow/tree/main/csharp/examples/FlightClientExample) + +## Go +- [Apache Arrow Go Flight SQL client](https://pkg.go.dev/github.com/apache/arrow/go/v12/arrow/flight/flightsql#Client) + +## Java +- [Apache Arrow Java FlightClient](https://arrow.apache.org/docs/java/reference/org/apache/arrow/flight/FlightClient.html) + +## Python +- [Apache Arrow PyArrow FlightClient](https://arrow.apache.org/docs/python/generated/pyarrow.flight.FlightClient.html#pyarrow.flight.FlightClient) +- [InfluxData flightsql-dbapi](https://github.com/influxdata/flightsql-dbapi) + + -For specifics about a client library, see the library's GitHub repository. -{{< children depth="999" description="true" >}} diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/_index.md b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/_index.md index 1e1bb503e..04ae24cb2 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/_index.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/_index.md @@ -24,11 +24,12 @@ For specifics about a client library, see the library's GitHub repository. ### Tools to execute queries InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint. -This endpoint can't query an InfluxDB Cloud Dedicated cluster. +This endpoint can't query an {{% cloud-name %}} cluster. -InfluxDB Cloud Dedicated supports many different tools for querying data, including: +{{% cloud-name %}} supports many different tools for querying data, including: -- [Flight SQL clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/) +- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) +- [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/) - [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/) - [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/) - [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api) diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/go.md b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/go.md index 4d46484ca..233596541 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/go.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/go.md @@ -1,21 +1,27 @@ --- -title: Go client library -seotitle: Use the InfluxDB Go client library +title: InfluxDB v2 Go client library list_title: Go description: > - Use the InfluxDB Go client library to interact with InfluxDB. + The InfluxDB v2 Go client library integrates with Go applications to write data to an InfluxDB Cloud Dedicated database. menu: influxdb_cloud_dedicated: name: Go parent: v2 client libraries influxdb/cloud-dedicated/tags: [client libraries, Go] weight: 201 -aliases: - - /influxdb/cloud-dedicated/reference/api/client-libraries/go/ - - /influxdb/cloud-dedicated/tools/client-libraries/go/ --- -Use the [InfluxDB Go client library](https://github.com/influxdata/influxdb-client-go) to integrate InfluxDB into Go scripts and applications. +Use the [InfluxDB Go client library](https://github.com/influxdata/influxdb-client-go) to write data to an {{% cloud-name %}} database. + +{{% note %}} +### Use the InfluxDB v3 client library + +InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint. +This endpoint can't query an {{% cloud-name %}} database. + +Use the [InfluxDB v3 Go client library](/influxdb/cloud-dedicated/reference/client-libraries/v3/go/) +to write and query data stored in {{% cloud-name %}}. +{{% /note %}} This guide presumes some familiarity with Go and InfluxDB. If just getting started, see [Get started with InfluxDB](/influxdb/cloud-dedicated/get-started/). @@ -30,7 +36,7 @@ If just getting started, see [Get started with InfluxDB](/influxdb/cloud-dedicat go get github.com/influxdata/influxdb-client-go/v2 ``` 3. Ensure that InfluxDB is running and you can connect to it. - For information about what URL to use to connect to your InfluxDB Cloud Dedicated cluster, contact your InfluxData account representative. + For information about what URL to use to connect to your {{% cloud-name %}} cluster, contact your InfluxData account representative. ## Boilerplate for the InfluxDB Go Client Library @@ -53,9 +59,9 @@ Use the Go library to write and query data from InfluxDB. 2. Define variables for your InfluxDB [database](/influxdb/cloud-dedicated/admin/databases/) (bucket), organization (required, but ignored), and [token](/influxdb/cloud-dedicated/admin/tokens/). ```go - bucket := "example-database" + bucket := "DATABASE_NAME" org := "ignored" - token := "example-token" + token := "DATABASE_TOKEN" // Store the URL of your InfluxDB instance url := "https://cluster-id.influxdb.io" ``` @@ -72,12 +78,6 @@ Use the Go library to write and query data from InfluxDB. writeAPI := client.WriteAPIBlocking(org, bucket) ``` -5. To query data, create an InfluxDB **query client** and pass in your InfluxDB `org`. - - ```go - queryAPI := client.QueryAPI(org) - ``` - ## Write data to InfluxDB with Go Use the Go library to write data to InfluxDB. @@ -109,9 +109,9 @@ import ( ) func main() { - bucket := "example-database" + bucket := "DATABASE_NAME" org := "ignored" - token := "example-token" + token := "DATABASE_TOKEN" // Store the URL of your InfluxDB instance url := "https://cluster-id.influxdb.io" // Create new client with default option for server url authenticate by token @@ -129,10 +129,3 @@ func main() { client.Close() } ``` -## Query data from InfluxDB with Go - -The InfluxDB v2 Go client can't query InfluxDB Cloud Dedicated. -To query your dedicated instance, use the [Go Flight SQL client](https://pkg.go.dev/github.com/apache/arrow/go/v12/arrow/flight/flightsql). -For an example, see [Get started querying data](/influxdb/cloud-dedicated/get-started/query/?t=Go#execute-an-sql-query). - -For more information, see the [Go client README on GitHub](https://github.com/influxdata/influxdb-client-go). diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/_index.md b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/_index.md index 29b345740..c27c81deb 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/_index.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/_index.md @@ -1,10 +1,10 @@ --- title: JavaScript client library for the InfluxDB v2 API -seotitle: Use the InfluxDB v2 JavaScript client library for the InfluxDB v2 API +seotitle: InfluxDB v2 JavaScript client library for the InfluxDB v2 API list_title: JavaScript description: > - Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) - for Node.js and browsers to write data to a InfluxDB Cloud Dedicated cluster. + The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) + for Node.js and browsers integrates with the InfluxDB v2 API to write data to an InfluxDB Cloud Dedicated cluster. menu: influxdb_cloud_dedicated: name: JavaScript @@ -15,7 +15,25 @@ aliases: - /influxdb/cloud-dedicated/reference/api/client-libraries/js/ --- -Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) -for Node.js and browsers to write data to a InfluxDB Cloud Dedicated cluster. +The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) +for Node.js and browsers integrates with the InfluxDB v2 API to write data to an {{% cloud-name %}} cluster. -{{< children type="list">}} +{{% note %}} +### Tools to execute queries + +InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint. +This endpoint can't query an {{% cloud-name %}} cluster. + +{{% cloud-name %}} supports many different tools for querying data, including: + +- [`influx3` data CLI](https://github.com/InfluxCommunity/influxdb3-python-cli) +- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) +- [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/) +- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/) +- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/) +- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api) +- [Chronograf](/{{< latest "Chronograf" >}}/) + +{{% /note %}} + +{{< children depth="999" >}} diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/browser.md b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/browser.md index a13bcdafd..2c6543064 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/browser.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/browser.md @@ -1,9 +1,8 @@ --- -title: JavaScript client library for web browsers -seotitle: Use the InfluxDB v2 JavaScript client library for web browsers +title: InfluxDB v2 JavaScript client library for web browsers list_title: JavaScript for browsers description: > - Use the InfluxDB v2 JavaScript client library to interact with InfluxDB in web clients. + Use the InfluxDB v2 JavaScript client library in browsers and front-end clients to write data to an InfluxDB Cloud Dedicated database. menu: influxdb_cloud_dedicated: name: Browsers and web clients @@ -19,23 +18,19 @@ related: - /influxdb/cloud-dedicated/api-guide/client-libraries/nodejs/query/ --- -Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) in browsers and front-end clients to write data to an InfluxDB Cloud Dedicated database. This library supports both front-end and server-side environments and provides the following distributions: -* ECMAScript modules (ESM) and CommonJS modules (CJS) -* Bundled ESM -* Bundled UMD - -This guide presumes some familiarity with JavaScript, browser environments, and InfluxDB. -If you're just getting started with InfluxDB, see [Get started with InfluxDB](/{{% latest "influxdb" %}}/get-started/). +Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) in browsers and front-end clients to write data to an {{% cloud-name %}} database. {{% note %}} + ### Tools to execute queries InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint. -This endpoint can't query an InfluxDB Cloud Dedicated cluster. +This endpoint can't query an {{% cloud-name %}} database. -InfluxDB Cloud Dedicated supports many different tools for querying data, including: +{{% cloud-name %}} supports many different tools for querying data, including: -- [Flight SQL clients](?t=Go#execute-an-sql-query) +- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) +- [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/) - [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/) - [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/) - [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api) @@ -43,6 +38,16 @@ InfluxDB Cloud Dedicated supports many different tools for querying data, includ {{% /note %}} +This library supports both front-end and server-side environments and provides the following distributions: + +- ECMAScript modules (ESM) and CommonJS modules (CJS) +- Bundled ESM +- Bundled UMD + +This guide presumes some familiarity with JavaScript, browser environments, and InfluxDB. +If you're just getting started with InfluxDB, see [Get started with InfluxDB](/{{% latest "influxdb" %}}/get-started/). + + {{% warn %}} ### Tokens in production applications {{% api/browser-token-warning %}} @@ -58,7 +63,7 @@ InfluxDB Cloud Dedicated supports many different tools for querying data, includ 1. Install [Node.js](https://nodejs.org/en/download/package-manager/) to serve your front-end app. 2. Ensure that InfluxDB is running and you can connect to it. - For information about what URL to use to connect to your InfluxDB Cloud Dedicated cluster, contact your InfluxData account representative. + For information about what URL to use to connect to your {{% cloud-name %}} cluster, contact your InfluxData account representative. ## Use with module bundlers @@ -121,7 +126,7 @@ The client library includes an example browser app that writes to your InfluxDB cd examples ``` -3. Update `./env_browser.js` with your InfluxDB Cloud Dedicated cluster URL, your database name as `bucket`, an arbitrary string as `org`, and your database token. +3. Update `./env_browser.js` with your {{% cloud-name %}} cluster URL, your database name as `bucket`, an arbitrary string as `org`, and your database token. 4. Run the following command to start the application at [http://localhost:3001/examples/index.html]() diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/_index.md b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/_index.md index fe8fb1201..575629106 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/_index.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/_index.md @@ -1,9 +1,10 @@ --- title: Node.js JavaScript client library -seotitle: Use the InfluxDB v2 JavaScript client library +seotitle: InfluxDB v2 JavaScript client library for Node.js list_title: Node.js description: > - Use the InfluxDB v2 JavaScript client library to interact with InfluxDB. + The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) + for Node.js integrates with the InfluxDB v2 API to write data to an InfluxDB Cloud Dedicated database. menu: influxdb_cloud_dedicated: name: Node.js @@ -14,26 +15,27 @@ aliases: - /influxdb/cloud-dedicated/reference/api/client-libraries/nodejs/ --- -Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) -to write data from Node.js and browser applications to an InfluxDB Cloud Dedicated cluster. - -## Use the client library in a Node.js application - -{{< children >}} +The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) +integrates with the InfluxDB v2 API to write data from Node.js and browser applications to an {{% cloud-name %}} database. {{% note %}} ### Tools to execute queries InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint. -This endpoint can't query an InfluxDB Cloud Dedicated cluster. +This endpoint can't query an {{% cloud-name %}} database. -InfluxDB Cloud Dedicated supports many different tools for querying data, including: +{{% cloud-name %}} supports many different tools for querying data, including: -- [Flight SQL clients](?t=Go#execute-an-sql-query) +- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) +- [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/) - [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/) - [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/) - [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api) - [Chronograf](/{{< latest "Chronograf" >}}/) {{% /note %}} + +## Use the client library in a Node.js application + +{{< children >}} diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/install.md b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/install.md index 84ac18e60..a07b084ab 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/install.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/install.md @@ -1,35 +1,61 @@ --- title: Install the InfluxDB v2 JavaScript client library -seotitle: Install the InfluxDB Node.js JavaScript client library description: > - Install the Node.js JavaScript client library to interact with the InfluxDB v2 API. + Install the Node.js JavaScript client library to write data to an InfluxDB Cloud Dedicated database. menu: influxdb_cloud_dedicated: name: Install parent: Node.js -influxdb/cloud-dedicated/tags: [client libraries, JavaScript] +influxdb/cloud-serverless/tags: [client libraries, JavaScript] weight: 100 aliases: - - /influxdb/cloud-dedicated/reference/api/client-libraries/nodejs/install + - /influxdb/cloud-serverless/reference/api/client-libraries/nodejs/install --- +{{% note %}} + +Install the Node.js JavaScript client library to write data to an {{% cloud-name %}} database. + +### Tools to execute queries + +InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint. +This endpoint can't query an {{% cloud-name %}} database. + +{{% cloud-name %}} supports many different tools for querying data, including: + +- [InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/) +- [Flight clients](/influxdb/cloud-serverless/reference/client-libraries/flight-sql/) +- [Superset](/influxdb/cloud-serverless/query-data/execute-queries/flight-sql/superset/) +- [Grafana](/influxdb/cloud-serverless/query-data/tools/grafana/) +- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-serverless/primers/api/v1/#query-using-the-v1-api) +- [Chronograf](/{{< latest "Chronograf" >}}/) + +{{% /note %}} + ## Install Node.js 1. Install [Node.js](https://nodejs.org/en/download/package-manager/). 2. Ensure that InfluxDB is running and you can connect to it. - For information about what URL to use to connect to your InfluxDB Cloud Dedicated cluster, contact your InfluxData account representative. + For information about what URL to use to connect to your {{% cloud-name %}} cluster, contact your InfluxData account representative. -3. Start a new Node.js project. - The `npm` package manager is included with Node.js. +3. In your terminal, create a directory for your Node.js project and change to it. - ```sh - npm init -y influx-node-app - ``` + ```sh + mkdir influx-node-app && cd $_ + ``` + +4. Enter the following command to generate an npm package for your project. + The `npm` package manager is included with Node.js. + + ```sh + npm init -y + ``` ## Install TypeScript -Many of the client library examples use [TypeScript](https://www.typescriptlang.org/). Follow these steps to initialize the TypeScript project. +Many of the client library examples use [TypeScript](https://www.typescriptlang.org/). +Follow these steps to initialize the TypeScript project: 1. Install TypeScript and type definitions for Node.js. @@ -49,22 +75,23 @@ Many of the client library examples use [TypeScript](https://www.typescriptlang. ## Install dependencies -Open a new terminal window and install `@influxdata/influxdb-client`: +Use the `@influxdata/influxdb-client` JavaScript client library to write data in {{% cloud-name %}}. + +Open a new terminal window and install the `@influxdata/influxdb-client` package for querying and writing data: ```sh npm i --save @influxdata/influxdb-client ``` -The `@influxdata/influxdb-client-apis` client library package doesn't -work with InfluxDB v3. -It only works with InfluxDB v2 management APIs. +The `@influxdata/influxdb-client-apis` client library package won't work with {{% cloud-name %}}. +It only works with InfluxDB v2 management APIs. ## 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 examples use these properties to interact with the InfluxDB API. -Set environment variables or update `env.js` with your InfluxDB [database](/influxdb/cloud-dedicated/admin/databases/) (bucket), organization (required, but ignored), [token](/influxdb/cloud-dedicated/admin/tokens/), and cluster URL. +Set environment variables or update `env.js` with your InfluxDB [database](/influxdb/cloud-dedicated/admin/databases/), organization (required, but ignored), [token](/influxdb/cloud-dedicated/admin/tokens/), and cluster URL. ```sh export INFLUX_URL=https://cluster-id.influxdb.io @@ -79,6 +106,6 @@ Set environment variables or update `env.js` with your InfluxDB [database](/infl ## Next steps -Once you've installed the client library and configured credentials, you're ready to [write data](/influxdb/cloud-dedicated/api-guide/client-libraries/nodejs/write/) to InfluxDB. +Once you've installed the client library and configured credentials, you're ready to [write data](/influxdb/cloud-serverless/api-guide/client-libraries/nodejs/write/) to InfluxDB. {{< page-nav next="/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/write/" keepTab=true >}} diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/write.md b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/write.md index 68a1c0b80..239eb45d0 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/write.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/write.md @@ -2,7 +2,7 @@ title: Write data with the InfluxDB v2 JavaScript client library list_title: Write data description: > - Use the JavaScript client library to write data with the InfluxDB API in Node.js. + The InfluxDB v2 JavaScript client library integrates with Node.js applications to write data to the InfluxDB v2 API. menu: influxdb_cloud_dedicated: name: Write @@ -29,7 +29,7 @@ The Javascript client library includes the following convenient features for wri ### Write data with the client library -1. Instantiate an `InfluxDB` client. Provide your InfluxDB URL and database token. +1. Instantiate a client by calling the `new InfluxDB()` constructor with your InfluxDB URL and database token (environment variables you already set in the [Install section](/influxdb/cloud-dedicated/api-guide/client-libraries/nodejs/install/)). ```js import {InfluxDB, Point} from '@influxdata/influxdb-client' diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/v3/_index.md b/content/influxdb/cloud-dedicated/reference/client-libraries/v3/_index.md index 9c712fa4f..666f3bef6 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/v3/_index.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/v3/_index.md @@ -13,11 +13,20 @@ influxdb/cloud-dedicated/tags: [client libraries, API, developer tools] ## Client libraries for InfluxDB v3 -InfluxDB v3 client libraries use InfluxDB HTTP APIs to write data and use [Flight SQL clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql) to query data stored in an InfluxDB Cloud Dedicated database. +InfluxDB v3 client libraries are language-specific packages that work with +and integrate with your application to write to and query data in {{% cloud-name %}}. -Functionality varies among client libraries. -These client libraries are in active development and may not be feature-complete. +InfluxDB client libraries provide configurable batch writing of data to InfluxDB HTTP APIs. +They can be used to construct line protocol data and transform data from other formats +to line protocol. + +InfluxDB v3 client libraries can query InfluxDB v3 using the Arrow Flight protocol with gRPC. +Client libraries use Flight clients to execute SQL and InfluxQL queries, request +database information, and retrieve data stored in {{% cloud-name %}}. + +Additional functionality may vary among client libraries and some may not be feature-complete. For specifics about a client library, see the library's GitHub repository. +InfluxDB v3 client libraries are part of the [Influx Community](https://github.com/InfluxCommunity). {{< children depth="999" description="true" >}} diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/v3/go.md b/content/influxdb/cloud-dedicated/reference/client-libraries/v3/go.md new file mode 100644 index 000000000..92e1974db --- /dev/null +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/v3/go.md @@ -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. + +InfluxDB v3 Go client library diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/v3/python.md b/content/influxdb/cloud-dedicated/reference/client-libraries/v3/python.md index c4e6b8c3b..1807b1cec 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/v3/python.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/v3/python.md @@ -7,8 +7,6 @@ menu: influxdb_cloud_dedicated: name: Python parent: v3 client libraries - params: - url: https://github.com/InfluxCommunity/influxdb3-python identifier: influxdb3-python influxdb/cloud-dedicated/tags: [python, gRPC, SQL, Flight SQL, client libraries] weight: 201 @@ -16,9 +14,483 @@ aliases: - /influxdb/cloud-dedicated/reference/client-libraries/v3/pyinflux3/ --- -The InfluxDB v3 [`influxdb3-python` Python client library](https://github.com/InfluxCommunity/influxdb3-python) integrates with Python scripts and applications -to write and query data stored in an {{% cloud-name %}} database. +The InfluxDB v3 [`influxdb3-python` Python client library](https://github.com/InfluxCommunity/influxdb3-python) +integrates {{% cloud-name %}} write and query operations with Python scripts and applications. -The documentation for this client library is available on GitHub. +InfluxDB client libraries provide configurable batch writing of data to {{% cloud-name %}}. +Client libraries can be used to construct line protocol data, transform data from other formats +to line protocol, and batch write line protocol data to InfluxDB HTTP APIs. -InfluxDB v3 Python client library \ No newline at end of file +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. + + + +- [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 + + +- [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. diff --git a/content/influxdb/cloud-dedicated/write-data/use-telegraf/configure/_index.md b/content/influxdb/cloud-dedicated/write-data/use-telegraf/configure/_index.md index fbc69ff37..76e7d9f9e 100644 --- a/content/influxdb/cloud-dedicated/write-data/use-telegraf/configure/_index.md +++ b/content/influxdb/cloud-dedicated/write-data/use-telegraf/configure/_index.md @@ -1,6 +1,6 @@ --- title: Configure Telegraf for InfluxDB -seotitle: Configure Telegraf to write to InfluxDB +seotitle: Configure Telegraf to write data to InfluxDB description: > Telegraf is a plugin-based agent with plugins that are enabled and configured in your Telegraf configuration file (`telegraf.conf`). @@ -41,6 +41,7 @@ for using Telegraf with {{< cloud-name >}}._ - [organization](#organization) - [bucket](#bucket) - [Write to InfluxDB v1.x and {{< cloud-name >}}](#write-to-influxdb-v1x-and--cloud-name-) + - [Other Telegraf configuration options](#other-telegraf-configuration-options) - [Start Telegraf](#start-telegraf) @@ -119,6 +120,12 @@ If a Telegraf agent is already writing to an InfluxDB v1.x database, enabling the InfluxDB v2 output plugin will write data to both v1.x and your {{< cloud-name >}} cluster. {{% /note %}} +### Other Telegraf configuration options + +`influx_uint_support`: supported in InfluxDB IOx. + +For more plugin options, see [`influxdb`](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) on GitHub. + ## Start Telegraf Start the Telegraf service using the `--config` flag to specify the location of your `telegraf.conf`. diff --git a/content/influxdb/cloud-serverless/api-compatibility/_index.md b/content/influxdb/cloud-serverless/api-compatibility/_index.md new file mode 100644 index 000000000..fb20bce82 --- /dev/null +++ b/content/influxdb/cloud-serverless/api-compatibility/_index.md @@ -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>}} \ No newline at end of file diff --git a/content/influxdb/cloud-serverless/api-compatibility/v1/_index.md b/content/influxdb/cloud-serverless/api-compatibility/v1/_index.md new file mode 100644 index 000000000..02de696df --- /dev/null +++ b/content/influxdb/cloud-serverless/api-compatibility/v1/_index.md @@ -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. + + + +- [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) + + + +## 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 +``` + +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 ` + +{{% 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 %}} + + +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 %}} + + +{{% /tab-content %}} +{{% tab-content %}} + + +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 %}} + + +{{% /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 +``` diff --git a/content/influxdb/cloud-serverless/api-compatibility/v2/_index.md b/content/influxdb/cloud-serverless/api-compatibility/v2/_index.md new file mode 100644 index 000000000..c897bddb2 --- /dev/null +++ b/content/influxdb/cloud-serverless/api-compatibility/v2/_index.md @@ -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). + + + +- [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) + + + +## 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 %}}. + diff --git a/content/influxdb/cloud-serverless/get-started/query.md b/content/influxdb/cloud-serverless/get-started/query.md index 351bebf1d..a27680dfd 100644 --- a/content/influxdb/cloud-serverless/get-started/query.md +++ b/content/influxdb/cloud-serverless/get-started/query.md @@ -49,14 +49,16 @@ The examples in this section of the tutorial query the [**get-started** bucket]( {{< req type="key" text="Covered in this tutorial" >}} -- [Flight SQL clients](?t=Go#execute-an-sql-query){{< req "\* " >}} - [InfluxDB user interface (UI)](?t=InfluxDB+UI#execute-an-sql-query){{< req "\* " >}} - [`influx3` data CLI](?t=influx3+CLI#execute-an-sql-query){{< req "\* " >}} -- [InfluxDB HTTP API](?t=InfluxDB+API#execute-an-sql-query){{< req "\* " >}} -- [`influx` CLI](?t=influx+CLI#execute-an-sql-query){{< req "\* " >}} +- [InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/) +- [Flight SQL clients](- [Flight clients](/influxdb/cloud-serverless/reference/client-libraries/flight-sql/) +){{< req "\* " >}} - [Superset](/influxdb/cloud-serverless/query-data/execute-queries/flight-sql/superset/) - [Grafana](/influxdb/cloud-serverless/query-data/tools/grafana/) - [Chronograf](/{{< latest "Chronograf" >}}/) +- [InfluxDB HTTP API](?t=InfluxDB+API#execute-an-sql-query){{< req "\* " >}} +- [`influx` CLI](?t=influx+CLI#execute-an-sql-query){{< req "\* " >}} ## SQL query basics diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/v2/go.md b/content/influxdb/cloud-serverless/reference/client-libraries/v2/go.md index ce59be31d..b8ffdaf79 100644 --- a/content/influxdb/cloud-serverless/reference/client-libraries/v2/go.md +++ b/content/influxdb/cloud-serverless/reference/client-libraries/v2/go.md @@ -1,21 +1,28 @@ --- -title: Go client library -seotitle: Use the InfluxDB Go client library +title: InfluxDB v2 Go client library list_title: Go description: > - Use the InfluxDB Go client library to interact with InfluxDB. + The InfluxDB v2 Go client library integrates with Go applications to write data to an InfluxDB Cloud Serverless bucket. menu: influxdb_cloud_serverless: name: Go parent: v2 client libraries influxdb/cloud-serverless/tags: [client libraries, Go] weight: 201 -aliases: - - /influxdb/cloud-serverless/reference/api/client-libraries/go/ - - /influxdb/cloud-serverless/tools/client-libraries/go/ --- -Use the [InfluxDB Go client library](https://github.com/influxdata/influxdb-client-go) to integrate InfluxDB into Go scripts and applications. +The [InfluxDB Go client library](https://github.com/influxdata/influxdb-client-go) +integrates with Go applications to write data to an {{% cloud-name %}} bucket. + +{{% note %}} +### Use the InfluxDB v3 client library + +InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint. +This endpoint can't query an {{% cloud-name %}} cluster. + +Use the [InfluxDB v3 Go client library](/influxdb/cloud-dedicated/reference/client-libraries/v3/go/) +to write and query data stored in {{% cloud-name %}}. +{{% /note %}} This guide presumes some familiarity with Go and InfluxDB. If just getting started, see [Get started with InfluxDB](/influxdb/cloud-serverless/get-started/). @@ -50,12 +57,13 @@ Use the Go library to write and query data from InfluxDB. ) ``` -2. Define variables for your InfluxDB [bucket](/influxdb/cloud-serverless/organizations/buckets/), [organization](/influxdb/cloud-serverless/organizations/), and [token](/influxdb/cloud-serverless/security/tokens/). +2. Define variables for your InfluxDB [bucket](/influxdb/cloud-serverless/organizations/buckets/) and [token](/influxdb/cloud-serverless/security/tokens/). + For `org`, pass a non-empty string (this parameter is ignored by InfluxDB, but required by the client). ```go - bucket := "example-bucket" - org := "example-org" - token := "example-token" + bucket := "BUCKET_NAME" + org := "ignored" + token := "API_TOKEN" // Store the URL of your InfluxDB instance url := "https://cloud2.influxdata.com" ``` @@ -72,12 +80,6 @@ Use the Go library to write and query data from InfluxDB. writeAPI := client.WriteAPIBlocking(org, bucket) ``` -5. To query data, create an InfluxDB **query client** and pass in your InfluxDB `org`. - - ```go - queryAPI := client.QueryAPI(org) - ``` - ## Write data to InfluxDB with Go Use the Go library to write data to InfluxDB. @@ -109,9 +111,9 @@ import ( ) func main() { - bucket := "example-bucket" - org := "example-org" - token := "example-token" + bucket := "BUCKET_NAME" + org := "ignored" + token := "API_TOKEN" // Store the URL of your InfluxDB instance url := "https://cloud2.influxdata.com" // Create new client with default option for server url authenticate by token diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/_index.md b/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/_index.md index a65dd9cd8..d0c27420f 100644 --- a/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/_index.md +++ b/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/_index.md @@ -1,10 +1,10 @@ --- title: JavaScript client library for the InfluxDB v2 API -seotitle: Use the InfluxDB v2 JavaScript client library for the InfluxDB v2 API +seotitle: InfluxDB v2 JavaScript client library for the InfluxDB v2 API list_title: JavaScript description: > - Use the InfluxDB v2 JavaScript client library to integrate with InfluxDB and the InfluxDB v2 API. -external_url: https://github.com/influxdata/influxdb-client-js + The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) + for Node.js and browsers integrates with the InfluxDB v2 API to write data to an InfluxDB Cloud Serverless bucket. menu: influxdb_cloud_serverless: name: JavaScript @@ -15,6 +15,25 @@ aliases: - /influxdb/cloud-serverless/reference/api/client-libraries/js/ --- -Use the [InfluxDB JavaScript client library](https://github.com/influxdata/influxdb-client-js) to integrate InfluxDB into Node.js and browser applications. +The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) +for Node.js and browsers integrates with the InfluxDB v2 API to write data to an {{% cloud-name %}} cluster. + +{{% note %}} +### Tools to execute queries + +InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint. +This endpoint can't query an {{% cloud-name %}} cluster. + +{{% cloud-name %}} supports many different tools for querying data, including: + +- [`influx3` data CLI](https://github.com/InfluxCommunity/influxdb3-python-cli) +- [InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/) +- [Flight clients](/influxdb/cloud-serverless/reference/client-libraries/flight-sql/) +- [Superset](/influxdb/cloud-serverless/query-data/execute-queries/flight-sql/superset/) +- [Grafana](/influxdb/cloud-serverless/query-data/tools/grafana/) +- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-serverless/primers/api/v1/#query-using-the-v1-api) +- [Chronograf](/{{< latest "Chronograf" >}}/) + +{{% /note %}} {{< children type="list">}} diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/browser.md b/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/browser.md index e69ce1828..be34dbb49 100644 --- a/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/browser.md +++ b/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/browser.md @@ -1,9 +1,8 @@ --- -title: JavaScript client library for web browsers -seotitle: Use the InfluxDB v2 JavaScript client library for web browsers +title: InfluxDB v2 JavaScript client library for web browsers list_title: JavaScript for browsers description: > - Use the InfluxDB v2 JavaScript client library to integrate with InfluxDB in web clients. + Use the InfluxDB v2 JavaScript client library in browsers and front-end clients to write data to an InfluxDB Cloud Serverless bucket. menu: influxdb_cloud_serverless: name: Browsers and web clients @@ -19,7 +18,27 @@ related: - /influxdb/cloud-serverless/api-guide/client-libraries/nodejs/query/ --- -Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) to integrate the InfluxDB v2 API in browsers and front-end clients. This library supports both front-end and server-side environments and provides the following distributions: +Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) in browsers and front-end clients to write data to an {{% cloud-name %}} bucket. + +{{% note %}} + +### Tools to execute queries + +InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint. +This endpoint can't query an {{% cloud-name %}} cluster. + +{{% cloud-name %}} supports many different tools for querying data, including: + +- [InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/) +- [Flight clients](/influxdb/cloud-serverless/reference/client-libraries/flight-sql/) +- [Superset](/influxdb/cloud-serverless/query-data/execute-queries/flight-sql/superset/) +- [Grafana](/influxdb/cloud-serverless/query-data/tools/grafana/) +- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-serverless/primers/api/v1/#query-using-the-v1-api) +- [Chronograf](/{{< latest "Chronograf" >}}/) + +{{% /note %}} + +This library supports both front-end and server-side environments and provides the following distributions: * ECMAScript modules (ESM) and CommonJS modules (CJS) * Bundled ESM * Bundled UMD @@ -42,12 +61,10 @@ If you're just getting started with InfluxDB, see [Get started with InfluxDB](/{ 1. Install [Node.js](https://nodejs.org/en/download/package-manager/) to serve your front-end app. 2. Ensure that InfluxDB is running and you can connect to it. - For information about what URL to use to connect to InfluxDB Cloud, see [InfluxDB URLs](/{{% latest "influxdb" %}}/reference/urls/). ## Use with module bundlers If you use a module bundler like Webpack or Parcel, install `@influxdata/influxdb-client-browser`. -For more information and examples, see [Node.js](/{{% latest "influxdb" %}}/api-guide/client-libraries/nodejs/). ## Use bundled distributions with browsers and module loaders @@ -56,14 +73,14 @@ For more information and examples, see [Node.js](/{{% latest "influxdb" %}}/api- ```html ``` Replace the following: - - **`INFLUX_READ_WRITE_TOKEN`**: An InfluxDB token with _write_ permission to the bucket. + - **`API_TOKEN`**: An InfluxDB token with WRITE permission to the bucket. 2. Import modules from the latest client library browser distribution. `@influxdata/influxdb-client-browser` exports bundled ESM and UMD syntaxes. @@ -95,20 +112,21 @@ For more information and examples, see [Node.js](/{{% latest "influxdb" %}}/api- {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} -After you've imported the client library, you're ready to [write data](/{{% latest "influxdb" %}}/api-guide/client-libraries/nodejs/write/?t=nodejs) to InfluxDB. +After you've imported the client library, you're ready to [get started writing data with the example app](#get-started-with-the-example-app). ## Get started with the example app -This library includes an example browser app that queries from and writes to your InfluxDB instance. +The client library includes an example browser app that writes to your InfluxDB instance. 1. Clone the [influxdb-client-js](https://github.com/influxdata/influxdb-client-js) repo. 2. Navigate to the `examples` directory: + ```js cd examples ``` -3. Update `./env_browser.js` with your InfluxDB [url](/{{% latest "influxdb" %}}/reference/urls/), [bucket](/{{% latest "influxdb" %}}/organizations/buckets/), [organization](/{{% latest "influxdb" %}}/organizations/), and [token](/{{% latest "influxdb" %}}/security/tokens/) +3. Update `./env_browser.js` with your {{% cloud-name %}} region URL, your [bucket](/influxdb/cloud-serverless/admin/buckets/), an arbitrary string as `org`, and your [API token](/influxdb/cloud-serverless/admin/tokens/). 4. Run the following command to start the application at [http://localhost:3001/examples/index.html]() @@ -117,3 +135,5 @@ This library includes an example browser app that queries from and writes to you ``` `index.html` loads the `env_browser.js` configuration, the client library ESM modules, and the application in your browser. + +For more examples, see how to [write data using the JavaScript client library for Node.js](/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/write/). diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/_index.md b/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/_index.md index 88aac2852..74ca1d6bb 100644 --- a/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/_index.md +++ b/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/_index.md @@ -1,10 +1,10 @@ --- title: Node.js JavaScript client library -seotitle: Use the InfluxDB v2 JavaScript client library +seotitle: InfluxDB v2 JavaScript client library for Node.js list_title: Node.js description: > - Use the InfluxDB v2 JavaScript client library to integrate with InfluxDB. -external_url: https://github.com/influxdata/influxdb-client-js + The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) + for Node.js integrates with the InfluxDB v2 API to write data to an InfluxDB Cloud Serverless bucket. menu: influxdb_cloud_serverless: name: Node.js @@ -12,11 +12,34 @@ menu: influxdb/cloud-serverless/tags: [client libraries, JavaScript, NodeJS] weight: 201 aliases: - - /influxdb/cloud-serverless/reference/api/client-libraries/nodejs/ + - /influxdb/cloud-serverless/reference/api/client-libraries/nodejs/ + - /influxdb/cloud-serverless/reference/api/client-libraries/nodejs/query/ + --- -Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) to integrate InfluxDB into Node.js and browser applications. +The [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) +integrates with the InfluxDB v2 API to write data from Node.js and browser applications to {{% cloud-name %}}. + +{{% note %}} + +### Tools to execute queries + +InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint. +This endpoint can't query an {{% cloud-name %}} cluster. + +{{% cloud-name %}} supports many different tools for querying data, including: + +- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) +- [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/) +- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/) +- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/) +- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api) +- [Chronograf](/{{< latest "Chronograf" >}}/) + +{{% /note %}} ## Use the client library in a Node.js application -{{< children type="list">}} +{{< children >}} + + diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/install.md b/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/install.md index 38ec4ea28..9d0753d88 100644 --- a/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/install.md +++ b/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/install.md @@ -1,8 +1,7 @@ --- title: Install the InfluxDB v2 JavaScript client library -seotitle: Install the InfluxDB Node.js JavaScript client library description: > - Install the Node.js JavaScript client library to integrate with the InfluxDB v2 API. + Install the Node.js JavaScript client library to write data to InfluxDB Cloud Serverless. menu: influxdb_cloud_serverless: name: Install @@ -13,13 +12,32 @@ aliases: - /influxdb/cloud-serverless/reference/api/client-libraries/nodejs/install --- +{{% note %}} + +Install the Node.js JavaScript client library to write data to InfluxDB {{% cloud-name %}}. + +### Tools to execute queries + +InfluxDB v2 client libraries use the InfluxDB API `/api/v2/query` endpoint. +This endpoint can't query an {{% cloud-name %}} cluster. + +{{% cloud-name %}} supports many different tools for querying data, including: + +- [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) +- [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight-sql/) +- [Superset](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/superset/) +- [Grafana](/influxdb/cloud-dedicated/query-data/tools/grafana/) +- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api) +- [Chronograf](/{{< latest "Chronograf" >}}/) + +{{% /note %}} ## Install Node.js 1. Install [Node.js](https://nodejs.org/en/download/package-manager/). 2. Ensure that InfluxDB is running and you can connect to it. - For information about what URL to use to connect to InfluxDB Cloud, see [InfluxDB URLs](/influxdb/cloud-serverless/reference/urls/). + For information about what URL to use to connect to {{% cloud-name %}}, see [InfluxDB URLs](/influxdb/cloud-serverless/reference/urls/). 3. In your terminal, create a directory for your Node.js project and change to it. @@ -57,15 +75,15 @@ Follow these steps to initialize the TypeScript project: ## Install dependencies -Use the `@influxdata/influxdb-client` JavaScript client library to write and query data in {{% cloud-name %}}. +Use the `@influxdata/influxdb-client` JavaScript client library to write data in {{% cloud-name %}}. Open a new terminal window and install the `@influxdata/influxdb-client` package for querying and writing data: ```sh - npm install --save @influxdata/influxdb-client + npm i --save @influxdata/influxdb-client ``` -The `@influxdata/influxdb-client-apis` client library package won't work with InfluxDB v3. +The `@influxdata/influxdb-client-apis` client library package won't work with {{% cloud-name %}}. It only works with InfluxDB v2 management APIs. ## Configure credentials diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/query.md b/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/query.md deleted file mode 100644 index a328b71c7..000000000 --- a/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/query.md +++ /dev/null @@ -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 >}} diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/write.md b/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/write.md index 237562547..b1978ebaa 100644 --- a/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/write.md +++ b/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/write.md @@ -2,7 +2,7 @@ title: Write data with the InfluxDB v2 JavaScript client library list_title: Write data description: > - Use the JavaScript client library to write data with the InfluxDB API in Node.js. + The JavaScript client library integrates with Node.js applications to write data to an InfluxDB Cloud Serverless bucket. menu: influxdb_cloud_serverless: name: Write @@ -63,7 +63,7 @@ The Javascript client library includes the following convenient features for wri ```js const point1 = new Point('temperature') .tag('sensor_id', 'TLM010') - .floatField('value', 24) + .floatField('value', 24.0) ``` 5. Use the `writePoint()` method to write the point to your InfluxDB bucket. diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/v3/_index.md b/content/influxdb/cloud-serverless/reference/client-libraries/v3/_index.md index c133eb7f5..ac8d2c930 100644 --- a/content/influxdb/cloud-serverless/reference/client-libraries/v3/_index.md +++ b/content/influxdb/cloud-serverless/reference/client-libraries/v3/_index.md @@ -13,11 +13,20 @@ influxdb/cloud-serverless/tags: [client libraries, API, developer tools] ## Client libraries for InfluxDB v3 -InfluxDB v3 client libraries use InfluxDB HTTP APIs to write data and use [Flight SQL clients](/influxdb/cloud-serverless/reference/client-libraries/flight-sql) to query data stored in an InfluxDB Cloud Serverless bucket. +InfluxDB v3 client libraries are language-specific packages that work with +and integrate with your application to write to and query data in {{% cloud-name %}}. -Functionality varies among client libraries. -These client libraries are in active development and may not be feature-complete. +InfluxDB client libraries provide configurable batch writing of data to InfluxDB HTTP APIs. +They can be used to construct line protocol data and transform data from other formats +to line protocol. + +InfluxDB v3 client libraries can query InfluxDB v3 using the Arrow Flight protocol with gRPC. +Client libraries use Flight clients to execute SQL queries, request +bucket information, and retrieve data stored in {{% cloud-name %}}. + +Additional functionality may vary among client libraries and some may not be feature-complete. For specifics about a client library, see the library's GitHub repository. +InfluxDB v3 client libraries are part of the [Influx Community](https://github.com/InfluxCommunity). {{< children depth="999" description="true" >}} diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/v3/go.md b/content/influxdb/cloud-serverless/reference/client-libraries/v3/go.md new file mode 100644 index 000000000..df6840ee8 --- /dev/null +++ b/content/influxdb/cloud-serverless/reference/client-libraries/v3/go.md @@ -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. + +InfluxDB v3 Go client library \ No newline at end of file diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/v3/python.md b/content/influxdb/cloud-serverless/reference/client-libraries/v3/python.md index 6d9212be5..632ddcc74 100644 --- a/content/influxdb/cloud-serverless/reference/client-libraries/v3/python.md +++ b/content/influxdb/cloud-serverless/reference/client-libraries/v3/python.md @@ -8,17 +8,491 @@ menu: name: Python parent: v3 client libraries identifier: influxdb3-python - params: - url: https://github.com/InfluxCommunity/influxdb3-python weight: 201 influxdb/cloud-serverless/tags: [python, gRPC, SQL, Flight SQL, client libraries] aliases: - /influxdb/cloud-serverless/reference/client-libraries/v3/pyinflux3/ --- -The InfluxDB v3 [`influxdb3-python` Python client library](https://github.com/InfluxCommunity/influxdb3-python) integrates with Python scripts and applications -to write and query data stored in an {{% cloud-name %}} bucket. +The InfluxDB v3 [`influxdb3-python` Python client library](https://github.com/InfluxCommunity/influxdb3-python) +integrates {{% cloud-name %}} write and query operations with Python scripts and applications. -The documentation for this client library is available on GitHub. +InfluxDB client libraries provide configurable batch writing of data to {{% cloud-name %}}. +Client libraries can be used to construct line protocol data, transform data from other formats +to line protocol, and batch write line protocol data to InfluxDB HTTP APIs. -InfluxDB v3 Python client library \ No newline at end of file +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. + + + +- [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 + + +- [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. diff --git a/shared/text/api/cloud-dedicated/basic-auth.sh b/shared/text/api/cloud-dedicated/basic-auth.sh index 0e3dc8ace..cb482e59e 100644 --- a/shared/text/api/cloud-dedicated/basic-auth.sh +++ b/shared/text/api/cloud-dedicated/basic-auth.sh @@ -2,10 +2,9 @@ # Use Basic authentication with a database token # to query the InfluxDB v1 API ####################################### -# Use the --user option with `--user username:DATABASE_TOKEN` syntax -####################################### -curl --get "http://cluster-id.influxdb.io/query" \ + +curl --get "https://cluster-id.influxdb.io/query" \ --user "":"DATABASE_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM MEASUREMENT" diff --git a/shared/text/api/cloud-dedicated/bearer-auth-v1-query.sh b/shared/text/api/cloud-dedicated/bearer-auth-v1-query.sh index e3a499345..cf114805b 100644 --- a/shared/text/api/cloud-dedicated/bearer-auth-v1-query.sh +++ b/shared/text/api/cloud-dedicated/bearer-auth-v1-query.sh @@ -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 ######################################################## diff --git a/shared/text/api/cloud-dedicated/bearer-auth-v2-write.sh b/shared/text/api/cloud-dedicated/bearer-auth-v2-write.sh index 5a4861126..8c9ea3b2f 100644 --- a/shared/text/api/cloud-dedicated/bearer-auth-v2-write.sh +++ b/shared/text/api/cloud-dedicated/bearer-auth-v2-write.sh @@ -1,8 +1,8 @@ ######################################################## -# Use the Bearer token authentication scheme with /api/v2/write +# Use the Bearer authorization scheme with /api/v2/write # to write data. ######################################################## -curl --post "https://cluster-id.influxdb.io/api/v2/write?bucket=DATABASE_NAME&precision=s" \ - --header "Authorization: Bearer DATABASE_TOKEN" \ +curl --post 'https://cluster-id.influxdb.io/api/v2/write?bucket=DATABASE_NAME&precision=s' \ + --header 'Authorization: Bearer DATABASE_TOKEN' \ --data-binary 'home,room=kitchen temp=72 1463683075' diff --git a/shared/text/api/cloud-dedicated/token-auth-v1-write.sh b/shared/text/api/cloud-dedicated/token-auth-v1-write.sh index e08da2cf6..6621613a1 100644 --- a/shared/text/api/cloud-dedicated/token-auth-v1-write.sh +++ b/shared/text/api/cloud-dedicated/token-auth-v1-write.sh @@ -1,5 +1,5 @@ ######################################################## -# Use the Bearer authorization scheme with v1 /write +# Use the Token authorization scheme with v1 /write # to write data. ######################################################## diff --git a/shared/text/api/cloud-serverless/basic-auth.sh b/shared/text/api/cloud-serverless/basic-auth.sh new file mode 100644 index 000000000..5700b2576 --- /dev/null +++ b/shared/text/api/cloud-serverless/basic-auth.sh @@ -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" diff --git a/shared/text/api/cloud-serverless/querystring-auth.sh b/shared/text/api/cloud-serverless/querystring-auth.sh new file mode 100644 index 000000000..f6d37700f --- /dev/null +++ b/shared/text/api/cloud-serverless/querystring-auth.sh @@ -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" diff --git a/shared/text/api/cloud-serverless/token-auth-v1-write.sh b/shared/text/api/cloud-serverless/token-auth-v1-write.sh new file mode 100644 index 000000000..4cd4948bf --- /dev/null +++ b/shared/text/api/cloud-serverless/token-auth-v1-write.sh @@ -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' \ No newline at end of file