diff --git a/content/influxdb/v2.0/api-guide/client-libraries/js-browser.md b/content/influxdb/cloud/api-guide/client-libraries/browserjs.md similarity index 99% rename from content/influxdb/v2.0/api-guide/client-libraries/js-browser.md rename to content/influxdb/cloud/api-guide/client-libraries/browserjs.md index b61ff0984..ca06cd26e 100644 --- a/content/influxdb/v2.0/api-guide/client-libraries/js-browser.md +++ b/content/influxdb/cloud/api-guide/client-libraries/browserjs.md @@ -1,7 +1,7 @@ --- title: JavaScript client library seotitle: InfluxDB JavaScript client library -list_title: JavaScript +list_title: JavaScript (browser) description: > Use the JavaScript client library for web browsers to interact with InfluxDB. menu: diff --git a/content/influxdb/cloud/api-guide/client-libraries/js.md b/content/influxdb/cloud/api-guide/client-libraries/js.md deleted file mode 100644 index d907f2a82..000000000 --- a/content/influxdb/cloud/api-guide/client-libraries/js.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: JavaScript client library -seotitle: InfluxDB JavaScript client library -list_title: JavaScript -description: > - Use the JavaScript client library to interact with InfluxDB. -menu: - influxdb_cloud: - name: JavaScript - parent: Client libraries -influxdb/cloud/tags: [client libraries, JavaScript] -weight: 201 -aliases: - - /influxdb/cloud/reference/api/client-libraries/js/ ---- - -{{< duplicate-oss >}} \ No newline at end of file diff --git a/content/influxdb/cloud/api-guide/client-libraries/nodejs/_index.md b/content/influxdb/cloud/api-guide/client-libraries/nodejs/_index.md new file mode 100644 index 000000000..f5b942665 --- /dev/null +++ b/content/influxdb/cloud/api-guide/client-libraries/nodejs/_index.md @@ -0,0 +1,18 @@ +--- +title: Node.js JavaScript client library +seotitle: InfluxDB JavaScript client library +list_title: Node.js +description: > + Use the Node.js JavaScript client library to interact with InfluxDB. +menu: + influxdb_cloud: + name: Node.js + parent: Client libraries +influxdb/v2.0/tags: [client libraries, JavaScript] +weight: 201 +aliases: + - /influxdb/cloud/reference/api/client-libraries/js/ + - /influxdb/cloud/reference/api/client-libraries/nodejs/ +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/api-guide/client-libraries/nodejs/install.md b/content/influxdb/cloud/api-guide/client-libraries/nodejs/install.md new file mode 100644 index 000000000..10860ede3 --- /dev/null +++ b/content/influxdb/cloud/api-guide/client-libraries/nodejs/install.md @@ -0,0 +1,20 @@ +--- +title: Install the JavaScript client library +description: > + Install the Node.js JavaScript client library to interact with the InfluxDB API. +menu: + influxdb_cloud: + name: Install + parent: Node.js +influxdb/v2.0/tags: [client libraries, JavaScript] +weight: 100 +aliases: + - /influxdb/cloud/reference/api/client-libraries/js/install + - /influxdb/cloud/reference/api/client-libraries/nodejs/install +--- + +{{< duplicate-oss >}} + +{{% note %}} +The URL in the examples depends on your [InfluxDB Cloud region](/influxdb/cloud/reference/regions/). +{{% /note %}} diff --git a/content/influxdb/cloud/api-guide/client-libraries/nodejs/query.md b/content/influxdb/cloud/api-guide/client-libraries/nodejs/query.md new file mode 100644 index 000000000..585435094 --- /dev/null +++ b/content/influxdb/cloud/api-guide/client-libraries/nodejs/query.md @@ -0,0 +1,16 @@ +--- +title: Query data with the JavaScript client library +description: > + Use the Node.js JavaScript client library to query data with the InfluxDB API. +menu: + influxdb_cloud: + name: Query + parent: Node.js +influxdb/v2.0/tags: [client libraries, JavaScript] +weight: 201 +aliases: + - /influxdb/cloud/reference/api/client-libraries/js/query + - /influxdb/cloud/reference/api/client-libraries/nodejs/query +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/cloud/api-guide/client-libraries/nodejs/write.md b/content/influxdb/cloud/api-guide/client-libraries/nodejs/write.md new file mode 100644 index 000000000..fc739fd0e --- /dev/null +++ b/content/influxdb/cloud/api-guide/client-libraries/nodejs/write.md @@ -0,0 +1,16 @@ +--- +title: Write data with the JavaScript client library +description: > + Use the Node.js JavaScript client library to write data with the InfluxDB API. +menu: + influxdb_cloud: + name: Write + parent: Node.js +influxdb/v2.0/tags: [client libraries, JavaScript] +weight: 101 +aliases: + - /influxdb/cloud/reference/api/client-libraries/js/write + - /influxdb/cloud/reference/api/client-libraries/nodejs/write +--- + +{{< duplicate-oss >}} diff --git a/content/influxdb/v2.0/api-guide/_index.md b/content/influxdb/v2.0/api-guide/_index.md index c778db2f1..83ba47896 100644 --- a/content/influxdb/v2.0/api-guide/_index.md +++ b/content/influxdb/v2.0/api-guide/_index.md @@ -14,7 +14,7 @@ Access the InfluxDB API using the `/api/v2/` endpoint. ## InfluxDB client libraries InfluxDB client libraries are language-specific packages that integrate with the InfluxDB v2 API. -For information about supported client libraries, see [InfluxDB client libraries](/influxdb/v2.0/tools/client-libraries/). +For information about supported client libraries, see [InfluxDB client libraries](/{{< latest "influxdb" >}}/api-guide/client-libraries/). ## InfluxDB v2 API documentation InfluxDB OSS 2.0 API documentation diff --git a/content/influxdb/v2.0/api-guide/client-libraries/browserjs.md b/content/influxdb/v2.0/api-guide/client-libraries/browserjs.md new file mode 100644 index 000000000..000e6581e --- /dev/null +++ b/content/influxdb/v2.0/api-guide/client-libraries/browserjs.md @@ -0,0 +1,180 @@ +--- +title: JavaScript client library +seotitle: InfluxDB JavaScript client library +list_title: JavaScript (browser) +description: > + Use the JavaScript client library for web browsers to interact with InfluxDB. +menu: + influxdb_2_0: + name: Javascript (Browser) + parent: Client libraries +influxdb/v2.0/tags: [client libraries, JavaScript] +weight: 201 +aliases: + - /influxdb/v2.0/reference/api/client-libraries/browserjs/ +--- + +Use the [InfluxDB JavaScript client library](https://github.com/influxdata/influxdb-client-js) to integrate InfluxDB into JavaScript scripts and applications. This client supports both client-side (browser) and server-side (NodeJS) environments. + +This guide presumes some familiarity with JavaScript, browser environments, and InfluxDB. +If just getting started, see [Get started with InfluxDB](/influxdb/v2.0/get-started/). + +## Before you begin + +1. Install [NodeJS](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 OSS or InfluxDB Cloud, see [InfluxDB URLs](/influxdb/v2.0/reference/urls/). + +## Easiest way to get started +1. Clone the [examples directory](https://github.com/influxdata/influxdb-client-js/tree/master/examples) in the [influxdb-client-js](https://github.com/influxdata/influxdb-client-js) repo. +2. Navigate to the `examples` directory: + + ```js + cd examples + ``` +3. Install `yarn` or `npm` dependencies as needed: + +```js + yarn install + npm install +``` + +3. Update your `./env` and `index.html` with the name of your InfluxDB [bucket](/influxdb/v2.0/organizations/buckets/), [organization](/influxdb/v2.0/organizations/), [token](/influxdb/v2.0/security/tokens/), and `proxy` which relies upon proxy to forward requests to the target InfluxDB. +4. Run the following command to run the application at [http://localhost:3001/examples/index.html]() + + ```sh + npm run browser + ``` + +## Boilerplate for the InfluxDB Javascript client library +Use the Javascript library to write data to and query data from InfluxDB in a browser. + +1. To write a data point to InfluxDB using the JavaScript library, import the latest InfluxDB Javascript library in your script. + + ```js + import {InfluxDB, Point} from 'https://unpkg.com/@influxdata/influxdb-client/dist/index.browser.mjs' + ``` + +2. Define constants for your InfluxDB [bucket](/influxdb/v2.0/organizations/buckets/), [organization](/influxdb/v2.0/organizations/), [token](/influxdb/v2.0/security/tokens/), and `proxy` which relies on a proxy to forward requests to the target InfluxDB instance. + + ```js + const proxy = '/influx' + const token = 'example-token' + const org = 'example-org' + const bucket = 'example-bucket' + ``` + +3. Instantiate the InfluxDB JavaScript client and pass in the `proxy` and `token` parameters. + + ```js + const influxDB = new InfluxDB({proxy, token}) + ``` + +## Write data to InfluxDB with JavaScript +Use the Javascript library to write data to InfluxDB in a Node.js environment. + +1. Instantiate an `InfluxDB` client. Provide your InfluxDB `url` and `token`. +2. Use the `getWriteApi` method of the instantiated InfluxDB client to create a **write client**. Provide your InfluxDB `org` and `bucket`. + + ```js + import {InfluxDB, Point} from '@influxdata/influxdb-client' + + const influxDB = new InfluxDB({url, token}) + const writeApi = influxDB.getWriteApi(org, bucket) + ``` + + The `useDefaultTags` method instructs the write api to use default tags when writing points. Create a [point](/influxdb/v2.0/reference/glossary/#point) and write it to InfluxDB using the `writePoint` method. The `tag` and `floatField` methods add key value pairs for the tags and fields, respectively. Close the client to flush all pending writes and finish. + + ```js + writeApi.useDefaultTags({location: 'browser'}) + const point1 = new Point('temperature') + .tag('example', 'index.html') + .floatField('value', 24) + console.log(`${point1}`) + + writeApi.writePoint(point1) + writeApi.close() + ``` + +### Complete example write script + +```js +const influxDB = new InfluxDB({proxy, token}) +const writeApi = influxDB.getWriteApi(org, bucket) + +// setup default tags for all writes through this API +writeApi.useDefaultTags({location: 'browser'}) +const point1 = new Point('temperature') + .tag('example', 'index.html') + .floatField('value', 24) +console.log(` ${point1}`) + +writeApi.writePoint(point1) + +// flush pending writes and close writeApi +writeApi + .close() + .then(() => { + console.log('WRITE FINISHED') + }) +``` + +## Query data from InfluxDB with JavaScript +Use the Javascript library to query data from InfluxDB. + +1. Use the `getQueryApi` method of the `InfluxDB` client to create a new **query client**. Provide your InfluxDB `org`. + + ```js + const queryApi = influxDB.getQueryApi(org) + ``` + +2. Create a Flux query (including your `bucket` parameter). + + ```js + const fluxQuery = + 'from(bucket:"") + |> range(start: 0) + |> filter(fn: (r) => r._measurement == "temperature")' + ``` + + The **query client** sends the Flux query to InfluxDB and returns line table metadata and rows. + +3. Use the `next` method to iterate over the rows. + + ```js + queryApi.queryRows(fluxQuery, { + next(row: string[], tableMeta: FluxTableMetaData) { + const o = tableMeta.toObject(row) + // console.log(JSON.stringify(o, null, 2)) + console.log( + `${o._time} ${o._measurement} in '${o.location}' (${o.example}): ${o._field}=${o._value}` + ) + } + } + ``` + +### Complete example query script + +```js +// performs query and receive line table metadata and rows +// https://v2.docs.influxdata.com/v2.0/reference/syntax/annotated-csv/ +queryApi.queryRows(fluxQuery, { + next(row: string[], tableMeta: FluxTableMetaData) { + const o = tableMeta.toObject(row) + // console.log(JSON.stringify(o, null, 2)) + console.log( + '${o._time} ${o._measurement} in '${o.location}' (${o.example}): ${o._field}=${o._value}` + ) + }, + error(error: Error) { + console.error(error) + console.log('\nFinished ERROR') + }, + complete() { + console.log('\nFinished SUCCESS') + }, +}) +``` + +For more information, see the [JavaScript client README on GitHub](https://github.com/influxdata/influxdb-client-js). diff --git a/content/influxdb/v2.0/api-guide/client-libraries/js/_index.md b/content/influxdb/v2.0/api-guide/client-libraries/nodejs/_index.md similarity index 71% rename from content/influxdb/v2.0/api-guide/client-libraries/js/_index.md rename to content/influxdb/v2.0/api-guide/client-libraries/nodejs/_index.md index b49a433f9..76a35b7f6 100644 --- a/content/influxdb/v2.0/api-guide/client-libraries/js/_index.md +++ b/content/influxdb/v2.0/api-guide/client-libraries/nodejs/_index.md @@ -1,7 +1,7 @@ --- -title: JavaScript client library +title: Node.js JavaScript client library seotitle: InfluxDB JavaScript client library -list_title: JavaScript +list_title: Node.js description: > Use the Node.js JavaScript client library to interact with InfluxDB. menu: @@ -11,11 +11,16 @@ menu: influxdb/v2.0/tags: [client libraries, JavaScript] weight: 201 aliases: - - /influxdb/v2.0/reference/api/client-libraries/js/ + - /influxdb/v2.0/reference/api/client-libraries/nodejs/ + - /influxdb/v2.0/reference/api/client-libraries/js/ --- Use the [InfluxDB JavaScript client library](https://github.com/influxdata/influxdb-client-js) to integrate InfluxDB into your Node.js application. +{{% note %}} +{{% api/v2dot0/nodejs/install %}} +{{% /note %}} + In this guide, you'll start a Node.js project from scratch and code some simple API operations. {{< children >}} diff --git a/content/influxdb/v2.0/api-guide/client-libraries/js/install.md b/content/influxdb/v2.0/api-guide/client-libraries/nodejs/install.md similarity index 62% rename from content/influxdb/v2.0/api-guide/client-libraries/js/install.md rename to content/influxdb/v2.0/api-guide/client-libraries/nodejs/install.md index 9c4396f22..8668b823c 100644 --- a/content/influxdb/v2.0/api-guide/client-libraries/js/install.md +++ b/content/influxdb/v2.0/api-guide/client-libraries/nodejs/install.md @@ -7,31 +7,31 @@ menu: name: Install parent: Node.js influxdb/v2.0/tags: [client libraries, JavaScript] -weight: 201 +weight: 100 aliases: - - /influxdb/v2.0/reference/api/client-libraries/js/install + - /influxdb/v2.0/reference/api/client-libraries/nodejs/install --- ## Install 1. Install [Node.js](https://nodejs.org/en/download/package-manager/). -{{% note %}} -`npm` package manager is included with Node.js. -{{% /note %}} - 2. Ensure that InfluxDB is running and you can connect to it. For information about what URL to use to connect to InfluxDB OSS or InfluxDB Cloud, see [InfluxDB URLs](/influxdb/v2.0/reference/urls/). 3. Start a new Node.js project. + The `npm` package manager is included with Node.js. ```sh - npm init influx-node-app + npm init -y influx-node-app ``` - Answer or `Enter` through the prompts. - ## Install dependencies + +{{% note %}} +{{% api/v2dot0/nodejs/install %}} +{{% /note %}} + The JavaScript client contains two packages. Add both as dependencies of your project. 1. Change to your project directory: @@ -53,4 +53,12 @@ The JavaScript client contains two packages. Add both as dependencies of your pr ``` ## Configure your environment -Configure environment variables. Update your `./env` file with the name of your InfluxDB [bucket](/influxdb/v2.0/organizations/buckets/), [organization](/influxdb/v2.0/organizations/), [token](/influxdb/v2.0/security/tokens/), and [url](/influxdb/v2.0/urls). +Set environment variables for [bucket](/influxdb/v2.0/organizations/buckets/), [organization](/influxdb/v2.0/organizations/), [token](/influxdb/v2.0/security/tokens/), and [url](/influxdb/v2.0/urls). Your application will use these to interact with the InfluxDB API. + +```sh +{{< api/v2dot0/env >}} +``` + +{{% note %}} +The client examples include an [`env`](https://github.com/influxdata/influxdb-client-js/blob/master/examples/env.js) module for conveniently accessing environment variables. +{{% /note %}} diff --git a/content/influxdb/v2.0/api-guide/client-libraries/js/query.md b/content/influxdb/v2.0/api-guide/client-libraries/nodejs/query.md similarity index 94% rename from content/influxdb/v2.0/api-guide/client-libraries/js/query.md rename to content/influxdb/v2.0/api-guide/client-libraries/nodejs/query.md index 07ed01068..6ff4bdf3e 100644 --- a/content/influxdb/v2.0/api-guide/client-libraries/js/query.md +++ b/content/influxdb/v2.0/api-guide/client-libraries/nodejs/query.md @@ -9,10 +9,9 @@ menu: influxdb/v2.0/tags: [client libraries, JavaScript] weight: 201 aliases: - - /influxdb/v2.0/reference/api/client-libraries/js/nodejs/query + - /influxdb/v2.0/reference/api/client-libraries/nodejs/query --- -## Query data from InfluxDB with JavaScript Use the Javascript library to query data from InfluxDB. 1. Use the `getQueryApi` method of the `InfluxDB` client to create a new **query client**. Provide your InfluxDB `org`. diff --git a/content/influxdb/v2.0/api-guide/client-libraries/js/write.md b/content/influxdb/v2.0/api-guide/client-libraries/nodejs/write.md similarity index 64% rename from content/influxdb/v2.0/api-guide/client-libraries/js/write.md rename to content/influxdb/v2.0/api-guide/client-libraries/nodejs/write.md index 1396ffb16..4dc42d6ff 100644 --- a/content/influxdb/v2.0/api-guide/client-libraries/js/write.md +++ b/content/influxdb/v2.0/api-guide/client-libraries/nodejs/write.md @@ -7,18 +7,14 @@ menu: name: Write parent: Node.js influxdb/v2.0/tags: [client libraries, JavaScript] -weight: 201 +weight: 101 aliases: - - /influxdb/v2.0/reference/api/client-libraries/js/nodejs/write + - /influxdb/v2.0/reference/api/client-libraries/nodejs/write --- ## Write data to InfluxDB with JavaScript Use the Javascript library to write data to InfluxDB in a Node.js environment. -{{% note %}} -This library supports browser and server-side (Node.js) Javascript environments. Use `@influxdata/influxdb-client` in your Node.js project. -{{% /note %}} - 1. Instantiate an `InfluxDB` client. Provide your InfluxDB `url` and `token`. 2. Use the `getWriteApi` method of the instantiated InfluxDB client to create a **write client**. Provide your InfluxDB `org` and `bucket`. @@ -42,25 +38,34 @@ This library supports browser and server-side (Node.js) Javascript environments. writeApi.close() ``` -### Complete example write script +### Complete example -```js -const influxDB = new InfluxDB({proxy, token}) -const writeApi = influxDB.getWriteApi(org, bucket) - -// setup default tags for all writes through this API -writeApi.useDefaultTags({location: 'browser'}) -const point1 = new Point('temperature') - .tag('example', 'index.html') - .floatField('value', 24) -console.log(` ${point1}`) - -writeApi.writePoint(point1) - -// flush pending writes and close writeApi -writeApi - .close() - .then(() => { - console.log('WRITE FINISHED') - }) +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Curl](#curl) +[Node.js](#nodejs) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +{{< api/v2dot0/curl/write >}} +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```js +{{< api/v2dot0/nodejs/write >}} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +### Response codes +_For information about **InfluxDB API response codes**, see +[InfluxDB API Write documentation](/influxdb/cloud/api/#operation/PostWrite)._ + +### Compressing data + +To compress data when writing to InfluxDB, set the `Content-Encoding` header to `gzip`. +Compression reduces network bandwidth, but increases server-side load. + +```sh +{{< api/v2dot0/curl/write-compressed >}} ``` diff --git a/layouts/shortcodes/api/v2dot0/curl/write-compressed.sh b/layouts/shortcodes/api/v2dot0/curl/write-compressed.sh new file mode 100644 index 000000000..a71fd3e60 --- /dev/null +++ b/layouts/shortcodes/api/v2dot0/curl/write-compressed.sh @@ -0,0 +1,9 @@ +curl --request POST "http://localhost:8086/api/v2/write?org=YOUR_ORG&bucket=YOUR_BUCKET&precision=s" \ + --header "Authorization: Token YOURAUTHTOKEN" \ + --header "Content-Encoding: gzip" \ + --data-raw " +mem,host=host1 used_percent=23.43234543 1556896326 +mem,host=host2 used_percent=26.81522361 1556896326 +mem,host=host1 used_percent=22.52984738 1556896336 +mem,host=host2 used_percent=27.18294630 1556896336 +" diff --git a/layouts/shortcodes/api/v2dot0/curl/write.sh b/layouts/shortcodes/api/v2dot0/curl/write.sh new file mode 100644 index 000000000..1dc9f9e71 --- /dev/null +++ b/layouts/shortcodes/api/v2dot0/curl/write.sh @@ -0,0 +1,8 @@ +curl --request POST "http://localhost:8086/api/v2/write?org=YOUR_ORG&bucket=YOUR_BUCKET&precision=s" \ + --header "Authorization: Token YOURAUTHTOKEN" \ + --data-raw " +mem,host=host1 used_percent=23.43234543 1556896326 +mem,host=host2 used_percent=26.81522361 1556896326 +mem,host=host1 used_percent=22.52984738 1556896336 +mem,host=host2 used_percent=27.18294630 1556896336 +" diff --git a/layouts/shortcodes/api/v2dot0/env.sh b/layouts/shortcodes/api/v2dot0/env.sh new file mode 100644 index 000000000..7878b9a65 --- /dev/null +++ b/layouts/shortcodes/api/v2dot0/env.sh @@ -0,0 +1,4 @@ +export INFLUX_URL=http://localhost:8086 +export INFLUX_TOKEN=influxdbauthtoken +export INFLUX_ORG=emailaddress@yourorg.org +export INFLUX_BUCKET=your_data_bucket diff --git a/layouts/shortcodes/api/v2dot0/nodejs/install.md b/layouts/shortcodes/api/v2dot0/nodejs/install.md new file mode 100644 index 000000000..94b109a55 --- /dev/null +++ b/layouts/shortcodes/api/v2dot0/nodejs/install.md @@ -0,0 +1,5 @@ +This library supports browser and server-side (Node.js) Javascript environments. Use the @influxdata/influxdb-client module when targeting Node.js. The module supports both CommonJS and ES Module syntax. + +To use InfluxDB management APIs in your project, also add @influxdata/influxdb-client-apis as a dependency to your project. + +If you target the browser or deno, use @influxdata/influxdb-client-browser. It is UMD-compatible for use with module loaders. See [Javascript (browser)](/influxdb/content/v2.0/api-guide/client-libraries/js-browser) for more information. diff --git a/layouts/shortcodes/api/v2dot0/nodejs/write.mjs b/layouts/shortcodes/api/v2dot0/nodejs/write.mjs index 61562ab46..578bb808d 100644 --- a/layouts/shortcodes/api/v2dot0/nodejs/write.mjs +++ b/layouts/shortcodes/api/v2dot0/nodejs/write.mjs @@ -16,6 +16,10 @@ const bucket = process.env.INFLUX_BUCKET * with a configuration object. **/ const influxDB = new InfluxDB({ url, token }) +/** + * Create a write client from the getWriteApi method. + * Provide your `org` and `bucket`. + **/ const writeApi = influxDB.getWriteApi(org, bucket) /**