From 98d181f51a1d6bbce05516da987eefbd752f2eb5 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 11 Aug 2023 16:25:05 -0500 Subject: [PATCH] feature(v3): Get started writing and querying data with the JS client library (closes #5049, part of #5050) (#5080) --- .../cloud-dedicated/get-started/query.md | 123 ++++++++- .../cloud-dedicated/get-started/write.md | 240 ++++++++++-------- .../cloud-serverless/get-started/query.md | 124 ++++++++- .../cloud-serverless/get-started/write.md | 236 +++++++++-------- 4 files changed, 508 insertions(+), 215 deletions(-) diff --git a/content/influxdb/cloud-dedicated/get-started/query.md b/content/influxdb/cloud-dedicated/get-started/query.md index 8f0b82a98..122ecfe60 100644 --- a/content/influxdb/cloud-dedicated/get-started/query.md +++ b/content/influxdb/cloud-dedicated/get-started/query.md @@ -201,6 +201,7 @@ credentials (**URL**, **organization**, and **token**) are provided by [influx3 CLI](#influx3-cli) [Python](#) [Go](#) +[Node.js](#) [C#](#) [Java](#) {{% /tabs %}} @@ -580,6 +581,121 @@ _If your project's virtual environment is already running, skip to step 3._ {{% /tab-content %}} {{% tab-content %}} +{{% influxdb/custom-timestamps %}} + + +_This tutorial assumes you installed Node.js and npm, and created an `influxdb_js_client` npm project as described in the [Write data section](/influxdb/cloud-dedicated/get-started/write/?t=Nodejs)._ + +1. In your terminal or editor, change to the `influxdb_js_client` directory you created in the + [Write data section](/influxdb/cloud-dedicated/get-started/write/?t=Nodejs). +2. If you haven't already, install the `@influxdata/influxdb3-client` JavaScript client library as a dependency to your project: + + ```sh + npm install --save @influxdata/influxdb3-client + ``` +3. Create a file named `query.mjs`. The `.mjs` extension tells the Node.js interpreter that you're using [ES6 module syntax](https://nodejs.org/api/esm.html#modules-ecmascript-modules). +4. Inside of `query.mjs`, enter the following sample code: + + ```js + // query.mjs + import {InfluxDBClient} from '@influxdata/influxdb3-client' + import {tableFromArrays} from 'apache-arrow'; + + /** + * Set InfluxDB credentials. + */ + const host = "https://cluster-id.influxdb.io"; + const database = 'get-started'; + /** + * INFLUX_TOKEN is an environment variable you assigned to your + * database READ token value. + */ + const token = process.env.INFLUX_TOKEN; + + /** + * Query InfluxDB with SQL using the JavaScript client library. + */ + export async function querySQL() { + /** + * Instantiate an InfluxDBClient + */ + const client = new InfluxDBClient({host, token}) + const sql = ` + SELECT * + FROM home + WHERE time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' + ` + + const data = {time: [], room: [], co: [], hum: [], temp: []}; + const result = client.query(query, database); + + for await (const row of result) { + data.time.push(new Date(row._time)) + data.room.push(row.room) + data.co.push(row.co); + data.hum.push(row.hum); + data.temp.push(row.temp); + } + + console.table([...tableFromArrays(data)]) + + client.close() + } + + ``` + + The sample code does the following: + + 1. Imports the following: + - `InfluxDBClient` class + - `tableFromArrays` function + 2. Calls `new InfluxDBClient()` and passes a `ClientOptions` object to instantiate a client configured + with InfluxDB credentials. + + - **`host`**: your {{% cloud-name %}} cluster URL + - **`token`**: an [database token](/influxdb/cloud-dedicated/admin/tokens/) with _read_ access to the specified database. + _Store this in a secret store or environment variable to avoid exposing the raw token string._ + + 3. Defines a string variable (`sql`) for the SQL query. + 4. Defines an object (`data`) with column names for keys and array values for storing row data. + 5. Calls the `InfluxDBClient.query()` method with the following arguments: + + - **`sql`**: the query to execute + - **`database`**: the name of the {{% cloud-name %}} database to query + + `query()` returns a stream of row vectors. + 6. Iterates over rows and adds the column data to the arrays in `data`. + 7. Passes `data` to the Arrow `tableFromArrays()` function to format the arrays as a table, and then passes the result to the `console.table()` method to output a highlighted table in the terminal. +5. Inside of `index.mjs` (created in the [Write data section](/influxdb/cloud-dedicated/get-started/write/?t=Nodejs)), enter the following sample code to import the modules and call the functions: + + ```js + // index.mjs + import { writeLineProtocol } from "./write.mjs"; + import { querySQL } from "./query.mjs"; + + /** + * Execute the client functions. + */ + async function main() { + /** Write line protocol data to InfluxDB. */ + await writeLineProtocol(); + /** Query data from InfluxDB using SQL. */ + await querySQL(); + } + + main(); + ``` + +9. In your terminal, execute `index.mjs` to write to and query {{% cloud-name %}}: + + ```sh + node index.mjs + ``` + +{{% /influxdb/custom-timestamps %}} +{{% /tab-content %}} +{{% tab-content %}} {{% influxdb/custom-timestamps %}} @@ -612,7 +728,7 @@ _If your project's virtual environment is already running, skip to step 3._ string? database = "get-started"; /** INFLUX_TOKEN is an environment variable you assigned to your - * database token value. + * database READ token value. **/ string? authToken = System.Environment .GetEnvironmentVariable("INFLUX_TOKEN"); @@ -708,7 +824,7 @@ _If your project's virtual environment is already running, skip to step 3._ {{% influxdb/custom-timestamps %}} -_This tutorial assumes using Maven version 3.9, Java version >= 15, and a `influxdb_java_client` Maven project created in the [Write data section](/influxdb/cloud-dedicated/get-started/write/?t=Java)._ +_This tutorial assumes using Maven version 3.9, Java version >= 15, and an `influxdb_java_client` Maven project created in the [Write data section](/influxdb/cloud-dedicated/get-started/write/?t=Java)._ 1. In your terminal or editor, change to the `influxdb_java_client` directory you created in the [Write data section](/influxdb/cloud-dedicated/get-started/write/?t=Java). @@ -745,7 +861,7 @@ _This tutorial assumes using Maven version 3.9, Java version >= 15, and a `influ final String database = "get-started"; /** INFLUX_TOKEN is an environment variable you assigned to your - * database token value. + * database READ token value. **/ final char[] authToken = (System.getenv("INFLUX_TOKEN")). toCharArray(); @@ -862,6 +978,7 @@ _This tutorial assumes using Maven version 3.9, Java version >= 15, and a `influ {{% /influxdb/custom-timestamps %}} {{% /tab-content %}} + {{< /tabs-wrapper >}} ### Query results diff --git a/content/influxdb/cloud-dedicated/get-started/write.md b/content/influxdb/cloud-dedicated/get-started/write.md index 8b525842a..549cd2c70 100644 --- a/content/influxdb/cloud-dedicated/get-started/write.md +++ b/content/influxdb/cloud-dedicated/get-started/write.md @@ -310,7 +310,7 @@ To write data to {{% cloud-name %}} using Python, use the The following steps include setting up a Python virtual environment to scope dependencies to your current project. -1. Create a new module directory and navigate into it--for example: +1. Create a module directory and navigate into it--for example: ```sh mkdir influxdb_py_client && cd $_ @@ -350,7 +350,7 @@ dependencies to your current project. import os # INFLUX_TOKEN is an environment variable you assigned to your - # database token value. + # database WRITE token value. token = os.getenv('INFLUX_TOKEN') # host is the URL without protocol or trailing slash @@ -466,7 +466,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu func WriteLineProtocol() error { url := "https://cluster-id.influxdb.io" // INFLUX_TOKEN is an environment variable you assigned to your - // database token value. + // database WRITE token value. token := os.Getenv("INFLUX_TOKEN") database := os.Getenv("INFLUX_DATABASE") @@ -562,7 +562,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu write client's `Write()` method to write each line of line protocol separately to InfluxDB. -4. In your editor, create a `main.go` file and enter the following sample code that calls the `WriteLineProtocol()` function: +5. In your editor, create a `main.go` file and enter the following sample code that calls the `WriteLineProtocol()` function: ```go package main @@ -573,7 +573,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu } ``` -5. In your terminal, enter the following command to install the packages listed in `imports`, build the `influxdb_go_client` module, and execute the `main()` function: +6. In your terminal, enter the following command to install the packages listed in `imports`, build the `influxdb_go_client` module, and execute the `main()` function: ```sh go mod tidy && go build && go run influxdb_go_client @@ -585,134 +585,157 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu {{% /tab-content %}} {{% tab-content %}} - {{% influxdb/custom-timestamps %}} + -To write data to {{% cloud-name %}} using Node.js, use the -[influxdb-client-js package](https://github.com/influxdata/influxdb-client-js). - -1. Inside of your project directory, create an NPM or Yarn package and install - the `@influxdata/influxdb-client` InfluxDB v2 JavaScript client library. +1. If you haven't already, follow the instructions for [Downloading and installing Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) for your system. +2. In your terminal, enter the following command to create a `influxdb_js_client` project and `package.json` file: ```sh - npm init -y && npm install --save @influxdata/influxdb-client + npm init -y -w influxdb_js_client ``` -2. In your terminal or editor, create a new file for your code--for example: `write.js`. +3. Change into the `influxdb_js_client` directory. ```sh - touch write.js + cd influxdb_js_client ``` +4. Install the `@influxdata/influxdb3-client` JavaScript client library as a dependency to your project: -3. Inside of `write.js`, enter the following sample code: + ```sh + npm install --save @influxdata/influxdb3-client + ``` +5. In your terminal or editor, create a `write.mjs` file. The `.mjs` extension tells the Node.js interpreter that this is an [ES6 module](https://nodejs.org/api/esm.html#modules-ecmascript-modules). +6. Inside of `write.mjs`, enter the following sample code: ```js - 'use strict' - /** @module write - * Writes line protocol strings to InfluxDB using the JavaScript client - * library with Node.js. - **/ - import {InfluxDB} from '@influxdata/influxdb-client'; + // write.mjs + import { InfluxDBClient } from "@influxdata/influxdb3-client"; - /** Get credentials from environment variables. **/ - const url = process.env.INFLUX_URL; + /** + * Set InfluxDB credentials. + */ + const host = "https://cluster-id.influxdb.io"; + const database = "get-started"; + /** + * INFLUX_TOKEN is an environment variable you assigned to your + * database WRITE token value. + */ const token = process.env.INFLUX_TOKEN; - const org = process.env.INFLUX_ORG; /** - * Instantiate the InfluxDB client with a configuration object. - **/ - const influxDB = new InfluxDB({url, token}); - - /** - * Define an array of line protocol strings to write. - * Include an additional backslash to preserve backslashes - * and prevent interpretation of escape sequences---for example, - * escaped spaces in tag values. + * Write line protocol to InfluxDB using the JavaScript client library. */ - const lines = [ - 'home,room=Living\\ Room temp=21.1,hum=35.9,co=0i 1641024000', - 'home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000', - 'home,room=Living\\ Room temp=21.4,hum=35.9,co=0i 1641027600', - 'home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600', - 'home,room=Living\\ Room temp=21.8,hum=36.0,co=0i 1641031200', - 'home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200', - 'home,room=Living\\ Room temp=22.2,hum=36.0,co=0i 1641034800', - 'home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800', - 'home,room=Living\\ Room temp=22.2,hum=35.9,co=0i 1641038400', - 'home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400', - 'home,room=Living\\ Room temp=22.4,hum=36.0,co=0i 1641042000', - 'home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000', - 'home,room=Living\\ Room temp=22.3,hum=36.1,co=0i 1641045600', - 'home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600', - 'home,room=Living\\ Room temp=22.3,hum=36.1,co=1i 1641049200', - 'home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200', - 'home,room=Living\\ Room temp=22.4,hum=36.0,co=4i 1641052800', - 'home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800', - 'home,room=Living\\ Room temp=22.6,hum=35.9,co=5i 1641056400', - 'home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400', - 'home,room=Living\\ Room temp=22.8,hum=36.2,co=9i 1641060000', - 'home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000', - 'home,room=Living\\ Room temp=22.5,hum=36.3,co=14i 1641063600', - 'home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600', - 'home,room=Living\\ Room temp=22.2,hum=36.4,co=17i 1641067200', - 'home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200', - ]; + export async function writeLineProtocol() { + /** + * Instantiate an InfluxDBClient + */ + const client = new InfluxDBClient({ host, token }); - /** - * Create a write client from the getWriteApi method. - * Provide your org and database. - **/ - const writeApi = influxDB.getWriteApi(org, 'get-started', 's'); + /** + * Define line protocol records to write. + */ + const records = [ + `home,room=Living\\ Room temp=21.1,hum=35.9,co=0i 1641124000`, + `home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641124000`, + `home,room=Living\\ Room temp=21.4,hum=35.9,co=0i 1641127600`, + `home,room=Kitchen temp=23.0,hum=36.2,co=0 1641127600`, + `home,room=Living\\ Room temp=21.8,hum=36.0,co=0i 1641131200`, + `home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641131200`, + `home,room=Living\\ Room temp=22.2,hum=36.0,co=0i 1641134800`, + `home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641134800`, + `home,room=Living\\ Room temp=22.2,hum=35.9,co=0i 1641138400`, + `home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641138400`, + `home,room=Living\\ Room temp=22.4,hum=36.0,co=0i 1641142000`, + `home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641142000`, + `home,room=Living\\ Room temp=22.3,hum=36.1,co=0i 1641145600`, + `home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641145600`, + `home,room=Living\\ Room temp=22.3,hum=36.1,co=1i 1641149200`, + `home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641149200`, + `home,room=Living\\ Room temp=22.4,hum=36.0,co=4i 1641152800`, + `home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641152800`, + `home,room=Living\\ Room temp=22.6,hum=35.9,co=5i 1641156400`, + `home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641156400`, + `home,room=Living\\ Room temp=22.8,hum=36.2,co=9i 1641160000`, + `home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641160000`, + `home,room=Living\\ Room temp=22.5,hum=36.3,co=14i 1641163600`, + `home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641163600`, + `home,room=Living\\ Room temp=22.2,hum=36.4,co=17i 1641167200`, + `home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641167200`, + ]; - /** - * Write line protocol to the batch - */ - writeApi.writeRecords(lines); + /** + * Creates an array that contains separate write request promises + * for all the records. + */ + const writePromises = records.map((record) => { + return client.write(record, database, "", { precision: "s" }) + .then(() => `Data has been written successfully: ${record}`, + () => `Failed writing data: ${record}`); + }); - /** - * Flush pending writes from the buffer and close the write client. - **/ - writeApi.close().then( - () => { - console.log('Data has been written successfully.'); - }, - (err) => { - console.log('Error writing line protocol'); - } - ); + /** + * Wait for all the write promises to settle, and then output the results. + */ + const writeResults = await Promise.allSettled(writePromises); + writeResults.forEach(write => console.log(write.value)); + + /** Close the client to release resources. */ + await client.close(); + } ``` - The sample does the following: + The sample code does the following: - 1. Calls the `new InfluxDB()` constructor to instantiate a client configured - with the InfluxDB URL and database token. + 1. Imports the `InfluxDBClient` class. + 2. Calls the `new InfluxDBClient()` constructor and passes a `ClientOptions` object to instantiate a client configured + with InfluxDB credentials. - 2. Defines an array of line protocol strings where each string represents a data record. + - **`host`**: your {{% cloud-name %}} cluster URL + - **`token`**: an [database token](/influxdb/cloud-dedicated/admin/tokens/) with _write_ access to the specified database. + _Store this in a secret store or environment variable to avoid exposing the raw token string._ - 3. Calls the client's `getWriteApi()` method to create a - **write client** configured to write to the database - (the method requires an `org` argument, but InfluxDB ignores it). + 3. Defines a list of line protocol strings where each string represents a data record. + 4. Calls the client's `write()` method for each record, defines the success or failure message to return, and collects the pending promises into the `writePromises` array. + Each call to `write()` passes the following arguments: + + - **`record`**: the line protocol record + - **`database`**: the name of the {{% cloud-name %}} database to write to + - **`{precision}`**: a `WriteOptions` object that sets the `precision` value. - **Because the timestamps in the sample line protocol are in second - precision, the example passes `'s'` for the `precision` option in order - to set the[timestamp precision](/influxdb/cloud-dedicated/reference/glossary/#timestamp-precision) to seconds**. + **Because the timestamps in the sample line protocol are in second + precision, the example passes `s` as the `precision` value to set the write + [timestamp precision](/influxdb/cloud-dedicated/reference/glossary/#timestamp-precision) to seconds.** - 6. Calls the write client's `writeRecords()` method with the line protocol array - to write the records in batches to InfluxDB. + 5. Calls `Promise.allSettled()` with the promises array to pause execution until the promises have completed, and then assigns the array containing success and failure messages to a `writeResults` constant. + 7. Iterates over and prints the messages in `writeResults`. + 8. Closes the client to release resources. +7. In your terminal or editor, create an `index.mjs` file. +8. Inside of `index.mjs`, enter the following sample code to import and call `writeLineProtocol()`: - 7. Calls the write client's `close()` method with callback functions for success and error. - The `close()` method sends any records remaining in the buffer, - executes callbacks, and releases resources. + ```js + // index.mjs + import { writeLineProtocol } from "./write.mjs"; + + /** + * Execute the client functions. + */ + async function main() { + /** Write line protocol data to InfluxDB. */ + await writeLineProtocol(); + } + + main(); + ``` + +9. In your terminal, execute `index.mjs` to write to {{% cloud-name %}}: -4. To execute the file and write the line protocol to your {{% cloud-name %}} database, - enter the following command in your terminal: - ```sh - node write.js + node index.mjs ``` + {{% /influxdb/custom-timestamps %}} - + {{% /tab-content %}} {{% tab-content %}} @@ -762,7 +785,7 @@ To write data to {{% cloud-name %}} using Node.js, use the /** * INFLUX_TOKEN is an environment variable you assigned to your - * database token value. + * database WRITE token value. */ string? authToken = System.Environment .GetEnvironmentVariable("INFLUX_TOKEN"); @@ -953,7 +976,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._ /** * INFLUX_TOKEN is an environment variable you assigned to your - * database token value. + * database WRITE token value. */ final char[] authToken = (System.getenv("INFLUX_TOKEN")). toCharArray(); @@ -1009,7 +1032,14 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._ The sample code does the following: - 1. Calls `InfluxDBClient.getInstance()` to instantiate a client configured + 1. Imports the following classes: + + - `java.util.List`; + - `com.influxdb.v3.client.InfluxDBClient` + - `com.influxdb.v3.client.write.WriteParameters` + - `com.influxdb.v3.client.write.WritePrecision` + + 2. Calls `InfluxDBClient.getInstance()` to instantiate a client configured with InfluxDB credentials. - **`hostUrl`**: your {{% cloud-name %}} cluster URL @@ -1022,7 +1052,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._ **Because the timestamps in the sample line protocol are in second precision, the example passes the [`WritePrecision.S` enum value](https://github.com/InfluxCommunity/influxdb3-java/blob/main/src/main/java/com/influxdb/v3/client/write/WritePrecision.java) - as the `precision` argument to set the write[timestamp precision](/influxdb/cloud-dedicated/reference/glossary/#timestamp-precision) to seconds.** + as the `precision` argument to set the write [timestamp precision](/influxdb/cloud-dedicated/reference/glossary/#timestamp-precision) to seconds.** 8. In your editor, open the `App.java` file (created by Maven) and replace its contents with the following sample code: diff --git a/content/influxdb/cloud-serverless/get-started/query.md b/content/influxdb/cloud-serverless/get-started/query.md index 9272dff7b..717d27d0f 100644 --- a/content/influxdb/cloud-serverless/get-started/query.md +++ b/content/influxdb/cloud-serverless/get-started/query.md @@ -204,6 +204,7 @@ credentials (**URL**, **organization**, and **token**) are provided by [influx3 CLI](#influx3-cli) [Python](#) [Go](#) +[Node.js](#) [C#](#) [Java](#) {{% /tabs %}} @@ -424,7 +425,7 @@ _If your project's virtual environment is already running, skip to step 3._ 4. Calls the `client.query()` method with the SQL query. `query()` sends a - Flight request to InfluxDB, queries the database, retrieves result data from the endpoint, and then returns a + Flight request to InfluxDB, queries the database (bucket), retrieves result data from the endpoint, and then returns a [`pyarrow.Table`](https://arrow.apache.org/docs/python/generated/pyarrow.Table.html#pyarrow.Table) assigned to the `table` variable. @@ -609,6 +610,121 @@ _If your project's virtual environment is already running, skip to step 3._ {{% /tab-content %}} {{% tab-content %}} +{{% influxdb/custom-timestamps %}} + + +_This tutorial assumes you installed Node.js and npm, and created an `influxdb_js_client` npm project as described in the [Write data section](/influxdb/cloud-serverless/get-started/write/?t=Nodejs)._ + +1. In your terminal or editor, change to the `influxdb_js_client` directory you created in the + [Write data section](/influxdb/cloud-serverless/get-started/write/?t=Nodejs). +2. If you haven't already, install the `@influxdata/influxdb3-client` JavaScript client library as a dependency to your project: + + ```sh + npm install --save @influxdata/influxdb3-client + ``` +3. Create a file named `query.mjs`. The `.mjs` extension tells the Node.js interpreter that you're using [ES6 module syntax](https://nodejs.org/api/esm.html#modules-ecmascript-modules). +4. Inside of `query.mjs`, enter the following sample code: + + ```js + // query.mjs + import {InfluxDBClient} from '@influxdata/influxdb3-client' + import {tableFromArrays} from 'apache-arrow'; + + /** + * Set InfluxDB credentials. + */ + const host = "https://cloud2.influxdata.com"; + const database = 'get-started'; + /** + * INFLUX_TOKEN is an environment variable you assigned to your + * API READ token value. + */ + const token = process.env.INFLUX_TOKEN; + + /** + * Query InfluxDB with SQL using the JavaScript client library. + */ + export async function querySQL() { + /** + * Instantiate an InfluxDBClient + */ + const client = new InfluxDBClient({host, token}) + const sql = ` + SELECT * + FROM home + WHERE time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z' + ` + + const data = {time: [], room: [], co: [], hum: [], temp: []}; + const result = client.query(query, database); + + for await (const row of result) { + data.time.push(new Date(row._time)) + data.room.push(row.room) + data.co.push(row.co); + data.hum.push(row.hum); + data.temp.push(row.temp); + } + + console.table([...tableFromArrays(data)]) + + client.close() + } + + ``` + + The sample code does the following: + + 1. Imports the following: + - `InfluxDBClient` class + - `tableFromArrays` function + 2. Calls `new InfluxDBClient()` and passes a `ClientOptions` object to instantiate a client configured + with InfluxDB credentials. + + - **`host`**: your {{% cloud-name %}} region URL + - **`token`**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the specified bucket. + _Store this in a secret store or environment variable to avoid exposing the raw token string._ + + 3. Defines a string variable (`sql`) for the SQL query. + 4. Defines an object (`data`) with column names for keys and array values for storing row data. + 5. Calls the `InfluxDBClient.query()` method with the following arguments: + + - **`sql`**: the query to execute + - **`database`**: the name of the {{% cloud-name %}} bucket to query + + `query()` returns a stream of row vectors. + 6. Iterates over rows and adds the column data to the arrays in `data`. + 7. Passes `data` to the Arrow `tableFromArrays()` function to format the arrays as a table, and then passes the result to the `console.table()` method to output a highlighted table in the terminal. +5. Inside of `index.mjs` (created in the [Write data section](/influxdb/cloud-serverless/get-started/write/?t=Nodejs)), enter the following sample code to import the modules and call the functions: + + ```js + // index.mjs + import { writeLineProtocol } from "./write.mjs"; + import { querySQL } from "./query.mjs"; + + /** + * Execute the client functions. + */ + async function main() { + /** Write line protocol data to InfluxDB. */ + await writeLineProtocol(); + /** Query data from InfluxDB using SQL. */ + await querySQL(); + } + + main(); + ``` + +9. In your terminal, execute `index.mjs` to write to and query {{% cloud-name %}}: + + ```sh + node index.mjs + ``` + +{{% /influxdb/custom-timestamps %}} +{{% /tab-content %}} +{{% tab-content %}} {{% influxdb/custom-timestamps %}} @@ -641,7 +757,7 @@ _If your project's virtual environment is already running, skip to step 3._ string? database = "get-started"; /** INFLUX_TOKEN is an environment variable you assigned to your - * API token value. + * API READ token value. **/ string? authToken = System.Environment .GetEnvironmentVariable("INFLUX_TOKEN"); @@ -774,7 +890,7 @@ _This tutorial assumes using Maven version 3.9, Java version >= 15, and a `influ final String database = "get-started"; /** INFLUX_TOKEN is an environment variable you assigned to your - * API token value. + * API READ token value. **/ final char[] authToken = (System.getenv("INFLUX_TOKEN")). toCharArray(); @@ -821,7 +937,7 @@ _This tutorial assumes using Maven version 3.9, Java version >= 15, and a `influ 1. Calls `InfluxDBClient.getInstance()` to instantiate a client configured with InfluxDB credentials. - - **`hostUrl`**: your {{% cloud-name %}} cluster URL + - **`hostUrl`**: your {{% cloud-name %}} region URL - **`database`**: the name of the {{% cloud-name %}} bucket to write to - **`authToken`**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the specified bucket. _Store this in a secret store or environment variable to avoid exposing the raw token string._ diff --git a/content/influxdb/cloud-serverless/get-started/write.md b/content/influxdb/cloud-serverless/get-started/write.md index f533599a7..2cde44ce6 100644 --- a/content/influxdb/cloud-serverless/get-started/write.md +++ b/content/influxdb/cloud-serverless/get-started/write.md @@ -388,7 +388,7 @@ To write data to {{% cloud-name %}} using Python, use the The following steps include setting up a Python virtual environment to scope dependencies to your current project. -1. Create a new module directory and navigate into it--for example: +1. Create a module directory and navigate into it--for example: ```sh mkdir influxdb_py_client && cd $_ @@ -428,7 +428,7 @@ dependencies to your current project. import os # INFLUX_TOKEN is an environment variable you assigned to your - # API token value. + # API WRITE token value. token = os.getenv('INFLUX_TOKEN') # host is the URL without protocol or trailing slash @@ -542,7 +542,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu func WriteLineProtocol() error { url := "https://cloud2.influxdata.com" // INFLUX_TOKEN is an environment variable you assigned to your - // API token value. + // API WRITE token value. token := os.Getenv("INFLUX_TOKEN") database := os.Getenv("INFLUX_DATABASE") @@ -649,7 +649,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu } ``` -5. In your terminal, enter the following command to install the packages listed in `imports`, build the `influxdb_go_client` module, and execute the `main()` function: +6. In your terminal, enter the following command to install the packages listed in `imports`, build the `influxdb_go_client` module, and execute the `main()` function: ```sh go mod tidy && go build && go run influxdb_go_client @@ -661,134 +661,157 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu {{% /tab-content %}} {{% tab-content %}} - {{% influxdb/custom-timestamps %}} + -To write data to {{% cloud-name %}} using Node.js, use the -[influxdb-client-js package](https://github.com/influxdata/influxdb-client-js). - -1. Inside of your project directory, create an NPM or Yarn package and install - the `@influxdata/influxdb-client` InfluxDB v2 JavaScript client library. +1. If you haven't already, follow the instructions for [Downloading and installing Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) for your system. +2. In your terminal, enter the following command to create a `influxdb_js_client` project and `package.json` file: ```sh - npm init -y && npm install --save @influxdata/influxdb-client + npm init -y -w influxdb_js_client ``` -2. In your terminal or editor, create a new file for your code--for example: `write.js`. +3. Change into the `influxdb_js_client` directory. ```sh - touch write.js + cd influxdb_js_client ``` +4. Install the `@influxdata/influxdb3-client` JavaScript client library as a dependency to your project: -3. Inside of `write.js`, enter the following sample code: + ```sh + npm install --save @influxdata/influxdb3-client + ``` +5. In your terminal or editor, create a `write.mjs` file. The `.mjs` extension tells the Node.js interpreter that this is an [ES6 module](https://nodejs.org/api/esm.html#modules-ecmascript-modules). +6. Inside of `write.mjs`, enter the following sample code: ```js - 'use strict' - /** @module write - * Writes line protocol strings to InfluxDB using the JavaScript client - * library with Node.js. - **/ - import {InfluxDB} from '@influxdata/influxdb-client'; + // write.mjs + import { InfluxDBClient } from "@influxdata/influxdb3-client"; - /** Get credentials from environment variables. **/ - const url = process.env.INFLUX_URL; + /** + * Set InfluxDB credentials. + */ + const host = "https://cloud2.influxdata.com"; + const database = "get-started"; + /** + * INFLUX_TOKEN is an environment variable you assigned to your + * API WRITE token value. + */ const token = process.env.INFLUX_TOKEN; - const org = process.env.INFLUX_ORG; /** - * Instantiate the InfluxDB client with a configuration object. - **/ - const influxDB = new InfluxDB({url, token}); - - /** - * Define an array of line protocol strings to write. - * Include an additional backslash to preserve backslashes - * and prevent interpretation of escape sequences---for example, - * escaped spaces in tag values. + * Write line protocol to InfluxDB using the JavaScript client library. */ - const lines = [ - 'home,room=Living\\ Room temp=21.1,hum=35.9,co=0i 1641024000', - 'home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000', - 'home,room=Living\\ Room temp=21.4,hum=35.9,co=0i 1641027600', - 'home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600', - 'home,room=Living\\ Room temp=21.8,hum=36.0,co=0i 1641031200', - 'home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200', - 'home,room=Living\\ Room temp=22.2,hum=36.0,co=0i 1641034800', - 'home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800', - 'home,room=Living\\ Room temp=22.2,hum=35.9,co=0i 1641038400', - 'home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400', - 'home,room=Living\\ Room temp=22.4,hum=36.0,co=0i 1641042000', - 'home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000', - 'home,room=Living\\ Room temp=22.3,hum=36.1,co=0i 1641045600', - 'home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600', - 'home,room=Living\\ Room temp=22.3,hum=36.1,co=1i 1641049200', - 'home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200', - 'home,room=Living\\ Room temp=22.4,hum=36.0,co=4i 1641052800', - 'home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800', - 'home,room=Living\\ Room temp=22.6,hum=35.9,co=5i 1641056400', - 'home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400', - 'home,room=Living\\ Room temp=22.8,hum=36.2,co=9i 1641060000', - 'home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000', - 'home,room=Living\\ Room temp=22.5,hum=36.3,co=14i 1641063600', - 'home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600', - 'home,room=Living\\ Room temp=22.2,hum=36.4,co=17i 1641067200', - 'home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200', - ]; + export async function writeLineProtocol() { + /** + * Instantiate an InfluxDBClient + */ + const client = new InfluxDBClient({ host, token }); - /** - * Create a write client from the getWriteApi method. - * Provide your org and bucket. - **/ - const writeApi = influxDB.getWriteApi(org, 'get-started', 's'); + /** + * Define line protocol records to write. + */ + const records = [ + `home,room=Living\\ Room temp=21.1,hum=35.9,co=0i 1641124000`, + `home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641124000`, + `home,room=Living\\ Room temp=21.4,hum=35.9,co=0i 1641127600`, + `home,room=Kitchen temp=23.0,hum=36.2,co=0 1641127600`, + `home,room=Living\\ Room temp=21.8,hum=36.0,co=0i 1641131200`, + `home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641131200`, + `home,room=Living\\ Room temp=22.2,hum=36.0,co=0i 1641134800`, + `home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641134800`, + `home,room=Living\\ Room temp=22.2,hum=35.9,co=0i 1641138400`, + `home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641138400`, + `home,room=Living\\ Room temp=22.4,hum=36.0,co=0i 1641142000`, + `home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641142000`, + `home,room=Living\\ Room temp=22.3,hum=36.1,co=0i 1641145600`, + `home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641145600`, + `home,room=Living\\ Room temp=22.3,hum=36.1,co=1i 1641149200`, + `home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641149200`, + `home,room=Living\\ Room temp=22.4,hum=36.0,co=4i 1641152800`, + `home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641152800`, + `home,room=Living\\ Room temp=22.6,hum=35.9,co=5i 1641156400`, + `home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641156400`, + `home,room=Living\\ Room temp=22.8,hum=36.2,co=9i 1641160000`, + `home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641160000`, + `home,room=Living\\ Room temp=22.5,hum=36.3,co=14i 1641163600`, + `home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641163600`, + `home,room=Living\\ Room temp=22.2,hum=36.4,co=17i 1641167200`, + `home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641167200`, + ]; - /** - * Write line protocol to the batch - */ - writeApi.writeRecords(lines); + /** + * Creates an array that contains separate write request promises + * for all the records. + */ + const writePromises = records.map((record) => { + return client.write(record, database, "", { precision: "s" }) + .then(() => `Data has been written successfully: ${record}`, + () => `Failed writing data: ${record}`); + }); - /** - * Flush pending writes from the buffer and close the write client. - **/ - writeApi.close().then( - () => { - console.log('Data has been written successfully.'); - }, - (err) => { - console.log('Error writing line protocol'); - } - ); + /** + * Wait for all the write promises to settle, and then output the results. + */ + const writeResults = await Promise.allSettled(writePromises); + writeResults.forEach(write => console.log(write.value)); + + /** Close the client to release resources. */ + await client.close(); + } ``` - The sample does the following: + The sample code does the following: - 1. Calls the `new InfluxDB()` constructor to instantiate a client configured - with the InfluxDB URL and API token. + 1. Imports the `InfluxDBClient` class. + 2. Calls the `new InfluxDBClient()` constructor and passes a `ClientOptions` object to instantiate a client configured + with InfluxDB credentials. - 2. Defines an array of line protocol strings where each string represents a data record. + - **`host`**: your {{% cloud-name %}} region URL + - **`token`**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _write_ access to the specified bucket. + _Store this in a secret store or environment variable to avoid exposing the raw token string._ - 3. Calls the client's `getWriteApi()` method to create a - **write client** configured to write to the bucket - (the method requires an `org` argument, but InfluxDB ignores it). + 3. Defines a list of line protocol strings where each string represents a data record. + 4. Calls the client's `write()` method for each record, defines the success or failure message to return, and collects the pending promises into the `writePromises` array. + Each call to `write()` passes the following arguments: + + - **`record`**: the line protocol record + - **`database`**: the name of the {{% cloud-name %}} bucket to write to + - **`{precision}`**: a `WriteOptions` object that sets the `precision` value. - **Because the timestamps in the sample line protocol are in second - precision, the example passes `'s'` for the `precision` option in order - to set the [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) to seconds**. + **Because the timestamps in the sample line protocol are in second + precision, the example passes `s` as the `precision` value to set the write + [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) to seconds.** - 6. Calls the write client's `writeRecords()` method with the line protocol array - to write the records in batches to InfluxDB. + 5. Calls `Promise.allSettled()` with the promises array to pause execution until the promises have completed, and then assigns the array containing success and failure messages to a `writeResults` constant. + 7. Iterates over and prints the messages in `writeResults`. + 8. Closes the client to release resources. +7. In your terminal or editor, create an `index.mjs` file. +8. Inside of `index.mjs`, enter the following sample code to import and call `writeLineProtocol()`: - 7. Calls the write client's `close()` method with callback functions for success and error. - The `close()` method sends any records remaining in the buffer, - executes callbacks, and releases resources. + ```js + // index.mjs + import { writeLineProtocol } from "./write.mjs"; + + /** + * Execute the client functions. + */ + async function main() { + /** Write line protocol data to InfluxDB. */ + await writeLineProtocol(); + } + + main(); + ``` + +9. In your terminal, execute `index.mjs` to write to {{% cloud-name %}}: -4. To execute the file and write the line protocol to your {{% cloud-name %}} bucket, - enter the following command in your terminal: - ```sh - node write.js + node index.mjs ``` + {{% /influxdb/custom-timestamps %}} - + {{% /tab-content %}} {{% tab-content %}} @@ -838,7 +861,7 @@ To write data to {{% cloud-name %}} using Node.js, use the /** * INFLUX_TOKEN is an environment variable you assigned to your - * API token value. + * API WRITE token value. */ string? authToken = System.Environment .GetEnvironmentVariable("INFLUX_TOKEN"); @@ -1027,7 +1050,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._ /** * INFLUX_TOKEN is an environment variable you assigned to your - * database token value. + * API WRITE token value. */ final char[] authToken = (System.getenv("INFLUX_TOKEN")). toCharArray(); @@ -1083,7 +1106,14 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._ The sample code does the following: - 1. Calls `InfluxDBClient.getInstance()` to instantiate a client configured + 1. Imports the following classes: + + - `java.util.List`; + - `com.influxdb.v3.client.InfluxDBClient` + - `com.influxdb.v3.client.write.WriteParameters` + - `com.influxdb.v3.client.write.WritePrecision` + + 2. Calls `InfluxDBClient.getInstance()` to instantiate a client configured with InfluxDB credentials. - **`hostUrl`**: the {{% cloud-name %}} region URL