From d36544709ea041fcc41bca8567187d84240c31b5 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 24 May 2023 09:09:15 -0500 Subject: [PATCH] chore(v3): v2 JS client library: (#4951) * chore(v3): v2 JS client library: - Remove v2 client-library query page from Dedicated. - Add v3 query tools note. - Update examples and credentials. * Update content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/browser.md Co-authored-by: Scott Anderson * Update content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/_index.md Co-authored-by: Scott Anderson * Update content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/query.md Co-authored-by: Scott Anderson * Update content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/query.md Co-authored-by: Scott Anderson --------- Co-authored-by: Scott Anderson --- .../reference/client-libraries/v2/_index.md | 18 ++- .../client-libraries/v2/javascript/_index.md | 9 +- .../client-libraries/v2/javascript/browser.md | 31 ++++- .../v2/javascript/nodejs/_index.md | 27 +++- .../v2/javascript/nodejs/install.md | 49 +++---- .../v2/javascript/nodejs/query.md | 16 --- .../v2/javascript/nodejs/write.md | 92 ++++++++------ .../client-libraries/v2/javascript/_index.md | 4 +- .../client-libraries/v2/javascript/browser.md | 6 +- .../v2/javascript/nodejs/_index.md | 6 +- .../v2/javascript/nodejs/install.md | 60 ++++----- .../v2/javascript/nodejs/query.md | 120 ++++++++++++++++++ .../v2/javascript/nodejs/write.md | 89 ++++++++----- 13 files changed, 354 insertions(+), 173 deletions(-) delete mode 100644 content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/query.md create mode 100644 content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/query.md 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 8e782260a..1e1bb503e 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/_index.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/_index.md @@ -17,8 +17,24 @@ InfluxDB client libraries are language-specific tools that integrate with Influx InfluxDB v2 client libraries use InfluxDB `/api/v2` endpoints and work with [InfluxDB 2.0 API compatibility endpoints](/{{< latest "influxdb" "v1" >}}/tools/api/#influxdb-20-api-compatibility-endpoints). Functionality varies among client libraries. -These client libraries are in active development and may not be feature-complete. For specifics about a client library, see the library's GitHub repository. +{{% 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. + +InfluxDB Cloud Dedicated supports many different tools for querying data, including: + +- [Flight SQL 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 type="list" depth="999" >}} 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 39a374721..29b345740 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 JavaScript client library for the InfluxDB v2 API +seotitle: Use the InfluxDB v2 JavaScript client library for the InfluxDB v2 API list_title: JavaScript description: > - Use the InfluxDB JavaScript client library to interact with InfluxDB 2.x and the InfluxDB v2 API. -external_url: https://github.com/influxdata/influxdb-client-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. menu: influxdb_cloud_dedicated: name: JavaScript @@ -15,6 +15,7 @@ aliases: - /influxdb/cloud-dedicated/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. +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. {{< children type="list">}} 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 80abfe966..a13bcdafd 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,9 @@ --- title: JavaScript client library for web browsers -seotitle: Use the InfluxDB JavaScript client library for web browsers +seotitle: Use the InfluxDB v2 JavaScript client library for web browsers list_title: JavaScript for browsers description: > - Use the InfluxDB JavaScript client library to interact with InfluxDB in web clients. + Use the InfluxDB v2 JavaScript client library to interact with InfluxDB in web clients. menu: influxdb_cloud_dedicated: name: Browsers and web clients @@ -19,7 +19,7 @@ related: - /influxdb/cloud-dedicated/api-guide/client-libraries/nodejs/query/ --- -Use the [InfluxDB JavaScript client library](https://github.com/influxdata/influxdb-client-js) to interact with 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 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 @@ -27,6 +27,22 @@ Use the [InfluxDB JavaScript client library](https://github.com/influxdata/influ This guide presumes some familiarity with JavaScript, browser environments, and InfluxDB. If you're just getting started with InfluxDB, see [Get started with InfluxDB](/{{% latest "influxdb" %}}/get-started/). +{{% note %}} +### 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. + +InfluxDB Cloud Dedicated supports many different tools for querying data, including: + +- [Flight SQL clients](?t=Go#execute-an-sql-query) +- [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 %}} + {{% warn %}} ### Tokens in production applications {{% api/browser-token-warning %}} @@ -56,7 +72,7 @@ If you use a module bundler like Webpack or Parcel, install `@influxdata/influxd ``` @@ -91,15 +107,16 @@ If you use a module bundler like Webpack or Parcel, install `@influxdata/influxd {{% /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 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 ``` @@ -113,3 +130,5 @@ This library includes an example browser app that writes to your InfluxDB instan ``` `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-dedicated/reference/client-libraries/v2/javascript/nodejs/write/). 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 2da6f1d61..fe8fb1201 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,10 +1,9 @@ --- title: Node.js JavaScript client library -seotitle: Use the InfluxDB JavaScript client library +seotitle: Use the InfluxDB v2 JavaScript client library list_title: Node.js description: > - Use the InfluxDB JavaScript client library to interact with InfluxDB. -external_url: https://github.com/influxdata/influxdb-client-js + Use the InfluxDB v2 JavaScript client library to interact with InfluxDB. menu: influxdb_cloud_dedicated: name: Node.js @@ -15,8 +14,26 @@ aliases: - /influxdb/cloud-dedicated/reference/api/client-libraries/nodejs/ --- -Use the [InfluxDB JavaScript client library](https://github.com/influxdata/influxdb-client-js) to integrate InfluxDB into Node.js and browser applications. +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 type="list">}} +{{< children >}} + +{{% 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. + +InfluxDB Cloud Dedicated supports many different tools for querying data, including: + +- [Flight SQL clients](?t=Go#execute-an-sql-query) +- [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 %}} 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 067f50544..84ac18e60 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,5 +1,5 @@ --- -title: Install the InfluxDB JavaScript client library +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. @@ -13,7 +13,6 @@ aliases: - /influxdb/cloud-dedicated/reference/api/client-libraries/nodejs/install --- - ## Install Node.js 1. Install [Node.js](https://nodejs.org/en/download/package-manager/). @@ -50,48 +49,36 @@ Many of the client library examples use [TypeScript](https://www.typescriptlang. ## Install dependencies -The JavaScript client library contains two packages: `@influxdata/influxdb-client` and `@influxdata/influxdb-client-apis`. -Add both as dependencies of your project. - -1. Open a new terminal window and install `@influxdata/influxdb-client` for querying and writing data: +Open a new terminal window and install `@influxdata/influxdb-client`: ```sh - npm install --save @influxdata/influxdb-client + npm i --save @influxdata/influxdb-client ``` -3. Install `@influxdata/influxdb-client-apis` for access to the InfluxDB management APIs: +The `@influxdata/influxdb-client-apis` client library package doesn't +work with InfluxDB v3. +It only works with InfluxDB v2 management APIs. - ```sh - npm install --save @influxdata/influxdb-client-apis - ``` +## Configure credentials -## Next steps - -Once you've installed the Javascript client library, you're ready to [write data](/influxdb/cloud-dedicated/api-guide/client-libraries/nodejs/write/) to InfluxDB or [get started](#get-started-with-examples) with other examples from the client library. - -## Get started with examples - -{{% note %}} 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. -{{% /note %}} -1. 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/) (bucket), organization (required, but ignored), [token](/influxdb/cloud-dedicated/admin/tokens/), and cluster URL. ```sh export INFLUX_URL=https://cluster-id.influxdb.io - export INFLUX_TOKEN=YOUR_API_TOKEN - export INFLUX_ORG=YOUR_ORG - export INFLUX_BUCKET=YOUR_BUCKET + export INFLUX_TOKEN=DATABASE_TOKEN + export INFLUX_ORG=ORG_ID + export INFLUX_DATABASE=DATABASE_NAME ``` Replace the following: - - *`YOUR_API_TOKEN`*: InfluxDB database token - - *`YOUR_ORG`*: An arbitrary string (this credential is ignored) - - *`YOUR_BUCKET`*: InfluxDB database name + - **`DATABASE_TOKEN`**: InfluxDB database token + - **`ORG_ID`**: An arbitrary string (InfluxDB ignores this credential, but the client library requires it) + - **`DATABASE_NAME`**: InfluxDB database name -2. Run an example script. +## Next steps - ```sh - query.ts - ``` -{{% api/v2dot0/nodejs/learn-more %}} +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. + +{{< 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/query.md b/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/query.md deleted file mode 100644 index e8baaf155..000000000 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/query.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Query data with the InfluxDB JavaScript client library -description: > - Use the JavaScript client library to query data with the InfluxDB API in Node.js. -menu: - influxdb_cloud_dedicated: - name: Query - parent: Node.js -influxdb/cloud-dedicated/tags: [client libraries, JavaScript] -weight: 201 -aliases: - - /influxdb/cloud-dedicated/reference/api/client-libraries/nodejs/query ---- - -The [InfluxDB JavaScript client library](https://github.com/influxdata/influxdb-client-js) cannot query an InfluxDB Cloud dedicated cluster. -To query your dedicated instance, use a Flight SQL client with gRPC. 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 28bcfb908..68a1c0b80 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 @@ -1,5 +1,6 @@ --- -title: Write data with the InfluxDB JavaScript client library +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. menu: @@ -14,7 +15,7 @@ related: - /influxdb/cloud-dedicated/write-data/troubleshoot/ --- -Use the [InfluxDB Javascript client library](https://github.com/influxdata/influxdb-client-js) to write data from a Node.js environment to InfluxDB. +Use the [InfluxDB v2 Javascript client library](https://github.com/influxdata/influxdb-client-js) to write data from a Node.js environment to InfluxDB. The Javascript client library includes the following convenient features for writing data to InfluxDB: - Apply default tags to data points. @@ -25,28 +26,25 @@ The Javascript client library includes the following convenient features for wri ### Before you begin - [Install the client library and other dependencies](/influxdb/cloud-dedicated/api-guide/client-libraries/nodejs/install/). + ### Write data with the client library -1. Instantiate an `InfluxDB` client. Provide your InfluxDB URL and API token. +1. Instantiate an `InfluxDB` client. Provide your InfluxDB URL and database token. ```js import {InfluxDB, Point} from '@influxdata/influxdb-client' - const influxDB = new InfluxDB({YOUR_URL, YOUR_API_TOKEN}) + const influxDB = new InfluxDB({url: process.env.INFLUX_URL, + token: process.env.INFLUX_TOKEN}) ``` - Replace the following: - - *`YOUR_URL`*: InfluxDB Cloud Dedicated cluster URL - - *`YOUR_API_TOKEN`*: InfluxDB database token 2. Use the `getWriteApi()` method of the client to create a **write client**. - Provide your InfluxDB organization ID and bucket name. + Provide your InfluxDB organization ID and database name. ```js - const writeApi = influxDB.getWriteApi(YOUR_ORG, YOUR_BUCKET) + const writeApi = influxDB.getWriteApi(process.env.INFLUX_ORG, + process.env.INFLUX_DATABASE) ``` - Replace the following: - - *`YOUR_ORG`*: Arbitrary string (ignored by InfluxDB, but required for the method) - - *`YOUR_BUCKET`*: InfluxDB database name 3. To apply one or more [tags](/influxdb/cloud-dedicated/reference/glossary/#tag) to all points, use the `useDefaultTags()` method. Provide tags as an object of key/value pairs. @@ -65,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. @@ -82,36 +80,58 @@ The Javascript client library includes the following convenient features for wri ### Complete example -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[Curl](#curl) -[Node.js](#nodejs) -{{% /code-tabs %}} -{{% code-tab-content %}} - -```sh -{{< get-shared-text "api/v2.0/write/write.sh" >}} -``` -{{% /code-tab-content %}} -{{% code-tab-content %}} - ```js -{{< get-shared-text "api/v2.0/write/write.mjs" >}} +'use strict' +/** @module write + * Writes a data point to InfluxDB using the Javascript client library with Node.js. +**/ + +import {InfluxDB, Point} from '@influxdata/influxdb-client' + +/** + * Instantiate the InfluxDB client + * with a configuration object. + **/ +const influxDB = new InfluxDB({url: process.env.INFLUX_URL, + token: process.env.INFLUX_TOKEN}) + +/** + * Create a write client from the getWriteApi method. + * Provide your org and database. + **/ +const writeApi = influxDB.getWriteApi(process.env.INFLUX_ORG, + process.env.INFLUX_DATABASE) + +/** + * Apply default tags to all points. + **/ +writeApi.useDefaultTags({region: 'west'}) + +/** + * Create a point and write it to the buffer. + **/ +const point1 = new Point('temperature') + .tag('sensor_id', 'TLM01') + .floatField('value', 24.0) +console.log(` ${point1}`) + +writeApi.writePoint(point1) + +/** + * Flush pending writes and close writeApi. + **/ +writeApi.close().then(() => { + console.log('WRITE FINISHED') +}) ``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -To run the example from a file, set your InfluxDB environment variables and use `node` to execute the JavaScript file. +In your terminal with [environment variables or `env.js` set](/influxdb/cloud-dedicated/reference/client-libraries/v2/javascript/nodejs/install/#configure-credentials), run the following command to execute the JavaScript file: ```sh -export INFLUX_URL=https://cluster-id.influxdb.io && \ -export INFLUX_TOKEN=YOUR_DATABASE_TOKEN && \ -export INFLUX_ORG=YOUR_ORG && \ -export INFLUX_BUCKET=YOUR_DATABASE_NAME && \ node write.js ``` ### Response codes + _For information about **InfluxDB API response codes**, see -[InfluxDB API Write documentation](/influxdb/cloud/api/#operation/PostWrite)._ +[InfluxDB API Write documentation](/influxdb/cloud-dedicated/api/#operation/PostWrite)._ 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 2a0bdcb0d..a65dd9cd8 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,9 +1,9 @@ --- title: JavaScript client library for the InfluxDB v2 API -seotitle: Use the InfluxDB JavaScript client library for the InfluxDB v2 API +seotitle: Use the InfluxDB v2 JavaScript client library for the InfluxDB v2 API list_title: JavaScript description: > - Use the InfluxDB JavaScript client library to interact with InfluxDB 2.x and the InfluxDB v2 API. + 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 menu: influxdb_cloud_serverless: 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 3da9995d4..e69ce1828 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,9 @@ --- title: JavaScript client library for web browsers -seotitle: Use the InfluxDB JavaScript client library for web browsers +seotitle: Use the InfluxDB v2 JavaScript client library for web browsers list_title: JavaScript for browsers description: > - Use the InfluxDB JavaScript client library to interact with InfluxDB in web clients. + Use the InfluxDB v2 JavaScript client library to integrate with InfluxDB in web clients. menu: influxdb_cloud_serverless: name: Browsers and web clients @@ -19,7 +19,7 @@ related: - /influxdb/cloud-serverless/api-guide/client-libraries/nodejs/query/ --- -Use the [InfluxDB JavaScript client library](https://github.com/influxdata/influxdb-client-js) to interact with 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) 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: * ECMAScript modules (ESM) and CommonJS modules (CJS) * Bundled ESM * Bundled UMD 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 1ae3abfa0..88aac2852 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,9 +1,9 @@ --- title: Node.js JavaScript client library -seotitle: Use the InfluxDB JavaScript client library +seotitle: Use the InfluxDB v2 JavaScript client library list_title: Node.js description: > - Use the InfluxDB JavaScript client library to interact with InfluxDB. + Use the InfluxDB v2 JavaScript client library to integrate with InfluxDB. external_url: https://github.com/influxdata/influxdb-client-js menu: influxdb_cloud_serverless: @@ -15,7 +15,7 @@ aliases: - /influxdb/cloud-serverless/reference/api/client-libraries/nodejs/ --- -Use the [InfluxDB JavaScript client library](https://github.com/influxdata/influxdb-client-js) to integrate InfluxDB into Node.js and browser applications. +Use the [InfluxDB v2 JavaScript client library](https://github.com/influxdata/influxdb-client-js) to integrate InfluxDB into Node.js and browser applications. ## Use the client library in a Node.js application 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 1619a0668..de2f41c6e 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,8 @@ --- -title: Install the InfluxDB JavaScript client library +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 integrate with the InfluxDB v2 API. menu: influxdb_cloud_serverless: name: Install @@ -21,16 +21,23 @@ aliases: 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/). -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. @@ -50,50 +57,39 @@ Many of the client library examples use [TypeScript](https://www.typescriptlang. ## Install dependencies -The JavaScript client library contains two packages: `@influxdata/influxdb-client` and `@influxdata/influxdb-client-apis`. -Add both as dependencies of your project. +Use the `@influxdata/influxdb-client` JavaScript client library to write and query data in InfluxDB Cloud Serverless. -1. Open a new terminal window and install `@influxdata/influxdb-client` for querying and writing data: +Open a new terminal window and install the `@influxdata/influxdb-client` package for querying and writing data: ```sh npm install --save @influxdata/influxdb-client ``` -3. Install `@influxdata/influxdb-client-apis` for access to the InfluxDB management APIs: +The `@influxdata/influxdb-client-apis` client library package won't work with InfluxDB v3. +It only works with InfluxDB v2 management APIs. - ```sh - npm install --save @influxdata/influxdb-client-apis - ``` +## Configure credentials -## Next steps - -Once you've installed the Javascript client library, you're ready to [write data](/influxdb/cloud-serverless/api-guide/client-libraries/nodejs/write/) to InfluxDB or [get started](#get-started-with-examples) with other examples from the client library. - -## Get started with examples - -{{% note %}} 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. -{{% /note %}} -1. Set environment variables or update `env.js` with your InfluxDB [bucket](/influxdb/cloud-serverless/organizations/buckets/), [organization](/influxdb/cloud-serverless/organizations/), [token](/influxdb/cloud-serverless/security/tokens/), and [url](/influxdb/cloud-serverless/reference/urls/). +Set environment variables or update `env.js` with your InfluxDB [bucket](/influxdb/cloud-serverless/organizations/buckets/), [organization](/influxdb/cloud-serverless/organizations/), [token](/influxdb/cloud-serverless/security/tokens/), and [url](/influxdb/cloud-serverless/reference/urls/). ```sh export INFLUX_URL=https://cloud2.influxdata.com - export INFLUX_TOKEN=INFLUX_READ_WRITE_TOKEN + export INFLUX_TOKEN=API_TOKEN export INFLUX_ORG=ORG_ID export INFLUX_BUCKET=BUCKET_NAME ``` Replace the following: - - *`INFLUX_READ_WRITE_TOKEN`*: InfluxDB token with _write_ permission to the bucket. + - *`API_TOKEN`*: InfluxDB API token with _write_ permission to the bucket. - *`ORG_ID`*: InfluxDB organization ID - - *`BUCKET_NAME`*: The name of the InfluxDB bucket to write to. + - *`BUCKET_NAME`*: the name of the InfluxDB Cloud Serverless bucket to write to -2. Run an example script. +## Next steps - ```sh - query.ts - ``` -{{% api/v2dot0/nodejs/learn-more %}} +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/). + +{{< page-nav next="/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/query.md b/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/query.md new file mode 100644 index 000000000..a328b71c7 --- /dev/null +++ b/content/influxdb/cloud-serverless/reference/client-libraries/v2/javascript/nodejs/query.md @@ -0,0 +1,120 @@ +--- +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 c42b2ea7e..237562547 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 @@ -1,5 +1,6 @@ --- -title: Write data with the InfluxDB JavaScript client library +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. menu: @@ -9,12 +10,12 @@ menu: influxdb/cloud-serverless/tags: [client libraries, JavaScript] weight: 101 aliases: - - /influxdb/cloud-serverless/reference/api/client-libraries/nodejs/write + - /influxdb/cloud-serverless/reference/api/client-libraries/nodejs/write/ related: - /influxdb/cloud-serverless/write-data/troubleshoot/ --- -Use the [InfluxDB Javascript client library](https://github.com/influxdata/influxdb-client-js) to write data from a Node.js environment to InfluxDB. +Use the [InfluxDB v2 Javascript client library](https://github.com/influxdata/influxdb-client-js) to write data from a Node.js environment to InfluxDB. The Javascript client library includes the following convenient features for writing data to InfluxDB: - Apply default tags to data points. @@ -25,28 +26,25 @@ The Javascript client library includes the following convenient features for wri ### Before you begin - [Install the client library and other dependencies](/influxdb/cloud-serverless/api-guide/client-libraries/nodejs/install/). + ### Write data with the client library -1. Instantiate an `InfluxDB` client. Provide your InfluxDB URL and API token. +1. Instantiate a client by calling the `new InfluxDB()` constructor with your InfluxDB URL and API token (environment variables you already set in the [Install section](/influxdb/cloud-serverless/api-guide/client-libraries/nodejs/install/)). ```js import {InfluxDB, Point} from '@influxdata/influxdb-client' - const influxDB = new InfluxDB({YOUR_URL, YOUR_API_TOKEN}) + const influxDB = new InfluxDB({url: process.env.INFLUX_URL, + token: process.env.INFLUX_TOKEN}) ``` - Replace the following: - - *`YOUR_URL`*: InfluxDB URL - - *`YOUR_API_TOKEN`*: InfluxDB API token 2. Use the `getWriteApi()` method of the client to create a **write client**. Provide your InfluxDB organization ID and bucket name. ```js - const writeApi = influxDB.getWriteApi(YOUR_ORG, YOUR_BUCKET) + const writeApi = influxDB.getWriteApi(process.env.INFLUX_ORG, + process.env.INFLUX_BUCKET) ``` - Replace the following: - - *`YOUR_ORG`*: InfluxDB organization ID - - *`YOUR_BUCKET`*: InfluxDB bucket name 3. To apply one or more [tags](/influxdb/cloud-serverless/reference/glossary/#tag) to all points, use the `useDefaultTags()` method. Provide tags as an object of key/value pairs. @@ -82,35 +80,58 @@ The Javascript client library includes the following convenient features for wri ### Complete example -{{< code-tabs-wrapper >}} -{{% code-tabs %}} -[Node.js](#nodejs) -{{% /code-tabs %}} -{{% code-tab-content %}} - ```js -{{< get-shared-text "api/v2.0/write/write.mjs" >}} +'use strict' +/** @module write + * Writes a data point to InfluxDB using the Javascript client library with Node.js. +**/ + +import {InfluxDB, Point} from '@influxdata/influxdb-client' + +/** + * Instantiate the InfluxDB client. + * Provide your InfluxDB URL and API token. + **/ +const influxDB = new InfluxDB({url: process.env.INFLUX_URL, + token: process.env.INFLUX_TOKEN}) + +/** + * Create a write client from the getWriteApi method. + * Provide your org and bucket. + **/ +const writeApi = influxDB.getWriteApi(process.env.INFLUX_ORG, + process.env.INFLUX_BUCKET) + +/** + * Apply default tags to all points. + **/ +writeApi.useDefaultTags({region: 'west'}) + +/** + * Create a point and write it to the buffer. + **/ +const point1 = new Point('temperature') + .tag('sensor_id', 'TLM01') + .floatField('value', 24.0) +console.log(` ${point1}`) + +writeApi.writePoint(point1) + +/** + * Flush pending writes and close writeApi. + **/ +writeApi.close().then(() => { + console.log('WRITE FINISHED') +}) ``` -{{% /code-tab-content %}} -{{< /code-tabs-wrapper >}} - -To run the example from a file, set your InfluxDB environment variables and use `node` to execute the JavaScript file. +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 -export INFLUX_URL=http://localhost:8086 && \ -export INFLUX_TOKEN=INFLUX_READ_WRITE_TOKEN && \ -export INFLUX_ORG=ORG_ID && \ -export INFLUX_BUCKET=BUCKET_NAME && \ node write.js ``` -Replace the following: - -- *`INFLUX_READ_WRITE_TOKEN`*: InfluxDB token with _write_ permission to the bucket. -- *`ORG_ID`*: InfluxDB organization ID -- *`BUCKET_NAME`*: The name of the InfluxDB bucket to write to. - ### Response codes + _For information about **InfluxDB API response codes**, see -[InfluxDB API Write documentation](/influxdb/cloud/api/#operation/PostWrite)._ +[InfluxDB API Write documentation](/influxdb/cloud-serverless/api/#operation/PostWrite)._